Skip to content

Quickstart

From a bare chip to a moving motor: wire it, write the port, declare the motor, move it.

Datasheet sections this page relies on

From Analog Devices (Trinamic) TMC5160A-DS 1.18:

  • Package, pins and signal descriptions: 2 Pin Assignments, p. 11
  • Quick configuration guide: 22 Quick Configuration Guide, p. 111
  • Initialization examples: 23.1 Initialization Examples, p. 116

All of them, with the driver API for each: Datasheet map.

1. Wire it

SPI is the default bus. The pins are in Hardware; the minimum is SCK, MOSI, MISO, CSN, VCC_IO, ground, the motor supply and the bridge, with SPI_MODE high, SD_MODE low and CLK low for the internal 12 MHz clock. Wire DRV_ENN to a GPIO: the driver then switches the power stage in Enable() and Disable(). For UART, tie SPI_MODE and SD_MODE low and use the single wire on DIAG1_SWP (UART protocol).

Before the first power-up: the sense resistor must be the one you declare, and the motor's rated current must be the one on its data sheet. The driver derives every current register from those two numbers.

2. Write the port

The port is a class with EnsureInitialized(), Transfer() and DelayUs(). Porting has the contract.

class MyPort : public tmc5160::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 transfer, CS low for all `len` bytes (5 bytes per chip in a chain). `rx` is never nullptr.
  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 ramp-down waits, the tuning wait and the UART recovery
  // depend on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

3. Declare the motor and move it

#include "tmc5160.hpp"

int spin_one_revolution(MyPort& port) {
  // 1. Declare the motor and the board. The driver derives every current register from these two.
  const tmc5160::Config config =
      tmc5160::MakeConfig(tmc5160::Motor{.rated_rms_ma = 1000, .coil_resistance_mohm = 6000},
                          tmc5160::Board{.rsense_mohm = 100, .supply_mv = 24'000});
  tmc5160::TMC5160<MyPort> motor(port, config); // no I/O yet

  if (auto r = motor.EnsureInitialized();
      !r) {                           // 2. bus, strap, VERSION, every register, driver off
    return static_cast<int>(r.error); //    Bus, Timeout, DeviceIdMismatch, InvalidArgument ...
  }
  if (auto r = motor.Enable(); !r) { // 3. DRV_ENN active, TOFF written
    return static_cast<int>(r.error);
  }
  if (auto r = motor.MoveTo(51'200); !r) { // 4. one revolution at 256 microsteps, 200 full steps
    return static_cast<int>(r.error);
  }
  return 0; // poll PositionReached(); Disable() when done
}

What each step does:

  1. MakeConfig() fills a Config with the datasheet's reset values, a run current of 85 percent of the motor's ceiling and a hold current of 30 percent of the run current. Config{} alone is not usable: it has no motor and no sense resistor, so Validate() rejects it.
  2. EnsureInitialized() brings the bus up, reads IOIN to check the strap and the version byte (0x30), clears the reset flag, writes every register in a safe order with the driver off, and optionally verifies the writes (Config::verify). On a failure it leaves the chip with the driver off.
  3. Enable() reads the global status first: after a chip reset or a driver fault it refuses (UnexpectedReset, DeviceFault), because the write-only registers would be at their reset values. On UART it also checks that the interface counter counted every write.
  4. MoveTo() writes XTARGET in position mode. Poll PositionReached(); Stop(), Hold() and Disable() end the move.

4. Try it without hardware

The host examples run the same calls against a simulated chip: Examples.

If it does not work

Troubleshooting lists each error with its usual cause. The first two to check: DeviceIdMismatch (wrong chip, wrong SPI mode, MISO stuck) and ModeMismatch (the strap does not match the bus).