Skip to content

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.

my_port.hpp
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

main.cpp
#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:

  1. The Config declares 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).
  2. 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.
  3. 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, until SetChannel(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