AS5047U Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
as5047u::AS5047U< Port > Class Template Reference

Driver for one AS5047U on a platform port. More...

#include <as5047u.hpp>

Public Member Functions

 AS5047U (Port &port, const Config &config={}) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail.
 
 AS5047U (const AS5047U &)=delete
 One driver object per chip.
 
AS5047U & operator= (const AS5047U &)=delete
 One driver object per chip.
 
Lifecycle
Result< void > EnsureInitialized () noexcept
 Start the chip, once: the only way to initialise the driver.
 
bool IsInitialized () const noexcept
 
Result< void > Deinitialize () noexcept
 Mark the driver uninitialised; the next EnsureInitialized() starts the chip again (the recovery after a fault). No I/O: the AS5047U has no low-power mode to enter.
 
Configuration
Result< void > ApplyConfig (const Config &config, Verify verify=Verify::None) noexcept
 Change the configuration.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 
Result< void > SetZeroPosition (uint16_t counts, Verify verify=Verify::None) noexcept
 Set the zero position (ZPOSM, ZPOSL).
 
Result< uint16_t > SetZeroHere (Verify verify=Verify::None) noexcept
 Make the current position read as 0.
 
Result< void > SetDirection (Direction direction, Verify verify=Verify::None) noexcept
 Set the direction in which the angle increases.
 
Measurement
Result< uint16_t > ReadAngleCounts () noexcept
 The angle at address 0x3FFF (with DAEC unless it is off): the hot path.
 
Result< uint16_t > ReadUncompensatedAngleCounts () noexcept
 
Result< float > ReadAngleDegrees () noexcept
 
Result< float > ReadAngleRadians () noexcept
 
Result< int16_t > ReadVelocityCounts () noexcept
 
Result< float > ReadVelocityDegPerSec () noexcept
 
Result< float > ReadVelocityRpm () noexcept
 
Result< uint8_t > ReadAgc () noexcept
 
Result< uint16_t > ReadMagnitude () noexcept
 
Diagnostics
Result< Diagnostics > ReadDiagnostics () noexcept
 
Result< void > CheckForReset () noexcept
 Check that the chip still holds the settings the driver wrote: the cheap test for a reset of the chip that ERRFL may not report.
 
Result< ErrorFlags > ReadErrorFlags () noexcept
 Read ERRFL, which clears it on the chip. The value is also kept in GetLastErrorFlags() and ORed into GetLatchedErrorFlags().
 
ErrorFlags GetLastErrorFlags () const noexcept
 
ErrorFlags GetLatchedErrorFlags () const noexcept
 Every ERRFL flag the driver has read since the last ClearLatchedErrorFlags(). No I/O.
 
void ClearLatchedErrorFlags () noexcept
 Empty the latch of GetLatchedErrorFlags(), flags_lost included. No I/O.
 
uint16_t GetLastReply () const noexcept
 
Result< uint16_t > ReadRegister (uint16_t address) noexcept
 Read one register once: the command frame and the NOP frame that carries the answer, no retry (handbook KB-CPP-129).
 
Result< void > WriteRegister (uint16_t address, uint16_t value, Verify verify=Verify::None) noexcept
 Write a register: the command and data frames, nothing more unless verify asks for a read-back. PROG is refused: use ProgramOtp(). A write to DISABLE to SETTINGS3 does not change GetConfig(), so the next ApplyConfig() or setter writes the configuration over it. When such a write fails, DISABLE to ECC are read back (14 frames) for the reset check's copy.
 
Result< NonVolatileRegisters > ReadNonVolatile () noexcept
 
OTP
Result< void > ProgramOtp (OtpBurnConfirm confirm, OtpReport &report) noexcept
 Burn the current settings into the OTP. This cannot be undone.
 

Detailed Description

template<SpiPort Port>
class as5047u::AS5047U< Port >

Driver for one AS5047U on a platform port.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start (bus up, presence check, error flags cleared, settings written and read back), use, optionally Deinitialize(). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded; no call starts the chip as a side effect, so a read is always the frames it needs and nothing more.

Every read checks the two flag bits of the reply. A read whose reply has neither set costs exactly its two frames. When the error bit is set the driver reads ERRFL (which clears it on the chip, so the driver ORs it into GetLatchedErrorFlags()) and fails the call with Crc, Framing, Command or DeviceFault. When an angle or velocity reply carries the warning bit, the driver reads ERRFL the same way and refuses the value with MagnetWarning if the field is out of range (AGC at a limit, field at half); a P2RAM single-bit warning (corrected by the ECC) does not refuse it. Other reads (AGC, magnitude, DIA, settings) return their value under a warning and leave ERRFL on the chip for ReadErrorFlags().

Reset detection: a power-on reset or brown-out of the chip reloads its settings from the OTP and loses every soft write ("Non-Volatile Registers (OTP)"). When any ERRFL read after start-up holds OffCompNotFinished or WDTST (the offset compensation restarts at power-up, Figure 33), the driver reads DISABLE to ECC (14 frames) and compares them with what it last wrote or read there. A read of ERRFL that failed (and may have taken that flag) costs the same compare. On a difference, or when that read cannot be completed after a flag, the call fails with DeviceReset and the driver is uninitialised: call EnsureInitialized() again, which writes the configuration anew. The datasheet does not promise that flag after a reset, so call CheckForReset() periodically where a reset must not go unnoticed (docs/limitations.md).

Port hooks beyond the required bus hooks, found at compile time:

Hook Used for Without it
void DelayUs(uint32_t us) noexcept 1 ms between polls of DIA at start-up and of the OTP burn Compile error: the waits are required
void Log(LogLevel, const char* message) noexcept One line per lifecycle event or failure Nothing is logged

A hook declared with the wrong signature (for example DelayUs(uint16_t)) is a compile error.

Template Parameters
PortYour class derived from SpiInterface<Port>.

Constructor & Destructor Documentation

◆ AS5047U()

template<SpiPort Port>
as5047u::AS5047U< Port >::AS5047U ( Port &  port,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port and store the configuration. No I/O, cannot fail.

Parameters
portThe port; it must outlive the driver.
configWhat EnsureInitialized() will apply; checked there, before any I/O.

Member Function Documentation

◆ ApplyConfig()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::ApplyConfig ( const Config &  config,
Verify  verify = Verify::None 
)
noexcept

Change the configuration.

Running: the settings registers are read (to keep their DIA bits), then every setting is written, and read back with Verify::ReadBack. Not started yet: config is only stored, for the first EnsureInitialized(), with no I/O; start-up reads its writes back anyway.

When it fails after a write may have reached the chip, the write may have taken effect, so the driver neither retries it nor keeps the old values: it reads DISABLE to ECC back (14 frames) and GetConfig() then holds what the chip holds, field by field (the driver-side fields keep their old values). When that read fails too, the driver is uninitialised and GetConfig() holds the old configuration again, which EnsureInitialized() writes.

Parameters
configChecked with Validate() before any I/O.
verifyVerify::ReadBack reads each write back (two more frames per register).
Returns
Ok, InvalidArgument (also for a verify that is not an enumerator), Bus, Crc, Framing, Command, DeviceFault, WriteMismatch (with Verify::ReadBack) or DeviceReset (as for ReadAngleCounts()).

◆ CheckForReset()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::CheckForReset ( )
noexcept

Check that the chip still holds the settings the driver wrote: the cheap test for a reset of the chip that ERRFL may not report.

Reads DISABLE to ECC (14 frames, 7 register reads; about 34 µs of bus time at 10 MHz with 24-bit frames) and compares them with what the driver last wrote there or, with write_settings false, read at start-up. A power-on reset or brown-out reloads them from the OTP ("Non-Volatile Registers (OTP)"), so a configuration that differs from the OTP shows the reset; one equal to the OTP is not changed by a reset, so nothing is lost. Call it at the rate at which a reset must be noticed (for example once per control-loop supervision tick); the driver adds no periodic traffic of its own.

Returns
Ok; DeviceReset (the registers differ: the chip was reset, or a write was lost; the driver is now uninitialised, call EnsureInitialized()); NotInitialized; or a read error (Bus, Crc, NoDevice, Framing, Command, DeviceFault), after which the driver stays initialised, unless ERRFL reported a reset hint during the read, which is DeviceReset.

◆ Deinitialize()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::Deinitialize ( )
noexcept

Mark the driver uninitialised; the next EnsureInitialized() starts the chip again (the recovery after a fault). No I/O: the AS5047U has no low-power mode to enter.

Returns
Ok.

◆ EnsureInitialized()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::EnsureInitialized ( )
noexcept

Start the chip, once: the only way to initialise the driver.

The first call brings the bus up and waits for the chip: it reads DIA, once per millisecond for at most Config::startup_timeout_ms, until every magnetic loop reports finished, and accepts that only when the next DIA read says the same (a ready status a line could fake counts only when a second read confirms it, KB-CPP-116, KB-CPP-124). Then it reads ERRFL, which clears what the power-up left there (the value goes into GetLatchedErrorFlags(), which the call empties first), and applies the stored configuration: the settings registers read (to keep their DIA bits), then every setting written and read back (start-up always verifies), or, with write_settings false (an OTP-burned part), the chip's settings read into GetConfig(). A chip that is already up costs 6 frames before the settings; one that is not yet ready adds 2 frames and 1 ms per poll. After it succeeds, later calls return Ok at once with no I/O. After it fails, the driver stays uninitialised and the next call starts again from the beginning.

Returns
Ok, InvalidArgument (the stored configuration fails Validate(); no I/O), Bus, NoDevice (only line patterns until the deadline), NotReady (the chip answers but its loops did not finish by the deadline), DeviceIdMismatch (a DIA with a bit set that reads 0 on an AS5047U), Crc, Framing, Command, DeviceFault or WriteMismatch. After a DeviceReset from any call, this call starts the chip again and writes the stored configuration (GetConfig() still holds it).

◆ GetConfig()

template<SpiPort Port>
const Config & as5047u::AS5047U< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration last applied, stored or read from the chip: after a failed ApplyConfig() or setter, what the read-back found. No I/O.

◆ GetLastErrorFlags()

template<SpiPort Port>
ErrorFlags as5047u::AS5047U< Port >::GetLastErrorFlags ( ) const
inlinenoexcept
Returns
The ERRFL value the driver read last, by any call. No I/O.

◆ GetLastReply()

template<SpiPort Port>
uint16_t as5047u::AS5047U< Port >::GetLastReply ( ) const
inlinenoexcept
Returns
The raw reply word of the last frame (warning bit 15, error bit 14, 14 data bits), by any call, whatever its CRC said; 0 before the first. No I/O (handbook KB-CPP-129).

◆ GetLatchedErrorFlags()

template<SpiPort Port>
ErrorFlags as5047u::AS5047U< Port >::GetLatchedErrorFlags ( ) const
inlinenoexcept

Every ERRFL flag the driver has read since the last ClearLatchedErrorFlags(). No I/O.

ERRFL clears when it is read, and the driver reads it inside other calls: to resolve a reply's error or warning bit, and once at start-up. Each of those reads, ReadErrorFlags() and a raw ReadRegister(reg::kErrfl) OR the value into this latch, so no internal read hides a flag from the caller (handbook KB-CPP-119). EnsureInitialized() empties it first; after start-up it holds what the power-up left in ERRFL (for example offset_comp from before the loops settled): clear it there if only later flags matter.

flags_lost is set when a read of ERRFL failed once its command may have reached the chip (a reply CRC error, a failed transfer, NoDevice for the reserved bit): the chip cleared the flags that read took, so a fault may have been missed. The driver then compares the settings registers itself (14 frames, DeviceReset on a difference). When that compare cannot be read either, the call keeps its own error and the compare stays pending: each later call runs it and fails with its error until it is read, so no value is returned meanwhile. Check the bus, read ReadDiagnostics(), and call CheckForReset() when it is set.

Returns
The latched flags; raw is their OR.

◆ IsInitialized()

template<SpiPort Port>
bool as5047u::AS5047U< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized() and before Deinitialize(). No I/O.

◆ ProgramOtp()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::ProgramOtp ( OtpBurnConfirm  confirm,
OtpReport &  report 
)
noexcept

Burn the current settings into the OTP. This cannot be undone.

Follows the datasheet's step-by-step OTP procedure from step 6: the zero position is the one configured (steps 4 and 5, which set it to the current angle, are SetZeroHere()). Steps 1 to 3 (supply, settings) and 20 to 22 (power cycle and check) are the caller's. Needs the DelayUs() hook. Every frame of the procedure is CRC-protected, whatever Config::frame says, and the writes of steps 7, 9, 12 and 15 are always read back: a burn cannot be undone.

Parameters
confirmMust be kOtpConfirm, so that a stray call cannot burn the part.
reportFilled with the step that failed, whether the burn started, and what was burned.
Returns
Ok, NotInitialized, InvalidArgument (wrong confirm), Bus, Crc, Framing, Command, DeviceFault, WriteMismatch (steps 7, 9, 11, 12 and 15), Timeout (step 14) or OtpVerify (step 19: the part failed the guard-band test).

◆ ReadAgc()

template<SpiPort Port>
Result< uint8_t > as5047u::AS5047U< Port >::ReadAgc ( )
noexcept
Returns
The AGC value, 0 to 255: low for a strong field, high for a weak one.

◆ ReadAngleCounts()

template<SpiPort Port>
Result< uint16_t > as5047u::AS5047U< Port >::ReadAngleCounts ( )
noexcept

The angle at address 0x3FFF (with DAEC unless it is off): the hot path.

Two frames (the read command, then a NOP whose reply carries the angle) and nothing more when the reply has neither flag bit set. When it has one, two more frames read ERRFL to find out why (latched in GetLatchedErrorFlags()).

Returns
0 to 16383 counts, or NotInitialized, Bus, Crc, NoDevice, Framing, Command, DeviceFault, MagnetWarning (the field is out of range: not a measurement) or DeviceReset (ERRFL holds OffCompNotFinished or WDTST and the settings registers changed; 14 more frames read them, see the class description).

◆ ReadAngleDegrees()

template<SpiPort Port>
Result< float > as5047u::AS5047U< Port >::ReadAngleDegrees ( )
noexcept
Returns
The angle in degrees, [0, 360); errors as ReadAngleCounts().

◆ ReadAngleRadians()

template<SpiPort Port>
Result< float > as5047u::AS5047U< Port >::ReadAngleRadians ( )
noexcept
Returns
The angle in radians, [0, 2π); errors as ReadAngleCounts().

◆ ReadDiagnostics()

template<SpiPort Port>
Result< Diagnostics > as5047u::AS5047U< Port >::ReadDiagnostics ( )
noexcept
Returns
DIA, decoded.

◆ ReadErrorFlags()

template<SpiPort Port>
Result< ErrorFlags > as5047u::AS5047U< Port >::ReadErrorFlags ( )
noexcept

Read ERRFL, which clears it on the chip. The value is also kept in GetLastErrorFlags() and ORed into GetLatchedErrorFlags().

Returns
The flags read now, or NotInitialized, Bus, Crc, NoDevice (the reply has ERRFL's reserved bit set, or is a line pattern) or DeviceReset (ERRFL holds OffCompNotFinished or WDTST and the settings registers changed; the flags are still latched). A failed read sets flags_lost in GetLatchedErrorFlags().

◆ ReadMagnitude()

template<SpiPort Port>
Result< uint16_t > as5047u::AS5047U< Port >::ReadMagnitude ( )
noexcept
Returns
The CORDIC magnitude, 0 to 16383.

◆ ReadNonVolatile()

template<SpiPort Port>
Result< NonVolatileRegisters > as5047u::AS5047U< Port >::ReadNonVolatile ( )
noexcept
Returns
DISABLE to ECC as the chip holds them now.

◆ ReadRegister()

template<SpiPort Port>
Result< uint16_t > as5047u::AS5047U< Port >::ReadRegister ( uint16_t  address)
noexcept

Read one register once: the command frame and the NOP frame that carries the answer, no retry (handbook KB-CPP-129).

When the reply's error bit is set, ERRFL is read (two more frames) and the call fails with the error it names; a warning bit alone does not fail the call. Side effects are the chip's own: reading ERRFL clears it (the driver latches it, see GetLatchedErrorFlags()), reading DIA restarts its SPI frame counter.

Parameters
address14-bit address.
Returns
The 14-bit content, or NotInitialized, InvalidArgument (above 0x3FFF; nothing sent), Bus, Crc, NoDevice, Framing, Command, DeviceFault or DeviceReset (as for ReadAngleCounts()).

◆ ReadUncompensatedAngleCounts()

template<SpiPort Port>
Result< uint16_t > as5047u::AS5047U< Port >::ReadUncompensatedAngleCounts ( )
noexcept
Returns
The angle without dynamic compensation (ANGLEUNC), 0 to 16383 counts; errors and frames as ReadAngleCounts().

◆ ReadVelocityCounts()

template<SpiPort Port>
Result< int16_t > as5047u::AS5047U< Port >::ReadVelocityCounts ( )
noexcept
Returns
The angular velocity in counts (signed 14 bit, 24.141 °/s per count); errors and frames as ReadAngleCounts(), MagnetWarning included.

◆ ReadVelocityDegPerSec()

template<SpiPort Port>
Result< float > as5047u::AS5047U< Port >::ReadVelocityDegPerSec ( )
noexcept
Returns
The angular velocity in degrees per second.

◆ ReadVelocityRpm()

template<SpiPort Port>
Result< float > as5047u::AS5047U< Port >::ReadVelocityRpm ( )
noexcept
Returns
The angular velocity in revolutions per minute.

◆ SetDirection()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::SetDirection ( Direction  direction,
Verify  verify = Verify::None 
)
noexcept

Set the direction in which the angle increases.

Parameters
directionThe direction.
verifyAs for ApplyConfig().
Returns
As ApplyConfig(): before EnsureInitialized() the value is only stored.

◆ SetZeroHere()

template<SpiPort Port>
Result< uint16_t > as5047u::AS5047U< Port >::SetZeroHere ( Verify  verify = Verify::None)
noexcept

Make the current position read as 0.

Writes a zero of 0, reads the angle at 0x3FFF (ReadAngleCounts(), datasheet OTP procedure step 4) and writes it as the new zero. When the read fails, the previous zero is written back before the error is returned.

Parameters
verifyPassed to each SetZeroPosition().
Returns
The new zero position in counts; NotInitialized before EnsureInitialized(), or the errors of ReadAngleCounts() and SetZeroPosition().

◆ SetZeroPosition()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::SetZeroPosition ( uint16_t  counts,
Verify  verify = Verify::None 
)
noexcept

Set the zero position (ZPOSM, ZPOSL).

Parameters
counts0 to 16383: the uncorrected angle that will read as 0.
verifyAs for ApplyConfig().
Returns
As ApplyConfig(): before EnsureInitialized() the value is only stored.

◆ WriteRegister()

template<SpiPort Port>
Result< void > as5047u::AS5047U< Port >::WriteRegister ( uint16_t  address,
uint16_t  value,
Verify  verify = Verify::None 
)
noexcept

Write a register: the command and data frames, nothing more unless verify asks for a read-back. PROG is refused: use ProgramOtp(). A write to DISABLE to SETTINGS3 does not change GetConfig(), so the next ApplyConfig() or setter writes the configuration over it. When such a write fails, DISABLE to ECC are read back (14 frames) for the reset check's copy.

Parameters
address14-bit address, not reg::kProg.
value14-bit value.
verifyVerify::ReadBack reads the register back (two more frames) and compares.
Returns
Ok, NotInitialized, InvalidArgument, Bus, Crc, Framing, Command, DeviceFault, WriteMismatch (with Verify::ReadBack) or DeviceReset (as for ReadAngleCounts()).

The documentation for this class was generated from the following file: