Skip to content

Porting

Run the driver on a new MCU by writing one class: the port, on SPI or on UART.

Datasheet sections this page relies on

From Analog Devices (Trinamic) 19-101926 1:

  • Pin functions at power-up and the UART and SPI of the bootloader: General-Purpose Input/Output Description, p. 19

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 tmc9660::SpiInterface<Self> (in inc/tmc9660_spi_interface.hpp) or from tmc9660::UartInterface<Self> (in inc/tmc9660_uart_interface.hpp), not both. The base uses CRTP and declares no hook itself; the driver template is constrained by the concept AnyPort, 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

Method Bus Required Contract
bool EnsureInitialized() noexcept both yes Bring the bus up on the first call; return true at once afterwards. false makes the driver's EnsureInitialized() return Bus
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept SPI yes One full-duplex transfer of len bytes with chip select low for all of them; rx is always given. false on any bus error
BusStatus Exchange(const uint8_t* tx, std::size_t tx_len, uint8_t* rx, std::size_t rx_len, uint32_t timeout_us) noexcept UART yes Send tx_len bytes without gaps, then receive exactly rx_len bytes within the timeout. BusStatus::Ok, Timeout or Fault. Remove the echo of your own bytes on a shared wire and drive the transceiver direction
void DelayUs(uint32_t us) noexcept both yes Wait at least us microseconds. A port without it does not compile
bool GpioSet(CtrlPin, GpioSignal) noexcept both no Drive RSTN, DRV_EN or WAKE at the logical level; false if the pin write failed
bool GpioGet(CtrlPin, bool& high) noexcept both no Read FAULTN (or another control pin); false if the read failed
void Log(LogLevel, const char* message) noexcept both no Print one line; message is plain text, never a format string

The SPI port

my_port.hpp
class MyPort : public tmc9660::SpiInterface<MyPort> {
public:
  // Bring the bus up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_spi_init();
    }
    return ready_;
  }

  // One datagram, CS held low for all `len` bytes. `tx` and `rx` both have `len` bytes.
  bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept {
    return platform_spi_transfer(tx, rx, len);
  }

  // Wait at least `us` microseconds: the chip's reply gap and boot times depend on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Rules the transfer must follow:

  • One call, one frame. Keep chip select low for all len bytes; the chip decodes the frame when it rises. The frames are 5 (bootloader), 8 (parameter mode) and 6 (register mode) bytes.
  • The bus requirements below: mode 3, MSB first, up to kMaxClockHz. Start at 1 MHz on jumper wires.
  • Raw bytes only. Do not interpret, retry or reorder bytes; the driver owns the framing and the retries.
  • Return false for a bus error. The driver turns it into Error::Bus and never ignores it.
  • Bounded time-outs. A stuck bus fails the call; it does not block forever.
  • Idle levels. Chip select high and SCK high (mode 3) before the first transfer, so that the chip never sees a partial frame.

The UART port

my_port.hpp
class MyUartPort : public tmc9660::UartInterface<MyUartPort> {
public:
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_uart_init();
    }
    return ready_;
  }

  // Throw away stale received bytes, send the request, then wait for exactly `rx_len` bytes. With
  // `tx_len == 0` send nothing and only drain what is waiting (the driver does this after a failed
  // exchange). The driver tells timeouts from line faults.
  tmc9660::BusStatus Exchange(const uint8_t* tx, std::size_t tx_len, uint8_t* rx,
                              std::size_t rx_len, uint32_t timeout_us) noexcept {
    const int r = platform_uart_exchange(tx, tx_len, rx, rx_len, timeout_us);
    if (r == 0) {
      return tmc9660::BusStatus::Ok;
    }
    if (r == 1) {
      return tmc9660::BusStatus::Timeout;
    }
    return tmc9660::BusStatus::Fault;
  }

  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Rules the exchange must follow:

  • One call, one request. Send the whole request without a pause between bytes; two documents disagree on how long a gap may be before the chip drops a partial message (ambiguity A6), and a request without gaps avoids the question.
  • Receive exactly rx_len bytes, or report Timeout (nothing arrived) or Fault (framing or overrun). Never return partial data as Ok.
  • 8N1, least significant bit first, at the rate the chip has: it detects the rate of the first bytes (9600 to 250000 at the 40 MHz clock), or the boot configuration sets it.
  • Half duplex. On a shared RS-485 wire, enable the transmitter for the request and the receiver for the reply, and discard the echo.

Bus requirements

The driver states what the TMC9660 needs from the bus as constexpr values in the two interface headers (handbook KB-CPP-123). Check your port's settings against them with static_assert, as both example ports do, so a port that clocks too fast or in the wrong mode does not compile:

Constant Value Meaning
kSpiMode 3 CPOL 1, CPHA 1
kMsbFirst true Most significant bit first
kMaxClockHz 10'000'000 f_SCK max
kCsHoldNs 100 SCK edge to chip select change, t_CC
kContinuousWord true A datagram is one chip select low period
kMinCsHighNs 100 Chip select high between two datagrams
kClockPhaseNs 20 SCK low and high time
kDataSetupNs 20 Data setup and hold
kUartDataBits 8 8N1
kMaxBaudRate 5'000'000 Highest baud rate
kTurnaroundUs 1000 Assumed reply wait (ambiguity A19); the port timeout adds the frame time
kMaxAutobaudRate 250'000 Highest rate the chip detects at 40 MHz

Control pins

GpioSet() takes a CtrlPin and a logical GpioSignal; the port maps them to the physical level:

Pin ACTIVE means The port writes
CtrlPin::Reset The chip is held in reset RSTN low
CtrlPin::DrvEn The gate driver outputs are allowed DRV_EN high
CtrlPin::Wake The wake condition is asserted WAKE high

Make the pins idle in their safe state (RSTN released, DRV_EN low) before the first transfer; the driver never assumes it. A hardware reset at start is Config::hardware_reset:

Hardware reset at start
tmc9660::Config WithHardwareReset() {
  tmc9660::Config c{};
  c.hardware_reset =
      true; // the start pulses RSTN (after DRV_EN low); a port without GpioSet gets Unsupported
  return c;
}

A full port with every hook:

A port with every optional hook
class FullPort : public tmc9660::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);
  }

  // Required by every call that waits (the reply gap, boot and PLL times).
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

  // Optional: RSTN and DRV_EN on GPIOs. ACTIVE means "asserted": RSTN is active low, DRV_EN active
  // high.
  bool GpioSet(tmc9660::CtrlPin pin, tmc9660::GpioSignal signal) noexcept {
    const bool active = (signal == tmc9660::GpioSignal::ACTIVE);
    if (pin == tmc9660::CtrlPin::Reset) {
      return platform_gpio_write(kResetGpio, !active);
    }
    if (pin == tmc9660::CtrlPin::DrvEn) {
      return platform_gpio_write(kDrvEnGpio, active);
    }
    return false; // WAKE is not wired
  }

  // Optional: FAULTN, an open-drain output of the chip. `high` is the pin level.
  bool GpioGet(tmc9660::CtrlPin pin, bool& high) noexcept {
    if (pin != tmc9660::CtrlPin::Faultn) {
      return false;
    }
    return platform_gpio_read(kFaultnGpio, high);
  }

  // Optional: one line per lifecycle event or failure. The driver never formats; the port does.
  void Log(tmc9660::LogLevel level, const char* message) noexcept {
    if (level > tmc9660::LogLevel::Warning) {
      return;
    }
    platform_log(message); // plain text: never use it as a format string
  }

private:
  static constexpr int kResetGpio = 7;
  static constexpr int kDrvEnGpio = 8;
  static constexpr int kFaultnGpio = 9;
};

A GpioSet() that returns void is a compile error: the driver must see a failed pin write. The compile-fail tests check this rule and the others.

Reference implementations

Every port lives with its example, in examples/<platform>/; the driver has none. Platforms lists them and how to add one.

Check your port

  1. Build it: the ports on this page are compiled by the host CI from tests/docs/, with the driver instantiated over them.
  2. Call EnsureInitialized() with Mode::Bootloader on a freshly powered chip: Ok proves that the frames are moved correctly and that the chip identity read 0x544D0001.
  3. Call BlGetInfo(BlInfo::ChipFrequency): a plausible clock confirms a second, different frame.
  4. Only then start the application (BlStartApplication()) and read a parameter or a register.

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.