Quickstart¶
Run the driver on your PC first, with no hardware; then open a valve from your MCU: wire the chip, write a small port class, call two driver functions.
Datasheet sections this page relies on
From Analog Devices 19-100531 1:
- Pins, CMD, ENABLE, FAULT and the TRIG inputs: Pin Configuration; Pin Description, p. 12
All of them, with the driver API for each: Datasheet map.
Try it on your PC¶
examples/host/ runs the real driver against a simulated MAX22200, through a host
port. From the repository root, with CMake and a C++20 compiler:
cmake -S examples/host -B build-example
cmake --build build-example
./build-example/max22200_host_example
MAX22200 driver 0.1.0 on the host
max22200: initialised
HIT 500000 uA for 20800 us, HOLD 148437 uA
ONCH 0x01, flags 0x00
faults on channels 0x00
The calls in main.cpp are the ones below; only the port differs on an MCU. CI builds
and runs this example on every pull request.
1. Wire it¶
| MCU | MAX22200 | Notes |
|---|---|---|
| SPI SCK | SCK | Mode 0, up to 10 MHz; 1 MHz for bring-up on jumper wires |
| SPI MOSI | SDI | |
| SPI MISO | SDO | Open drain: fit a pull-up (1 kΩ to 4.7 kΩ to the MCU's supply) |
| GPIO (chip select) | CSB | Low for each transfer |
| GPIO | CMD | High while the command byte is written |
| GPIO | ENABLE | Or tie it high |
| IREF | 15 kΩ to ground: IFS = 1 A | |
| 24 V (4.5 V to 36 V) | VM | 0.1 µF at each VM pair, 10 µF bulk |
| GND | GND, EP |
Connect the valve from OUT0 to VM (low side). FAULT, TRIGA and TRIGB can stay unconnected for this example (TRIG has a pull-down). The Hardware page has the full pin list, the timing and the power.
2. Add the driver¶
Add the repository as a submodule and link the max22200::max22200 CMake target. Installation
covers CMake on any MCU, the installed package and ESP-IDF.
git submodule add https://github.com/kokeb-labs-drivers/driver-max22200.git external/driver-max22200
3. Write the port¶
The port is the only platform code: it brings the bus up, moves bytes and drives two pins. Replace the
platform_* calls with your SDK's.
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;
};
Porting explains each method, the optional hooks and the transfer rules.
4. Open the valve¶
#include "max22200.hpp"
int open_valve_0(MyPort& port) {
max22200::Config cfg{};
cfg.rref_ohm = 15000; // IFS = 15k x 1 V / 15 kohm = 1 A
max22200::ChannelConfig& v = cfg.channels[0];
v.hit = max22200::CurrentCode(600, cfg.rref_ohm, false).value; // 600 mA peak to pull in
v.hold = max22200::CurrentCode(200, cfg.rref_ohm, false).value; // 200 mA to hold
v.hit_time = max22200::HitTimeCode(30000, cfg.clock, v.chop).value; // 30 ms of HIT
static max22200::MAX22200<MyPort> chip(port, cfg); // no I/O yet
if (auto r = chip.EnsureInitialized(); !r) { // ENABLE, Figure 6, read-back of every register
return static_cast<int>(r.error); // NoDevice, DeviceIdMismatch: check the wiring
}
if (auto r = chip.SetChannel(0, true); !r) { // one 8-bit write: 2 transfers, then 1 per switch
return static_cast<int>(r.error);
}
return 0; // HIT for 30 ms, then HOLD until SetChannel(0, false)
}
What each step does:
- The
Configdeclares RREF, so the driver can turn milliamps into the chip's codes:CurrentCode()gives 600 mA as code 77 (77/128 x 1 A) and refuses a current it cannot regulate;HitTimeCode()gives 30 ms at 25 kHz as 19 steps of 1.6 ms (30.4 ms). EnsureInitialized()drives ENABLE high, waits tEN, runs the datasheet's programming procedure (STATUS read, STATUS write with ACTIVE = 1, every CFG_CHn, CFG_DPM), waits tWU and reads every register back.SetChannel(0, true)is one 8-bit write of ONCH (2 transfers; the next switch is 1). The chip drives HIT for 30 ms, then HOLD, untilSetChannel(0, false).
This example is built by the host CI, so it compiles against the current headers. It is not verified on hardware (Status and limitations).
If it does not work¶
| Symptom | First thing to check |
|---|---|
EnsureInitialized() returns Bus |
Your port's EnsureInitialized() or Transfer() returned false |
EnsureInitialized() returns NoDevice |
SDO reads 0xFF: VM, ENABLE, the SDO pull-up (Troubleshooting) |
EnsureInitialized() returns DeviceIdMismatch |
SDI, CMD or CSB do not reach the chip |
EnsureInitialized() returns Undervoltage |
VM is below about 4 V, or still rising |
| The valve does not move | IREF and RREF, the HIT current against the valve's pull-in current, ReadFaults() |
Next¶
- API guide: switching, HOLD on the fly, faults, errors.
- Drive modes: CDR and VDR, HIT and HOLD, bridges, DPM.
- Configuration: every
Configfield, Kconfig. - Examples: the host example and the MCU examples.