Changelog¶
What changed in each release of the driver. Entries under Breaking need source changes in code that used the affected API.
[Unreleased]¶
Changed¶
- The repository moved to kokeb-labs-drivers; URLs follow.
- The Hardware page draws the chip from the new
docs/hardware.yml: the TSSOP-14 pinout with each pin's port hook, the block diagram of Figure 2, the minimum circuit of Figure 61 (5 V) and the 3.3 V supply option of Figure 11, and the pin and parts tables, every fact with its datasheet section and page. TEST, which Figure 4 gives no pin type, is marked as not confirmed. The hand-written pin table is gone. - The
hardware-lessons-reviewskill andtools/preflight.shfollow the template.
[0.1.0] - 2026-11-09¶
Breaking¶
- A reset of the chip is reported as the new
Error::DeviceReset(23). When an ERRFL read after start-up holds OffCompNotFinished or WDTST, the driver reads DISABLE to ECC (14 frames) and compares them with what it last wrote or read there; on a difference, or when that read cannot be completed, the call (an angle or register read, a setter,ReadErrorFlags()) fails withDeviceResetinstead ofDeviceFault, and the driver is uninitialised untilEnsureInitialized()writes the configuration again. Before, a power-on reset that reloaded the OTP went unnoticed: the angle moved with the lost zero and direction, the reads succeeded andGetConfig()still showed the old settings. AswitchoverErrorwith-Wswitch-enumneeds the new case. - A failed settings write is read back, not assumed. A write whose reply failed (a CRC error, a lost frame, an
error flag, a read-back mismatch) may still have reached the chip.
ApplyConfig()and the setters used to restore the old configuration inGetConfig(). Now they read DISABLE to ECC back (14 frames) andGetConfig()takes every chip field from what the chip holds. The write is never retried. When that read fails too, the driver is uninitialised andEnsureInitialized()writes the configuration again. A failedWriteRegister()to a settings register reads the registers back the same way, for the reset check. - An angle or velocity under a magnet warning is refused. When the reply carries the warning bit and ERRFL holds
AGC_warning or MagHalf,
ReadAngleCounts(),ReadUncompensatedAngleCounts(),ReadAngleDegrees(),ReadAngleRadians()and the velocity reads fail with the newError::MagnetWarninginstead of returning the value (handbook KB-CPP-127): the chip says the field is out of the range it regulates. Before, warnings never failed a read. A P2RAM single-bit warning (corrected by the ECC) still returns the value; AGC, magnitude and diagnostics read as before. Such a read costs four frames (the ERRFL read); a read whose reply has no flag bit stays two. - Start-up waits for the chip to be ready.
EnsureInitialized()polls DIA once per millisecond until every loop reports finished, confirmed by a second read, for at most the newConfig::startup_timeout_ms(default 10 ms, t_pon; 0 tokStartupTimeoutMaxMs= 1000). A chip that answers but is not ready fails with the newError::NotReady; before, any non-zero DIA started the driver (handbook KB-CPP-124). - Stuck lines are
NoDevice. A missing chip, MISO stuck low or floating high, a looped-back MOSI or a chip that cannot hear MOSI now fail with the newError::NoDevice(20) instead ofDeviceIdMismatch, at start-up and, for a line pattern with a wrong CRC, an ERRFL with its reserved bit set or an error bit with no error in ERRFL, on later reads (handbook KB-CPP-116, KB-CPP-047).DeviceIdMismatchnow means only that DIA has a bit set that reads 0 on an AS5047U. An absent chip is reported after the start-up deadline (10 ms by default), not at once. - Every port needs
DelayUs(), because start-up polls DIA: a port without it no longer compiles, also when it never callsProgramOtp(). - The port concept checks exact hook signatures and
noexcept. ATransfer()with a length narrower thanstd::size_t, a hook withoutnoexcept, aDelayUs()that does not takeuint32_tor aLog()with another signature is a compile error. ProgramOtp()takes anOtpBurnConfirm.kOtpConfirmis now that type, soProgramOtp(kOtpConfirm, report)compiles unchanged; passing an integer does not compile.Erroris[[nodiscard]]: a call whoseErroris dropped (for exampleValidate(config);) warns.GetConfig()on a temporary driver is deleted (the reference would dangle).
Added¶
CheckForReset(): the same comparison on request, 14 frames, for a periodic check where a reset must not go unnoticed (the datasheet does not promise the ERRFL flag after a reset).ErrorFlags::flags_lost, set inGetLatchedErrorFlags()when a read of ERRFL fails after its command may have reached the chip (a reply CRC error, a failed transfer,NoDevicefor the reserved bit): ERRFL clears when read, so the flags it held may have been missed.ClearLatchedErrorFlags()andEnsureInitialized()clear it. Such a read may have taken a reset's OffCompNotFinished, so it also makes the driver compare the settings registers (14 frames;DeviceReseton a difference). When that compare cannot be read either, it stays pending and every later call fails with its error until it is read: no value is returned while a reset may have gone unseen.- An ERRFL latch: every ERRFL value the driver reads, inside other calls included, is ORed into
GetLatchedErrorFlags()(no I/O) untilClearLatchedErrorFlags()(handbook KB-CPP-119). Before, an internal read overwrote the last value, so a flag could be lost.ReadRegister(reg::kErrfl)feeds it too. GetLastReply(): the raw reply word of the last frame, flag bits included (handbook KB-CPP-129).- The bus requirements as
constexprininc/as5047u_spi_interface.hpp, with datasheet references:kSpiMode(1),kMsbFirst,kMaxClockHz(10 MHz),kMinCsHighNs(350),kCsSetupNs(350),kCsHoldNs(50),kContinuousWord,kFrameBits(handbook KB-CPP-123); the host and ESP32 portsstatic_asserttheir settings, and the ESP32 port refuses a clock above the limit. Config::operator==,reg::NvIndexandreg::At()for the settings array,kPowerOnTimeMs,kStartupTimeoutMaxMs,inc/as5047u_detail.hpp(exact hook probes, enumeration checks).- Strict-dialect builds (handbook KB-CPP20-001):
CMAKE_CXX_EXTENSIONS OFFfor every target,-pedantic-errorsand the C++20 deprecation warnings as errors in the tests, a header self-check per public header (as5047u_header_checks, also in the Cortex-M build), and an ISO C++20 check of the headers inside the ESP-IDF build (examples/esp32/main/as5047u_cxx20_check.cpp). - An independent chip model (handbook KB-TST-030):
tests/mock_as5047u.hppno longer includes the driver's register header or CRC, carries its own map with datasheet figures, a virtual clock with t_pon and four line modes (stuck low, floating high, looped back, deaf);tests/test_model.cppcross-checks the two maps. New tests for start-up, line patterns, the latch and the magnet warning; new compile-fail tests for narrowed, throwing and misdeclared hooks and an integer OTP confirmation. The fuzzer breaks lines, replays stale replies, holds magnet warnings and delays the chip's ready, and checks that no broken line gives a start-up or an angle. -
The review skills
cpp20-profile,misra-reviewandhardware-lessons-reviewand thesafety-revieweragent, from the driver template; CI runs the handbook's source checks. -
clang-tidy runs the CERT C++ checks (
cert-*) as well; the library code had no finding. -
The
Log()hook is documented asvoid Log(LogLevel, const char* message): the message is plain text, and the examples print it with"%s"instead of using it as a format string (no C variadic function, CERT DCL50-CPP; no format string from data). A port with the old variadic signature still compiles. -
AS5047U driver, first version:
as5047u::AS5047U<Port>over an SPI port (mode 1) with 16-bit, 24-bit (CRC-8, default) and 32-bit frames; writes always CRC-protected. - One start-up entry point: the constructor stores the configuration with no I/O,
EnsureInitialized()starts the chip once (and again after a failure orDeinitialize()), and no read or write starts it as a side effect. - Reads of the angle (counts, degrees, radians, uncompensated), velocity (counts, °/s, RPM), AGC, magnitude, DIA
and ERRFL; each reply's error bit resolved through ERRFL into
Crc,Framing,CommandorDeviceFault. - Every setting as a
Configfield (Config{}is an unprogrammed part);write_settings = falsereads a burned part's settings intoGetConfig().SetZeroHere(),SetZeroPosition(),SetDirection(), raw register access. ProgramOtp(kOtpConfirm, report): the datasheet OTP procedure, steps 6 to 19, CRC frames throughout, reporting the failing step and whether the burn started.- Kconfig options for the frame format, direction and DAEC; host and ESP32 examples; an OTP page.
- A libFuzzer target over corrupted, lost and replaced replies (
tests/fuzz/,-DAS5047U_BUILD_FUZZERS=ON); its corpus replays as a CTest on every compiler, and CI fuzzes every pull request.
Changed¶
- The
misra-review,cpp20-profileandnew-driver-from-templateskills anddocs/repo-setup.mdfollow the template: reading the MISRA report, the known tool misfires, enumeration ranges without a sentinel, and the settings tool. tools/preflight.shand theverifyandhardware-lessons-reviewskills follow the template: every check CI runs that a workstation can run, in one command, and the rules for device resets, faults the chip clears itself, dropped writes, switch-offs that no uncertainty refuses and a model that changes state on its own.- Follows the driver template's portable ownership: copyright belongs to
The driver-as5047u authors(LICENSE, every source header,driver.ymlauthors, the docs footer).tools/check_standalone.pyruns in the Handbook source checks job and keeps the code and docs about this chip only.AGENTS.mdfollows the template's structure; the issue and PR templates ask for the board, MCU and port in one field. - The port concepts match each hook's address against exactly one
noexceptsignature withdetail::ExactHook<Port, Sig>::Take(&Port::Hook)instead of probing it with a convertingdetail::Exactly<T>: no conversion operator is left. A misdeclared hook is still a compile error.kAlwaysFalsetakes a class and the enumeration helpers an enumeration (ClassType,Enumeration), each with a compile-fail test. Crc8()is table-driven: a 256-byteconstexprtable built and checked at compile time against the bitwise definition, two lookups per word. On the host the 24-bit angle read is faster (docs/architecture.md); the 16-bit read has no CRC and is unchanged within measurement noise.- Register work is done in
uint32_tand narrowed once (MISRA C++:2023 Rule 7.0.5, KB-CPP20-021, -022); the settings encoder and decoder are freeconstexprfunctions withstatic_assertround trips. - Include guards instead of
#pragma oncein every header (handbook KB-CPP-019). - The figure references in
inc/as5047u_registers.hppfollow the datasheet: ERRFL is Figure 33, PROG 34, DIA 35, ECC_s 40. - The template files (skills, agent, CI repository checks, clang-tidy profile) follow the driver template.
-
Not verified on hardware: the start-up wait, the magnet-warning refusal and the line-pattern checks rest on the datasheet ("Timing Characteristics", Figure 9; DIA, Figure 35; ERRFL, Figure 33; the reply flag bits, Figures 22, 25, 28). Bench steps: the "On hardware" section of the Testing and CI page.
-
CI runs fewer jobs, from the driver template: the host tests build GCC and Clang in one job; DCO, the org standard, Markdown and YAML lint, the handbook rules, template drift and cppcheck are steps of one
Repository checksjob (ci-repo-checks.yml, replacingci-handbook.yml,ci-cpp-analysis.yml,ci-markdown-lint.ymlandci-yaml-lint.yml); cross-compile and host quality use ci-tools' one-job layouts. No check is dropped. The workflows have no manual (workflow_dispatch) trigger any more. - Releases also carry signed build provenance for every file (ci-tools
ru-attest-release); check a download withgh attestation verify. - The repository is public: the README points to the published site and its Doxygen API reference.
- Reading a write back is chosen per call:
WriteRegister(),ApplyConfig(),SetZeroPosition(),SetZeroHere()andSetDirection()take a last parameterVerify(as5047u::Verify::NoneorReadBack),Noneby default. By default a run-time write is only the command and data frames the datasheet needs (still CRC-protected, the reply's error bit checked);ReadBackreads each register back (two more frames) and fails withWriteMismatch.EnsureInitialized()andProgramOtp()read their writes back as before. - MISRA C++:2023 conformance: integer constants passed as arguments have the parameter's exact type, through the
new
constevalliterals_u8,_u16and_u32inas5047u::detail(a value that does not fit is a compile error), and narrower values are widened by an explicit cast (BitIf()takes theuint16_tregister bit), Rule 7.0.6;kMaxAngleCountis computed with an unsigned literal (Rule 7.0.5); operands of?:,&&,||and comparisons are parenthesised (Rule 8.0.1); two loops read a non-constant bound into aconstlocal first (Rule 9.5.1); every switch over an enumeration ends withdefault: break;(Rule 9.4.2) and the test build adds-Wswitch-enum, so a new enumerator still warns;Config::operator==is a hidden friend (Rule 16.6.1); the include ofsrc/as5047u.ippcarries its deviation marker (Rule 19.0.3). Behaviour is unchanged.
Fixed¶
- ERRFL flags taken from the chip by a read whose reply failed its CRC were lost without a trace; the latch now
says so (
flags_lost). - The reset compare covers the bits each settings register implements (DISABLE 6..0, the others 7..0, Figures 43 to 49), so a raw write to an undescribed bit is not taken for a reset.
- The warning that
Bits16reads carry no CRC is onConfig::frameand its row in Configuration, next to the setting that selects it. - A lost data frame no longer turns the next command into data: after any failed transfer the driver sends a NOP read first. Before, losing the data frame of "PROG = PROGOTP" let the next read burn the OTP (found by fuzzing).
SetZeroHere()writes the previous zero back when its angle read fails, and returnsNotInitializedbefore start-up without changing the stored zero.