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.
[0.1.0] - 2026-11-10¶
Breaking¶
- Every I/O call of a running driver can return
Error::DeviceReset(wasReadStatus()only): a fault byte or a STATUS value with ACTIVE = 0 means a power-on reset.ReadRegister(reg::kStatus)no longer returns such a STATUS as read. - Every I/O call of a running driver can return
Error::CommunicationErrorwhen it sees COMER go from 0 to 1 (was only withVerify::ReadBack): an earlier write was miscounted. - New
Error::Uncertain(23):SetChannelsOn(),SetChannel()andSetBridge()refuse a switch-on in a pair whose mode a write with a failed reply left unknown; that pair is switched off instead (the rest of aSetChannelsOn()mask still goes out, and a channel a failed write may have switched on is switched off when asked, even if the copy already says off). A switch-off there is never refused: it switches both channels of the pair off, the partner too. SetChannel(ch, false)in a full-bridge pair sets HiZ (both channels off) instead of returningInvalidArgument.LatchedFaultshas new fields (overcurrent,open_load,hit_not_reached,plunger,lost), andAny()counts them.FullScaleUa()returnsResult<uint32_t>(InvalidArgumentfor an RREF out of range,kNoRrefincluded) instead of 0, andHitTimeUs()returnsResult<uint32_t>(InvalidArgumentforkHitTimeContinuous) instead ofkForever, which is removed: no public helper returns a sentinel (handbook KB-CPP-126, KB-CPP-127).- A load-dependent diagnostic (
open_load_detect,plunger_detect,hit_current_check) needs its channel in the newConfig::loaded_channels;Validate(),ApplyConfig(),EnsureInitialized()andConfigureChannel()refuse it otherwise withInvalidArgument(KB-CPP-131). - The port concept checks the required hooks exactly: each parameter of
EnsureInitialized(),Transfer()andGpioSet()must have exactly the documented type, and each hook must benoexceptand returnbool(KB-CPP20-006).GpioSet()is part ofSpiPort. ADelayUs(),GpioRead()orLog()declared with another signature is a compile error (KB-CPP20-007). reg::kMaxSpiHzis replaced bykMaxClockHzwith the other bus requirements inmax22200_spi_interface.hpp.Erroris[[nodiscard]];GetConfig()isconst&-qualified and deleted on a temporary driver.EnsureInitialized()takes 48 transfers (was 46): it reads and clears FAULT.
Added¶
- Bus requirements as
constexpr(KB-CPP-123):kSpiMode,kMsbFirst,kMaxClockHz,kMinCsHighNs,kCsSetupNs,kCsHoldNs,kContinuousWord,kCmdSetupNs,kTransferBytes,kSdoOpenDrain, with datasheet references; the host and ESP32 ports and the documented port check their settings withstatic_assert. - A driver-owned latch of clear-on-read flags (KB-CPP-119): every 32-bit STATUS read ORs OVT and UVM into it, every
FAULT read the flags it clears;
GetLatchedFaults()andClearLatchedFaults(), no I/O. Only the clear empties it (a restart does not), and a reply a floating SDO produces is never latched (KB-CPP-116). - The start-up reads and clears FAULT and reports what was latched before it in
GetStartupFaults()(KB-CPP-058). ReadRegister(), a single-shot raw 32-bit read with no retry (KB-CPP-129).DecodePairMode(),ValidLoadDiagnostics(),Faults::Or()andFaults::And(),LatchedFaults.- Strict ISO C++20 everywhere (KB-CPP20-001):
CMAKE_CXX_EXTENSIONS OFF,-pedantic-errorsand the C++20 deprecations as errors; a header self-check per public header on GCC, Clang, the Cortex-M build and inside the ESP-IDF build (max22200_cxx20_check.cpp). - Compile-fail tests for a narrowed
Transfer()length, aTransfer()withoutnoexcept, aDelayUs(uint16_t), avoid GpioRead(), aGpioRead()taking the signal by value and a misdeclaredLog();tests/test_latch.cpp; compile-time round trips of the register encoders. -
The review skills
cpp20-profile,misra-reviewandhardware-lessons-reviewand thesafety-revieweragent, from the template. -
First version of the driver for the Analog Devices MAX22200 and MAX22200A octal solenoid and motor drivers, written on the Kokeb Labs driver template from datasheet 19-100531 Rev 1, every rule checked against the datasheet.
max22200::MAX22200<Port>with the configuration in the constructor and one start-up call,EnsureInitialized(): CMD high, ENABLE and tEN, the programming procedure of Figure 6 (STATUS read; a wake loop of bare ACTIVE = 1 writes, tWU and STATUS reads until ACTIVE reads 1 with UVM clear, bounded byConfig::wake_timeout_us, 100 ms by default; STATUS write, every CFG_CHn and CFG_DPM), and a read-back of every register and of each write's command echo. A wake that runs out returnsUndervoltage(UVM set) orTimeout, uninitialised with every channel off. COMER repeats the procedure (kStartAttempts).ApplyConfig()writes only what changed;Deinitialize()switches every channel off, clears ACTIVE and drives ENABLE low.- Switching from the driver's copy of ONCH, one 8-bit write each:
SetChannelsOn(),SetChannel()(parallel pairs switch as one),SetBridge()(Table 7);ReadChannelsOn(). The Command Register stays in force until rewritten (p25), so an ONCH write right after another is one transfer (the data byte); any other access, a failure, an ENABLE change, COMER or a read-back sends the command again. The data byte's STATUS[7:0] updatesGetLastStatusByte(). - Settings:
ConfigureChannel(),SetHoldCode()(8-bit HOLD update on the fly),SetPairMode(),SetFaultMask(),SetDpm();Verify::ReadBackper call reads the register back and checks COMER. A drive-mode, side or pair-mode change while a channel concerned is on is refused (Error::ChannelsActive). - Diagnostics:
ReadStatus()(power-on reset reported asError::DeviceReset),ReadFaults()andClearFaults()for both parts (Config::variant,Variant::Max22200by default: correct on both parts, a selective clear needsMax22200Adeclared per the BOM and a bench check),ReadFaultPin()through an optionalGpioRead()hook,GetLastStatusByte(). - After a read-back that differs the driver's copy takes the value read (ONCH, CFG_CH, HOLD, STATUS, CFG_DPM); the ONCH bits that differ stay untrusted, and a channel whose CFG_CH write failed or read back different accepts no write while a channel is on.
ChannelConfigandConfigas the registers' codes,Config{}equal to the reset state,Validate()andValidateChannel()with every datasheet rule; exact conversionsCurrentCode(),CurrentUa()(IFS / 128),HitTimeCode(),HitTimeUs(),DpmCurrentCode()(IFS / 127),DebounceUs(),ChopPeriodNs(),DutyLimitsOf(); Kconfig options for the part, the oscillator and RREF.- Errors
NoDevice,Pin,CommunicationError,WriteMismatch,Undervoltage,ChannelsActive,DeviceReset. - Host tests over a protocol model of both parts, written from the datasheet independently of the driver's register header and cross-checked against it, with the bus and board faults the port contract allows, every transfer and pin write of every operation failed in turn; a libFuzzer target with its corpus replayed as a CTest; the host and ESP32 examples; the Drive modes and Status and limitations pages. Not verified on hardware.
Datasheet rules the first version applies. Details on the Status and limitations page:
- CDR currents use IFS / 128 (Table 4); no current becomes code 127, the unregulated full-on state.
- HIT times use the exact chopping frequency (33.3 kHz, 26.7 kHz, Tables 1 and 5); a HIT time beyond 254 steps is refused instead of becoming "continuous IHIT".
- COMER is tested as a bit of the fault byte (Figure 6), never by comparing the whole byte.
- The selective FAULT clear sends its mask LSB byte first, where Figure 8 draws it; not verified on hardware: it is
one constant,
reg::kFaultClearLsbByteFirst, and a bench step decides. A FAULT read on the MAX22200A clears only what SDI selects. - VDR duty codes are sent as asked, so 0 % and 100 % are reachable (Table 3); the chip applies δMIN and δMAX itself.
- SRC at 50 kHz, CDR, SRC, HFS or DPM on the high side, and HHF in VDR are refused.
- The start-up wakes the chip with bare ACTIVE writes until ACTIVE reads 1 with UVM clear (Figure 6), bounded by
Config::wake_timeout_us. COMER is not assumed to clear on a STATUS read (p36: "Read Only"): it is armed once the wake is done, only a 0 to 1 transition repeats the procedure, and ENABLE goes low for tDIS and high for tEN between attempts. - CMD idles high: it is driven high again after every data phase, the one-transfer ONCH write included (p25-26).
Config::rref_ohmis not given by default (kNoRref): the code-level API works without it, andCurrentCode(),CurrentUa()andDpmCurrentCode()returnInvalidArgumentuntil it is set.- CFG_DPM is compared on bits 14:0 only: bits 31:15 are reserved, three of them read only with no reset value (p40-41).
- Mode and pair-mode changes are refused while the channels concerned run (step 5c, Register Details); parallel pairs switch both ONCH bits (Table 6); out-of-range DPM settings are refused instead of clamped; shutdown reports its writes.
Changed¶
- Hardware page: the pinout, the block diagram and the application circuit are now figures drawn from
docs/hardware.yml, which also generates the pin table (replacing the hand-written one) and the parts table. Every pin, block and part cites the datasheet section and page; values the datasheet does not give are marked as not confirmed.kokeb-docs hardware --kicad-netlistexports the circuit. - Synced with the driver template:
tools/preflight.shruns clang-tidy over every file CI lints, as CI does, and the hardware-lessons review adds the switch-off lessons. The fault-handling example in the API guide clears the overcurrent channels with unsigned bit operations, which that clang-tidy run requires. - 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, channels in doubt and a model that changes state on its own.- Follows the driver template's portable ownership: copyright belongs to
The driver-max22200 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.HasGpioReadmatchesbool GpioRead(CtrlPin, GpioSignal&) noexceptthe same way, so a hook that takes the signal by value or asconst&still does not match. - Include guards instead of
#pragma oncein every header (KB-CPP-019). - Every narrow operand of a shift or bitwise operator is widened to
uint32_tfirst, andULliterals andunsignedcasts are fixed-width (KB-CPP20-020, -021); enumerations are range-checked withdetail::IsEnumerator()(KB-CPP20-025);ToString()is a switch over every enumerator. - The ESP32 port sets CMD high and ENABLE low before it enables their outputs (KB-HW-018); the Porting page lists each control pin's idle level and polarity.
- The data phases go through fixed-extent
std::spans (KB-CPP20-042). - MISRA C++:2023 conformance: integer constant arguments have exactly the parameter's type through the
constevalliteralsdetail::operator""_u8andoperator""_u32(EncodeStatus(config_, 0_u8, true),FaultClearSdi(0xFFFF'FFFF_u32); an out-of-range literal does not compile), and a narrow ONCH bit is widened explicitly (Rule 7.0.6); the layout checks compare againstUliterals (Rule 7.0.5); operands of&&,||,?:and comparisons are parenthesised (Rule 8.0.1); every switch over an enumeration ends withdefault: break;, and the host tests build with-Wswitch-enumso a new enumerator still warns (Rule 9.4.2); the five defaultedoperator==are hidden friends (Rule 16.6.1); the.ippinclude at the end ofmax22200.hppcarries the deviation marker of MD-CPP-009 (Rule 19.0.3). Behaviour is unchanged. - Synced with driver-template:
_config/.clang-tidy(the handbook's high-level profile), the repository checks with the handbook's source checks, theverify,add-driver-featureandnew-driver-from-templateskills.
Fixed¶
- A
SetChannelsOn()that returnsUncertainno longer skips its write while a switch-off is unverified: a switch-off that no fault byte with COMER clear has vouched for yet (the chip may have miscounted it, and the next fault byte may have been lost on the bus) counts as possibly on, so a mask that asks that channel off goes out again. - Doubt that a write settles is no longer lost when the chip miscounts that very write (p34, p36): a switch-off, a STATUS write that carries ONCH, CMxy or FREQM moves the doubt it clears into the unverified sets, so the COMER that follows restores it; with COMER already set a STATUS write keeps the doubt until a read-back, and a read-back that matches proves every switch.
- A configuration write (CFG_CHn, HOLD, STATUS, CFG_DPM) whose command byte shows a new COMER stops before its data
phase and returns
CommunicationError: the channels the miscount left in doubt may be on, so a drive-mode change would be ignored by the chip (Programming Procedure 5c). ONCH writes are never stopped, so a switch-off always goes out. - While COMER stays set (detection degraded),
ConfigureChannel()reads its write back (2 more transfers), and a CFG_CH or STATUS write without a read-back leaves the channel's mode, or the pair modes and FREQM it changes, in doubt: a miscounted configuration write cannot show then, so it is never trusted. tools/preflight.shfollows the template: clang-tidy runs as CI runs it. A signed-bitwise finding it then reported in the fault-handling example of the API guide is fixed.- A power-on reset (UVLO, p22) is detected by every call from the fault byte of its command, before the data phase:
no write reaches the reset chip, so no setter re-activates it with the cached ONCH over reset CFG_CHn values. The
driver marks itself uninitialised with every channel off and returns
DeviceReset. A STATUS value with ACTIVE = 0 does the same. A one-transfer ONCH write that gets no fault byte back (0xFF) sends its command again so the reset shows. - Flags the chip clears by itself (OLF on a switch-on, p21; HHF on a new cycle, p23) are no longer lost: the summary
flags of every fault byte (OVT, UVM, OCP, OLF, HHF, DPM) go into
GetLatchedFaults()at no extra I/O. - A miscounted write (COMER, p34) is no longer reported as
Okfor ever: the first call that sees COMER go from 0 to 1 returnsCommunicationError; the ONCH bits the writes since the last clean fault byte changed count as on forChannelsActive, their channels as of either drive mode, andApplyConfig()writes their registers again. - A write whose reply failed may have taken effect: a pair mode or FREQM it changed is unknown until a STATUS write
(pair off) or read-back settles it, a switch in that pair returns
Uncertain,ConfigureChannel()accepts only a channel valid at both clocks, andApplyConfig()writes the register again even when the copy matches. A channel that may run either drive mode is written, its own cached value included, only with every channel off, so the write settles the mode. - A COMER the wake leaves is cleared at start-up with ENABLE low, and while COMER stays set on a running driver every
switch-off is read back (2 more transfers each), so miscount detection never stays off silently;
IsMiscountDetectionDegraded()reports that state. A switch-off miscounted in the very call that first shows the COMER keeps its channels in doubt (they count as on and are switched off again when asked), and so does a switch-off whose forced read-back fails. - Read data of all ones is followed by one more command byte, so a reset between a read's command byte and its data
returns
DeviceResetinstead of the floating value. - A STATUS read, or a FAULT read that clears, that fails or gets a floating reply sets
LatchedFaults::lost: the flags it cleared are unknown. A genuine FAULT of 0xFFFFFFFF with a 0xFF fault byte is treated the same, never used as data. - A STATUS read-back (
SetPairMode(),SetFaultMask()withVerify::ReadBack) cleared OVT and UVM on the chip and dropped them; they are kept in the latch. - Faults latched before the start held the FAULT pin after a clean start; the start-up now clears them.
- A STATUS read-back with the reserved CMxy value 3 stored it as a
PairMode; it is refused and the copy keeps its mode. ApplyConfig()on a running driver dropped a newwake_timeout_us; it is kept, as is the newloaded_channels.