Contract¶
What the AS5047U driver promises, what it needs, and the rules a caller follows.
The driver inherits the Kokeb Labs driver contract; this page states only what is specific to it. A change to anything here is a breaking change, listed under Breaking in the changelog.
Promises¶
- The constructor is
noexcept, does no I/O and cannot fail. EnsureInitialized()brings the bus up and waits for the chip: it polls DIA once per millisecond, for at mostConfig::startup_timeout_ms(default t_pon, 10 ms), until every magnetic loop reports finished, and accepts that only when the next DIA read confirms it. A DIA that is all zeros or all ones, or a line pattern with a wrong CRC, isNoDevice; a DIA with a bit set that reads 0 on an AS5047U isDeviceIdMismatch; a chip that answers but is not ready by the deadline isNotReady. Then it reads ERRFL once to clear what the power-up left (the value goes into the latch), and only then writes the configuration and reads it back. Withwrite_settings = falseit writes nothing and reads the chip's settings intoGetConfig(). On any failure the driver stays uninitialised.- Every call that touches the chip returns
Error::NotInitializedbeforeEnsureInitialized()succeeds. No call initialises the chip as a side effect. - Every port failure propagates as
Error::Bus; a failed read returnsT{}, never a stale or partial value. - After a failed transfer the next frame is a read of NOP, because the chip may still be waiting for the data frame
of a write: taken as a command it reads nothing, taken as data it writes 0 (for PROG: no burn). A register whose
write failed holds an unknown value (the old one, the new one or 0), so a failed
ApplyConfig()or setter never retries the write and never keeps the old or the new value: it reads DISABLE to ECC back (14 frames, CRC- and flag-checked) andGetConfig()takes every chip field from what the chip holds; when that read fails too, the driver is uninitialised andEnsureInitialized()writes the configuration again. For ZPOSL and SETTINGS1 that 0 includes their DIA enable bits, whichApplyConfig()keeps as the chip holds them: power-cycle the chip (they reload from the OTP) or write them back withWriteRegister()if they matter to you. - Every reply's CRC is checked (24- and 32-bit frames), and every reply's error bit is resolved through ERRFL:
Crc,Framing,CommandorDeviceFault. A reply that a stuck, floating or looped-back line produces is never a value: all zeros or all ones with a wrong CRC, an ERRFL with its reserved bit set, or an error bit with no error in ERRFL isNoDevice(handbook KB-CPP-116). - An angle or velocity whose reply carries the warning bit is returned only when ERRFL holds no field warning; with
an AGC or magnetic-half warning the call fails with
MagnetWarning(handbook KB-CPP-127). A P2RAM single-bit warning (corrected by the ECC) does not refuse it. Other reads return their value under a warning. - Every ERRFL value the driver reads, its own internal reads included, is ORed into one latch:
GetLatchedErrorFlags()(no I/O) untilClearLatchedErrorFlags()(handbook KB-CPP-119). A read of ERRFL that fails once its command may have reached the chip (a reply CRC error, a failed transfer, the reserved bit set) setsflags_lostin the latch: ERRFL clears when read, so a fault may have been missed, a reset's OffCompNotFinished included. The driver then compares the settings registers as below (14 frames). When that compare cannot be read either, the call keeps its own error, the driver stays initialised and the compare stays pending: every later call runs it after its own access (14 more frames) and fails with the compare's error (Bus,Crc, ...) until it can be read, so no value is returned while a reset may have gone unseen. A compare that is read ends it:DeviceReseton a difference, else the call's own result. - A reset of the chip is never followed by the old cached settings. 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 fails with
DeviceResetand the driver is uninitialised untilEnsureInitialized()writes the configuration again.CheckForReset()makes the same comparison on request. - An angle or velocity read is two frames when the reply has no flag bit set, four when it has one (the ERRFL read), and 18 when that ERRFL holds OffCompNotFinished or WDTST or its read fails (the settings check). Nothing else is ever added to it, except the pending compare described above (16 frames: the read and the compare) after a failed ERRFL read whose compare failed too. The compare covers the bits each register implements (DISABLE 6..0, the others 7..0, Figures 43 to 49).
- Every write is CRC-protected, in every frame format. A run-time write (
WriteRegister(),ApplyConfig(), the setters) is the command and data frames only, unless the call passesVerify::ReadBack;EnsureInitialized()reads every settings write back. Every frame ofProgramOtp(), reads included, is CRC-protected, and its writes of steps 7, 9, 12 and 15 are always read back. - The only waits are in
EnsureInitialized()(1 ms between polls of DIA, at mostConfig::startup_timeout_ms, at mostkStartupTimeoutMaxMs) and inProgramOtp()(1 ms between polls of the burn, at mostkOtpBurnTimeoutMs, 100 ms). Every loop has a fixed bound. ProgramOtp()takes a typedOtpBurnConfirm, burns nothing withoutkOtpConfirm, sends the burn command once and never retries it, andWriteRegister()refuses PROG.Config{}equals the register reset values of an unprogrammed part.- The port concept checks each hook's exact signature and
noexcept: a hook with a narrower parameter or withoutnoexceptis a compile error. A missingDelayUs()is a compile error atEnsureInitialized(); a missingLog()logs nothing; a misdeclaredDelayUs()orLog()is a compile error. - What the chip needs from the bus is
constexprininc/as5047u_spi_interface.hpp(kSpiModetokContinuousWord), for a port tostatic_assertagainst. Deinitialize()does no I/O: the chip has no low-power mode.
Depends on¶
| Dependency | Version | Why |
|---|---|---|
| A C++20 compiler | GCC 10, Clang 13 or later | Concepts constrain the port |
| CMake | 3.16 or later | Generates as5047u_version.h |
| Your port | The bus, within the bus requirements; the delay; optionally logging (Porting) |
Nothing else: no RTOS, no SDK, no other repository of the org.
Threading¶
The driver is not thread-safe and takes no lock. Use each driver object from one task at a time, or guard every call on it with one mutex; the layer that owns the driver owns that lock, and the bus lock when several chips share a bus. Nothing may run in an ISR: every call can block for a bus transfer or a delay. Separate objects share no state.
Errors¶
as5047u::Error inside as5047u::Result<T>. Values 0 to 9 are the shared base set; this driver returns all of
them except Busy and Unsupported, plus eight chip-specific values.
Error |
Value | Returned when |
|---|---|---|
Ok |
0 | The call succeeded |
NotInitialized |
1 | EnsureInitialized() has not succeeded, or Deinitialize() ran since |
InvalidArgument |
2 | A Config field or argument is out of range (Validate(), a Verify that is not an enumerator, a startup_timeout_ms above kStartupTimeoutMaxMs), WriteRegister() on PROG, or ProgramOtp() without kOtpConfirm; nothing was sent |
Bus |
3 | A port hook returned false |
Timeout |
4 | The OTP burn did not finish in kOtpBurnTimeoutMs (100 ms) |
DeviceIdMismatch |
5 | Something answers at EnsureInitialized(), but DIA has bit 10 set, which reads 0 on an AS5047U |
Crc |
6 | A reply's CRC was wrong, or ERRFL.CRC_error is set (the chip saw a wrong CRC) |
Busy |
7 | Never returned: the chip has no busy state |
DeviceFault |
8 | ERRFL reports P2RAM_error, Watchdog_error, Off_comp_error or CORDIC_overflow |
Unsupported |
9 | Never returned: the driver has no optional feature |
Framing |
16 | ERRFL.Framing_error is set: the chip saw a frame of the wrong length |
Command |
17 | ERRFL.Command_error is set: the chip saw an invalid command |
WriteMismatch |
18 | A register read back different from what was written: a call with Verify::ReadBack, EnsureInitialized(), or OTP steps 7, 9, 11, 12 and 15 |
OtpVerify |
19 | The OTP guard-band read-back differs from what was burned (OTP step 19) |
NoDevice |
20 | A reply a stuck, floating or looped-back line produces: only such replies at start-up until the deadline, or at run time a line pattern with a wrong CRC, an ERRFL with its reserved bit 8 set, or an error bit with no error in ERRFL |
NotReady |
21 | At EnsureInitialized(): the chip answers, but DIA did not report every loop finished (twice in a row) by Config::startup_timeout_ms |
MagnetWarning |
22 | An angle or velocity reply carried the warning bit and ERRFL holds AGC_warning or MagHalf: the field is out of range and the value is not a measurement |
DeviceReset |
23 | The chip was reset, or a reset could not be ruled out: after OffCompNotFinished or WDTST in ERRFL, or in CheckForReset(), the settings registers did not hold what the driver wrote (or could not be read after such a flag). The driver is uninitialised |
The API guide says what to do about each.
Memory¶
No heap, no exceptions, no RTTI, no std::function, no std::string, no printf and no static mutable state. A
driver object holds a reference to the port, a Config, the last reply word, the last ERRFL value, the ERRFL latch,
the 14-byte copy of the settings registers it compares a reset against and five flags: under 80 bytes. Stack use
is small and fixed: 4-byte frame buffers, and 14-byte register arrays in ReadNonVolatile(), CheckForReset() and
ProgramOtp(). The CRC-8 table is 256 bytes of read-only data.
Platform¶
Platform-free: the same code runs on any target with a C++20 compiler, including the host tests. The ESP-IDF port
in examples/esp32 is an example, not part of the driver.
Deviations from the standard¶
None.