Porting¶
Run the driver on a new MCU by writing one class: the port.
Datasheet sections this page relies on
From Analog Devices 19-100531 1:
- Enable, wake-up and disable times; SPI timing: Electrical Characteristics (tEN, tWU, tDIS, SPI); Figure 1, p. 10
- Pins, CMD, ENABLE, FAULT and the TRIG inputs: Pin Configuration; Pin Description, p. 12
- The SPI, the 8-bit accesses and the daisy chain: SPI Detailed Description; Figure 5, p. 23
- The Command Register and the fault byte: Command Register Description (COMMAND); Table 9; Figure 7, p. 25
- 32-bit and 8-bit transfers and the command echo: Reading and Writing Operations of Registers; Figures 10 to 13, p. 30
All of them, with the driver API for each: Datasheet map.
The driver never calls your SDK. It calls hooks on a class you derive from max22200::SpiInterface<Self> (in
inc/max22200_spi_interface.hpp). The base uses CRTP and declares no hook
itself; the driver template is constrained by the max22200::SpiPort concept, so calls are resolved at compile
time (no virtual functions, nothing to allocate) and a missing or misdeclared hook is a compile error at the point
of use.
What you implement¶
| Hook | Required | Contract |
|---|---|---|
bool EnsureInitialized() noexcept |
yes | Bring the bus, CMD and ENABLE up on the first call, each pin at its idle level before it becomes an output (below); true at once afterwards |
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept |
yes | One full-duplex transfer of 1 or 4 bytes, both buffers given, CSB low for all of them and high after |
bool GpioSet(CtrlPin pin, GpioSignal signal) noexcept |
yes | Drive CtrlPin::Cmd or CtrlPin::Enable; false when the pin could not be driven |
void DelayUs(uint32_t us) noexcept |
yes | Wait at least us microseconds: tEN (500 µs) and tWU (2500 µs) at start-up |
bool GpioRead(CtrlPin pin, GpioSignal& signal) noexcept |
no | Read CtrlPin::Fault: ACTIVE while the pin is low |
void Log(LogLevel level, const char* message) noexcept |
no | One line per lifecycle event or failure; plain text, never a format string |
The required hooks are checked exactly by the SpiPort concept: each parameter must have exactly the type above
and each hook must be noexcept and return bool. A Transfer() that takes a uint16_t length, or a GpioSet()
without noexcept, is a compile error, not a silent conversion (handbook KB-CPP20-006). An optional hook that is
declared with another signature (void GpioRead(...), DelayUs(uint16_t)) is a compile error too, never ignored
(KB-CPP20-007).
Bus requirements¶
What the chip needs from the bus is in max22200_spi_interface.hpp as constexpr values (handbook KB-CPP-123). Check
your port's settings against them with static_assert, as the host and ESP32 ports do:
| Constant | Value | From |
|---|---|---|
kSpiMode |
0 (CPOL = 0, CPHA = 0) | SPI Detailed Description, p23 |
kMsbFirst |
true | Figure 1 |
kMaxClockHz |
10 000 000 (tCLK 100 ns; the SDO pull-up may set less) | Electrical Characteristics, SPI rows, p10 |
kMinCsHighNs |
30 (tCSPW) | the same |
kCsSetupNs |
30 (tCSS) | the same |
kCsHoldNs |
30 (tCSH) | the same |
kContinuousWord |
false: no limit on idle SCK time inside a transfer | the chip counts clocks while CSB is low (p34) |
kCmdSetupNs |
20 (tCMS); tCMH has no value | Electrical Characteristics, Figure 1 |
kTransferBytes |
1 and 4: the only lengths the driver asks for | Figures 10 to 13 |
kSdoOpenDrain |
true: fit a pull-up on SDO | Pin Description, p12 |
The port below checks its clock this way (kClockHz).
Control pins and their idle levels¶
The port drives each control output to its idle level before it enables the pin's output driver and before the first transfer (handbook KB-HW-018): set the level, then configure the pin as an output.
| Pin | CtrlPin |
Polarity | Idle level | Why |
|---|---|---|---|---|
| CMD | Cmd |
active high: ACTIVE = high selects the Command Register |
high (ACTIVE) |
The Command Register is written with CMD high for the whole transfer and at the CSB rising edge (p25-26); only a data phase lowers it |
| ENABLE | Enable |
active high: ACTIVE = high wakes the chip |
low (INACTIVE) |
The chip sleeps, every output Hi-Z, until EnsureInitialized() raises it |
| FAULT | Fault |
open drain, active low: ACTIVE = low = a fault |
input with a pull-up | Read only (GpioRead()) |
Timing¶
The bus: SPI mode 0, MSB first, up to 10 MHz. The driver calls Transfer() once for the command byte (with CMD
high) and once for the data (with CMD low), then drives CMD high again: CMD idles high between transactions, and your
port's EnsureInitialized() should leave it high. Never more than 4 bytes, so a polling transfer is fine. CSB must go high
between the two. GpioSet(CtrlPin::Cmd, ...) must have taken effect before Transfer() starts (tCMS, 20 ns before
the CSB falling edge, Figure 1) and CMD must still be high when CSB rises (p26), then for tCMH, for which the
datasheet gives no value: a GPIO write that returns after the pin changed, before and after Transfer(), does both.
A board that ties ENABLE high returns true for CtrlPin::Enable and does nothing.
tEN and tDIS are minimum waits: the driver calls DelayUs() for them after GpioSet() returns. A pin behind a slow
I/O expander adds its latency on top and never shortens them; it does stretch every CMD toggle, so put CMD on an MCU
pin where you can.
The port moves raw bytes: it never retries, never interprets the data and never configures the chip.
The port¶
class MyPort : public max22200::SpiInterface<MyPort> {
public:
// The bus settings platform_spi_init() uses, checked against the driver's requirements.
static constexpr uint32_t kClockHz = 1'000'000;
static_assert(kClockHz <= max22200::kMaxClockHz, "above the MAX22200's tCLK limit");
static_assert(max22200::kSpiMode == 0 && max22200::kMsbFirst, "set the bus to mode 0, MSB first");
// Bring the bus up once, CMD at its idle level high and ENABLE low before either pin becomes an
// output; later calls return true at once.
bool EnsureInitialized() noexcept {
if (!ready_) {
ready_ = platform_spi_init();
}
return ready_;
}
// One transfer: 1 byte (command or 8-bit data) or 4 bytes (32-bit data), CSB low throughout.
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept {
return platform_spi_transfer(tx, rx, len);
}
// CMD and ENABLE are both active high. Return false when the pin could not be driven.
bool GpioSet(max22200::CtrlPin pin, max22200::GpioSignal signal) noexcept {
const bool high = signal == max22200::GpioSignal::ACTIVE;
switch (pin) {
case max22200::CtrlPin::Cmd:
return platform_gpio_write(kCmdGpio, high);
case max22200::CtrlPin::Enable:
return platform_gpio_write(kEnableGpio, high); // tied high on the board? return true
case max22200::CtrlPin::Fault: // an input: never driven
default:
break;
}
return false;
}
// Wait at least `us` microseconds: tEN (0.5 ms) and tWU (2.5 ms) at start-up.
void DelayUs(uint32_t us) noexcept {
platform_delay_us(us);
}
private:
static constexpr int kCmdGpio = 5;
static constexpr int kEnableGpio = 6;
bool ready_ = false;
};
Optional hooks¶
A port with every hook, as the ESP32 example has:
class FullPort : public max22200::SpiInterface<FullPort> {
public:
bool EnsureInitialized() noexcept {
return platform_spi_init();
}
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept {
return platform_spi_transfer(tx, rx, len);
}
bool GpioSet(max22200::CtrlPin pin, max22200::GpioSignal signal) noexcept {
const bool high = signal == max22200::GpioSignal::ACTIVE;
if (pin == max22200::CtrlPin::Cmd) {
return platform_gpio_write(kCmdGpio, high);
}
return pin == max22200::CtrlPin::Enable && platform_gpio_write(kEnableGpio, high);
}
void DelayUs(uint32_t us) noexcept {
platform_delay_us(us);
}
// Optional: the FAULT pin, open drain and active low. ACTIVE means a fault, a low level.
bool GpioRead(max22200::CtrlPin pin, max22200::GpioSignal& signal) noexcept {
bool high = true;
if (pin != max22200::CtrlPin::Fault || !platform_gpio_read(kFaultGpio, high)) {
return false;
}
signal = high ? max22200::GpioSignal::INACTIVE : max22200::GpioSignal::ACTIVE;
return true;
}
// Optional: one line per lifecycle event or failure. The driver never formats; the port does.
void Log(max22200::LogLevel level, const char* message) noexcept {
if (level > max22200::LogLevel::Warning) {
return;
}
platform_log(message); // plain text: never use it as a format string
}
private:
static constexpr int kCmdGpio = 5;
static constexpr int kEnableGpio = 6;
static constexpr int kFaultGpio = 7;
};
With GpioRead(), ReadFaultPin() reads the FAULT pin without SPI; without it, it returns Unsupported. A use:
// In the FAULT interrupt's deferred handler (never in the ISR: it uses the bus).
max22200::Result<max22200::Faults> OnFaultPin(max22200::MAX22200<FullPort>& chip) {
const auto pin = chip.ReadFaultPin(); // no SPI
if (!pin || !pin.value) {
return max22200::Result<max22200::Faults>::Failure(pin.error);
}
return chip.ReadFaults(); // which channel, which fault; the MAX22200A keeps the flags
}
A GpioSet() that returns void, or none at all, is a compile error: the driver must see a failed pin write, and
CMD is part of the protocol. A missing DelayUs() is a compile error too. The compile-fail tests
check each rule.
Reference implementations¶
Every port lives with its example, in examples/<platform>/; the driver has none. Platforms lists
them and how to add one.
examples/host/host_max22200_port.hpp: any PC, against a simulated chip. Start from it for a host build or a test bench; it is also the smallest complete port.examples/esp32/main/esp32_max22200_port.hpp: ESP-IDF, with every hook. Start from it for any ESP-IDF target.
Check your port¶
- Build it: the ports on this page are compiled by the host CI from
tests/docs/, with the driver instantiated over them. - Call
EnsureInitialized():Okproves that CMD, ENABLE, SDI and SDO work: every 32-bit write echoed its command and every register read back what was written.NoDevicemeans SDO reads 0xFF (no supply, ENABLE low, no pull-up);DeviceIdMismatchmeans the chip did not take or echo the commands (SDI, CMD or CSB). - With a load on channel 0:
SetChannel(0, true, Verify::ReadBack)returnsOk, the load is energised, andReadFaults()shows no OLF for channel 0 while it is on. Not verified on hardware with this driver yet.
Threads¶
The driver is not thread-safe. Give each driver object one owner task, or guard every call with one mutex. When several chips share a bus, the port must also serialise the bus. See Contract.
Editor setup¶
The clang-format and clang-tidy configuration is in _config/, and the repository root has no copy of it. Tools
that take a path use it directly; CI does the same:
| Tool | Setting |
|---|---|
| Command line | clang-format --style=file:_config/.clang-format, clang-tidy --config-file=_config/.clang-tidy -p build |
| VS Code (C/C++ extension) | "C_Cpp.clang_format_style": "file:${workspaceFolder}/_config/.clang-format" and "C_Cpp.codeAnalysis.clangTidy.args": ["--config-file=${workspaceFolder}/_config/.clang-tidy"] |
| clangd (VS Code clangd, Neovim, Emacs), CLion | These find .clang-format and .clang-tidy only by name, from the file upwards: copy both to the root once (cp _config/.clang-format _config/.clang-tidy .). .gitignore lists the copies, so they never reach a commit; copy again after _config/ changes |
Configure with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON (clangd: --compile-commands-dir=build) so the editor sees the
same flags as the build.