AS5047U Driver 0.1.0
API reference
Loading...
Searching...
No Matches
as5047u_types.hpp
Go to the documentation of this file.
1
12#ifndef AS5047U_TYPES_HPP
13#define AS5047U_TYPES_HPP
14
15#include <array>
16#include <cstdint>
17
18#include "as5047u_detail.hpp"
19#include "as5047u_registers.hpp"
20#include "as5047u_version.h"
21
23namespace as5047u {
24
37enum class [[nodiscard]] Error : uint8_t {
38 // Base set: the same names and values in every driver of the org (standards/driver.md).
39 Ok = 0,
41 1,
42 InvalidArgument = 2,
43 Bus = 3,
44 Timeout = 4,
47 Crc = 6,
48 Busy = 7,
49 DeviceFault = 8,
51 Unsupported = 9,
52 // Chip-specific values start at 16; each one is returned by some call (tests/test_errors.cpp).
53 Framing = 16,
54 Command = 17,
55 WriteMismatch = 18,
56 OtpVerify = 19,
58 NoDevice = 20,
61 NotReady = 21,
63 MagnetWarning = 22,
66 DeviceReset = 23,
70};
71
77constexpr const char* ToString(Error error) noexcept {
78 switch (error) {
79 case Error::Ok:
80 return "Ok";
82 return "NotInitialized";
84 return "InvalidArgument";
85 case Error::Bus:
86 return "Bus";
87 case Error::Timeout:
88 return "Timeout";
90 return "DeviceIdMismatch";
91 case Error::Crc:
92 return "Crc";
93 case Error::Busy:
94 return "Busy";
96 return "DeviceFault";
98 return "Unsupported";
99 case Error::Framing:
100 return "Framing";
101 case Error::Command:
102 return "Command";
104 return "WriteMismatch";
105 case Error::OtpVerify:
106 return "OtpVerify";
107 case Error::NoDevice:
108 return "NoDevice";
109 case Error::NotReady:
110 return "NotReady";
112 return "MagnetWarning";
114 return "DeviceReset";
115 default:
116 break;
117 }
118 return "Unknown";
119}
120
128template <typename T>
129struct [[nodiscard]] Result {
130 T value{};
131 Error error{Error::Ok};
132
134 [[nodiscard]] constexpr bool ok() const noexcept {
135 return error == Error::Ok;
136 }
138 constexpr explicit operator bool() const noexcept {
139 return ok();
140 }
141
147 static constexpr Result Success(T v) noexcept {
148 return {v, Error::Ok};
149 }
155 static constexpr Result Failure(Error e) noexcept {
156 return {T{}, e};
157 }
158};
159
161template <>
162struct [[nodiscard]] Result<void> {
163 Error error{Error::Ok};
164
166 [[nodiscard]] constexpr bool ok() const noexcept {
167 return error == Error::Ok;
168 }
170 constexpr explicit operator bool() const noexcept {
171 return ok();
172 }
173
175 static constexpr Result Success() noexcept {
176 return {Error::Ok};
177 }
183 static constexpr Result Failure(Error e) noexcept {
184 return {e};
185 }
186};
187
189enum class LogLevel : uint8_t {
190 Error = 0,
191 Warning,
192 Info,
193 Debug,
194};
195
203enum class FrameFormat : uint8_t {
204 Bits16 = 0,
205 Bits24 = 1,
206 Bits32 = 2,
207};
208
209namespace detail {
211template <>
212struct EnumLast<FrameFormat> {
213 static constexpr FrameFormat kValue = FrameFormat::Bits32;
214};
215} // namespace detail
216
218enum class Direction : uint8_t {
219 Clockwise = 0,
220 CounterClockwise = 1,
221};
222
224enum class IncrementalOutput : uint8_t {
225 Abi = 0,
226 Uvw = 1,
227};
228
230enum class IndexWidth : uint8_t {
231 ThreeLsb = 0,
232 OneLsb = 1,
233};
234
235namespace detail {
237template <>
238struct EnumLast<Direction> {
239 static constexpr Direction kValue = Direction::CounterClockwise;
240};
242template <>
243struct EnumLast<IncrementalOutput> {
244 static constexpr IncrementalOutput kValue = IncrementalOutput::Uvw;
245};
247template <>
248struct EnumLast<IndexWidth> {
249 static constexpr IndexWidth kValue = IndexWidth::OneLsb;
250};
251} // namespace detail
252
261enum class Verify : uint8_t {
262 None = 0,
263 ReadBack = 1,
264};
265
266namespace detail {
268template <>
269struct EnumLast<Verify> {
270 static constexpr Verify kValue = Verify::ReadBack;
271};
272} // namespace detail
273
276inline constexpr uint32_t kPowerOnTimeMs = 10;
278inline constexpr uint32_t kStartupTimeoutMaxMs = 1000;
279
334
336inline constexpr uint16_t kCountsPerRevolution = 16384;
338inline constexpr uint16_t kMaxAngleCount = kCountsPerRevolution - 1U;
340inline constexpr float kVelocityDegPerSecPerLsb = 24.141F;
342// NOLINTNEXTLINE(modernize-use-std-numbers): <numbers> is outside the target subset (ADR-0017)
343inline constexpr float kPi = 3.14159265358979323846F;
346inline constexpr uint32_t kOtpBurnTimeoutMs = 100;
352 uint32_t code{0};
353};
355inline constexpr OtpBurnConfirm kOtpConfirm{0x0B7B'0B7BU};
357inline constexpr uint8_t kMax3BitCode = 7;
359inline constexpr uint8_t kMaxHysteresisCode = 3;
361inline constexpr uint8_t kMaxUvwPolePairs = 7;
362
365 bool agc_warning{false};
366 bool mag_half{false};
367 bool p2ram_warning{false};
368 bool p2ram_error{false};
369 bool framing{false};
370 bool command{false};
371 bool crc{false};
372 bool watchdog{false};
373 bool offset_comp{false};
374 bool cordic_overflow{false};
380 bool flags_lost{false};
381 uint16_t raw{0};
382};
383
386 bool vdd_5v{false};
387 bool loops_finished{false};
388 bool cordic_overflow{false};
389 bool agc_low{false};
390 bool agc_high{false};
391 bool mag_half{false};
392 bool offset_comp_done{false};
393 bool agc_done{false};
394 uint8_t spi_frame_count{0};
395 uint16_t raw{0};
396};
397
399using NonVolatileRegisters = std::array<uint16_t, reg::kNonVolatileCount>;
400
412
422constexpr Error Validate(const Config& config) noexcept {
423 if (!detail::IsEnumerator(config.frame) || !detail::IsEnumerator(config.direction) ||
424 !detail::IsEnumerator(config.incremental) || !detail::IsEnumerator(config.index_width)) {
426 }
427 if ((config.zero_position > kMaxAngleCount) || (config.filter_k_min_code > kMax3BitCode) ||
428 (config.filter_k_max_code > kMax3BitCode) || (config.abi_resolution_code > kMax3BitCode) ||
429 (config.hysteresis_code > kMaxHysteresisCode) || (config.uvw_pole_pairs == 0U) ||
430 (config.uvw_pole_pairs > kMaxUvwPolePairs) ||
431 (config.startup_timeout_ms > kStartupTimeoutMaxMs)) {
433 }
434 return Error::Ok;
435}
436
437static_assert(Validate(Config{}) == Error::Ok, "the defaults are valid");
438
444constexpr float CountsToDegrees(uint16_t counts) noexcept {
445 return static_cast<float>(static_cast<uint32_t>(counts) & kMaxAngleCount) * (360.0F / 16384.0F);
446}
447
453constexpr float CountsToRadians(uint16_t counts) noexcept {
454 return static_cast<float>(static_cast<uint32_t>(counts) & kMaxAngleCount) *
455 (2.0F * kPi / 16384.0F);
456}
457
459constexpr const char* GetDriverVersion() noexcept {
460 return AS5047U_VERSION_STRING;
461}
463constexpr uint32_t GetDriverVersionMajor() noexcept {
464 return AS5047U_VERSION_MAJOR;
465}
467constexpr uint32_t GetDriverVersionMinor() noexcept {
468 return AS5047U_VERSION_MINOR;
469}
471constexpr uint32_t GetDriverVersionPatch() noexcept {
472 return AS5047U_VERSION_PATCH;
473}
474
477} // namespace as5047u
478
479#endif // AS5047U_TYPES_HPP
Compile-time helpers of the AS5047U driver: exact hook matching, the dependent-false helper,...
AS5047U register map: addresses, field masks and shifts.
constexpr float kPi
Pi, as a float (C++20's std::numbers is not on every embedded toolchain).
Definition as5047u_types.hpp:343
LogLevel
Severity passed to the optional Log() hook.
Definition as5047u_types.hpp:189
constexpr uint8_t kMax3BitCode
The highest field code for 3-bit fields (filter_k_*_code, abi_resolution_code).
Definition as5047u_types.hpp:357
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition as5047u_types.hpp:37
constexpr uint16_t kCountsPerRevolution
Angle counts per revolution (14 bits).
Definition as5047u_types.hpp:336
constexpr uint8_t kMaxUvwPolePairs
Highest UVW pole-pair count.
Definition as5047u_types.hpp:361
constexpr uint32_t GetDriverVersionPatch() noexcept
Definition as5047u_types.hpp:471
std::array< uint16_t, reg::kNonVolatileCount > NonVolatileRegisters
The non-volatile registers DISABLE to ECC, in address order; index with reg::At(reg::NvIndex).
Definition as5047u_types.hpp:399
constexpr uint8_t kMaxHysteresisCode
The highest hysteresis code (2-bit field).
Definition as5047u_types.hpp:359
constexpr uint32_t kPowerOnTimeMs
Definition as5047u_types.hpp:276
constexpr float kVelocityDegPerSecPerLsb
Velocity resolution in degrees per second per LSB (datasheet, VEL register).
Definition as5047u_types.hpp:340
constexpr uint32_t kStartupTimeoutMaxMs
Largest Config::startup_timeout_ms that Validate() accepts.
Definition as5047u_types.hpp:278
constexpr float CountsToRadians(uint16_t counts) noexcept
Convert angle counts to radians.
Definition as5047u_types.hpp:453
constexpr const char * ToString(Error error) noexcept
The name of an error, for logs.
Definition as5047u_types.hpp:77
constexpr const char * GetDriverVersion() noexcept
Definition as5047u_types.hpp:459
constexpr uint32_t kOtpBurnTimeoutMs
Definition as5047u_types.hpp:346
IndexWidth
Length of the ABI index pulse (SETTINGS2.IWIDTH).
Definition as5047u_types.hpp:230
constexpr Error Validate(const Config &config) noexcept
Check a configuration without touching the chip.
Definition as5047u_types.hpp:422
Direction
Direction in which the angle increases (SETTINGS2.DIR).
Definition as5047u_types.hpp:218
constexpr OtpBurnConfirm kOtpConfirm
The confirmation to pass to ProgramOtp().
Definition as5047u_types.hpp:355
IncrementalOutput
Which incremental interface the A/B/I-U/V/W pins carry (SETTINGS2.UVW_ABI).
Definition as5047u_types.hpp:224
Verify
Whether a run-time write reads the register back, chosen per call.
Definition as5047u_types.hpp:261
FrameFormat
SPI frame length. The chip recognises the length of each frame, so the driver may mix them.
Definition as5047u_types.hpp:203
constexpr uint32_t GetDriverVersionMinor() noexcept
Definition as5047u_types.hpp:467
constexpr float CountsToDegrees(uint16_t counts) noexcept
Convert angle counts to degrees.
Definition as5047u_types.hpp:444
constexpr uint16_t kMaxAngleCount
Highest angle count.
Definition as5047u_types.hpp:338
constexpr uint32_t GetDriverVersionMajor() noexcept
Definition as5047u_types.hpp:463
@ Warning
Something unexpected that the driver recovered from.
@ Info
Lifecycle events: initialised, OTP burned.
@ Debug
Detail for bring-up.
@ InvalidArgument
An argument or a Config field is out of range; nothing was sent.
@ Framing
The chip saw an SPI framing error (ERRFL.Framing_error).
@ Crc
A reply's CRC was wrong, or the chip saw a wrong CRC (ERRFL.CRC_error).
@ Bus
A port hook returned false.
@ NotInitialized
EnsureInitialized() has not succeeded yet, or Deinitialize() ran since.
@ Ok
The call succeeded.
@ Unsupported
Not returned by this driver.
@ Timeout
The OTP burn did not finish in kOtpBurnTimeoutMs.
@ Busy
Not returned by this driver (the chip has no busy state).
@ Command
The chip saw an invalid command (ERRFL.Command_error).
@ WriteMismatch
A register read back different from what was written.
@ ThreeLsb
3 LSB. Reset value.
@ CounterClockwise
Inverted (DIR = 1).
@ Clockwise
The datasheet's default direction, seen from above the magnet.
@ Abi
A, B and index pulses; PWM, when on, goes on pin W. Reset value.
@ Uvw
U, V and W commutation signals; PWM, when on, goes on pin I.
@ None
Command and data frames only. The default: nothing extra on a timed path.
@ ReadBack
Read each written register back and compare.
@ Bits16
16-bit frames, no CRC: the fastest reads, but a corrupted reply goes unnoticed.
@ Bits32
32-bit frames: a pad byte, then a 24-bit frame (daisy chains).
@ Bits24
24-bit frames with CRC-8 in both directions. Default.
The AS5047U driver: everything it declares lives here; internals in detail.
Definition as5047u.hpp:24
Everything EnsureInitialized() and ApplyConfig() write to the chip.
Definition as5047u_types.hpp:287
Direction direction
SETTINGS2.DIR.
Definition as5047u_types.hpp:305
uint8_t pad_byte
Driver side: the pad byte of 32-bit frames (the daisy-chain address).
Definition as5047u_types.hpp:294
bool high_temperature_noise
Definition as5047u_types.hpp:320
uint16_t zero_position
ZPOSM/ZPOSL, counts 0 to 16383.
Definition as5047u_types.hpp:306
bool uvw_enable
U/V/W pins driven (DISABLE.UVW_off = 0).
Definition as5047u_types.hpp:313
bool write_settings
Definition as5047u_types.hpp:298
bool pwm_enable
SETTINGS2.PWMon.
Definition as5047u_types.hpp:314
uint8_t filter_k_max_code
SETTINGS1.K_max code, 0 to 7.
Definition as5047u_types.hpp:310
bool uncompensated_at_angle_register
SETTINGS2.Data_select: address 0x3FFF (and the PWM output) carry the angle without DAEC.
Definition as5047u_types.hpp:322
bool abi_decimal
SETTINGS2.ABI_DEC.
Definition as5047u_types.hpp:316
uint8_t uvw_pole_pairs
SETTINGS3.UVWPP + 1, 1 to 7.
Definition as5047u_types.hpp:318
uint8_t filter_k_min_code
SETTINGS1.K_min code, 0 to 7.
Definition as5047u_types.hpp:309
uint8_t hysteresis_code
SETTINGS3.HYS, 0 to 3.
Definition as5047u_types.hpp:319
IndexWidth index_width
SETTINGS2.IWIDTH.
Definition as5047u_types.hpp:317
bool abi_enable
A/B/I pins driven (DISABLE.ABI_off = 0).
Definition as5047u_types.hpp:312
bool adaptive_filter
Velocity filter on (DISABLE bit 6 = 0).
Definition as5047u_types.hpp:308
friend constexpr bool operator==(const Config &lhs, const Config &rhs) noexcept=default
Field by field; every member is an integer, a bool or an enumeration, so equality is exact (KB-CPP20-...
IncrementalOutput incremental
SETTINGS2.UVW_ABI.
Definition as5047u_types.hpp:311
uint32_t startup_timeout_ms
Definition as5047u_types.hpp:303
bool dynamic_compensation
DAEC on (SETTINGS2.DAECDIS = 0).
Definition as5047u_types.hpp:307
FrameFormat frame
Definition as5047u_types.hpp:292
uint8_t abi_resolution_code
SETTINGS3.ABIRES, 0 to 7.
Definition as5047u_types.hpp:315
DIA, decoded: the state of the chip's internal loops.
Definition as5047u_types.hpp:385
bool cordic_overflow
CORDIC overflow.
Definition as5047u_types.hpp:388
uint16_t raw
The register value.
Definition as5047u_types.hpp:395
uint8_t spi_frame_count
SPI_cnt: frames since the last read of DIA, modulo 4.
Definition as5047u_types.hpp:394
bool agc_high
AGC at its high limit (field too weak).
Definition as5047u_types.hpp:390
bool mag_half
Field at half the regulated value.
Definition as5047u_types.hpp:391
bool agc_low
AGC at its low limit (field too strong).
Definition as5047u_types.hpp:389
bool offset_comp_done
Offset compensation finished.
Definition as5047u_types.hpp:392
bool loops_finished
Every magnetic loop has settled.
Definition as5047u_types.hpp:387
bool vdd_5v
VDD_mode: the chip runs from 5 V (else 3.3 V).
Definition as5047u_types.hpp:386
bool agc_done
AGC loop finished.
Definition as5047u_types.hpp:393
ERRFL, decoded. Reading ERRFL clears it on the chip.
Definition as5047u_types.hpp:364
bool command
Invalid SPI command.
Definition as5047u_types.hpp:370
bool crc
Wrong CRC on a MOSI frame.
Definition as5047u_types.hpp:371
bool framing
SPI framing error.
Definition as5047u_types.hpp:369
bool mag_half
Field at half the regulated value.
Definition as5047u_types.hpp:366
uint16_t raw
The register value.
Definition as5047u_types.hpp:381
bool offset_comp
Offset compensation not finished.
Definition as5047u_types.hpp:373
bool p2ram_error
ECC found an uncorrectable P2RAM error.
Definition as5047u_types.hpp:368
bool flags_lost
Not an ERRFL bit: in GetLatchedErrorFlags() only, true when a read of ERRFL failed after its command ...
Definition as5047u_types.hpp:380
bool p2ram_warning
ECC corrected one bit in the P2RAM.
Definition as5047u_types.hpp:367
bool watchdog
Internal oscillator or watchdog fault.
Definition as5047u_types.hpp:372
bool agc_warning
AGC at its minimum or maximum: magnet too far or too close.
Definition as5047u_types.hpp:365
bool cordic_overflow
CORDIC overflow.
Definition as5047u_types.hpp:374
The typed confirmation ProgramOtp() requires: burning the OTP cannot be undone, so the call names its...
Definition as5047u_types.hpp:351
uint32_t code
Must be kOtpConfirm.code.
Definition as5047u_types.hpp:352
Outcome of AS5047U::ProgramOtp().
Definition as5047u_types.hpp:402
NonVolatileRegisters written
DISABLE to ECC as verified before the burn: what was burned.
Definition as5047u_types.hpp:410
bool burn_started
Definition as5047u_types.hpp:408
uint8_t failed_step
Datasheet step that failed (6 to 19), or 0 when every step succeeded.
Definition as5047u_types.hpp:404
constexpr bool ok() const noexcept
Definition as5047u_types.hpp:166
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition as5047u_types.hpp:183
static constexpr Result Success() noexcept
Definition as5047u_types.hpp:175
The value of a call, or why there is none.
Definition as5047u_types.hpp:129
static constexpr Result Success(T v) noexcept
A successful result.
Definition as5047u_types.hpp:147
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition as5047u_types.hpp:155
constexpr bool ok() const noexcept
Definition as5047u_types.hpp:134