Skip to content

API guide

The driver's API by task, with code that compiles: start, set the current, move, tune, watch, handle errors and stop.

The shape of the API

Group Calls Page
Lifecycle EnsureInitialized(), IsInitialized(), Enable(), Disable(), Deinitialize() below
Current SetCurrent() and the declared motor Current and limits
Motion MoveTo(), MoveBy(), RunVelocity(), Stop(), SetRamp(), PositionReached() Motion
Chopper SetChopper(), SetStealthChop(), SetThresholds() Chopper
Load SetStallGuard(), SetStopOnStall(), ReleaseStall(), CoolStep StallGuard and CoolStep
Status Service(), ReadRampStatus(), ClearFaults() Diagnostics and status
Guards Ack, Verify Guards

Every call that touches the chip returns Result<T>: check ok() (or the bool conversion) and read value, or read error. Result is [[nodiscard]], so an unchecked call is a compiler warning.

Start, enable, stop

// Start, enable, stop. Every call returns a Result: check it.
tmc5160::Error RunAndStop(Motor& motor) {
  if (auto r = motor.EnsureInitialized(); !r) { // writes every register; the driver stays off
    return r.error;
  }
  if (auto r = motor.Enable(); !r) { // refuses after a chip reset or a driver fault
    return r.error;
  }
  if (auto r = motor.RunVelocity(50'000); !r) { // VMAX in the chip's own units, signed
    return r.error;
  }
  if (auto r = motor.Stop(tmc5160::StopKind::Ramp); !r) { // decelerate with the programmed ramp
    return r.error;
  }
  return motor.Disable().error; // DRV_ENN inactive; the motor is not held
}

The constructor stores the port and the configuration and does no I/O. EnsureInitialized() is the one way to start the chip; it leaves the power stage off. Enable() switches it on, and refuses after a chip reset or a driver fault. Config{} is not valid: build one with MakeConfig() from the motor and the sense resistor (Configuration).

Once EnsureInitialized() has succeeded it returns Ok at once with no I/O. After a failure the driver stays uninitialised and the next call starts again. Before it succeeds every call returns NotInitialized and sends nothing.

Set the current

// The current is always checked against the declared motor and the sense resistor.
tmc5160::Error SetCurrents(Motor& motor) {
  const auto plan = motor.SetCurrent(800, 240); // run and hold, mA rms
  if (!plan) {
    return plan.error; // LimitExceeded: above the motor or the 5 % ceiling, or below one CS step
  }
  // `plan.value` holds GLOBALSCALER, IRUN, IHOLD and the realised currents.
  return tmc5160::Error::Ok;
}

Move

// Position mode: the ramp generator moves to XTARGET. Poll PositionReached().
tmc5160::Error GoTo(Motor& motor, int32_t target) {
  if (auto r = motor.MoveTo(target); !r) {
    return r.error;
  }
  for (int i = 0; i < 1000; ++i) { // bounded: the caller decides how long a move may take
    const auto done = motor.PositionReached();
    if (!done) {
      return done.error;
    }
    if (done.value) {
      return tmc5160::Error::Ok;
    }
  }
  return tmc5160::Error::Timeout;
}

Quiet running and stall detection

// StealthChop below a velocity, SpreadCycle above it.
tmc5160::Error QuietMotor(Motor& motor) {
  tmc5160::StealthChop stealth;
  stealth.enable = true;
  if (auto r = motor.SetStealthChop(stealth); !r) { // waits the automatic tuning time at standstill
    return r.error;
  }
  return motor.SetThresholds(tmc5160::Thresholds{.pwm = 500})
      .error; // TSTEP above 500 is StealthChop
}
// StallGuard2 with a stop on stall. The motor stays stopped until ReleaseStall().
tmc5160::Error SensorlessStop(Motor& motor) {
  if (auto r = motor.SetThresholds(tmc5160::Thresholds{.cool = 200'000}); !r) {
    return r.error;
  }
  if (auto r = motor.SetStallGuard(tmc5160::StallGuard{.threshold = 4, .filter = true}); !r) {
    return r.error;
  }
  if (auto r = motor.SetStopOnStall(true); !r) {
    return r.error;
  }
  const auto ramp = motor.ReadRampStatus();
  if (ramp && ramp.value.event_stop_stall) {
    return motor.ReleaseStall().error; // clear the event: the motor may move again
  }
  return ramp.error;
}

Watch the chip

// A periodic service call: one batch read, the events decoded and the latched ones cleared.
tmc5160::Error ServiceLoop(Motor& motor) {
  const auto events = motor.Service();
  if (!events) {
    return events.error; // UnexpectedReset: write-only registers are lost, Enable() refuses
  }
  if (events.value.driver.over_temp || events.value.driver.s2g_a || events.value.driver.s2g_b) {
    return tmc5160::Error::DeviceFault;
  }
  return tmc5160::Error::Ok;
}

Dangerous writes

// A guarded write: IHOLD above IRUN is refused unless the call acknowledges it.
tmc5160::Error HoldAboveRun(Motor& motor) {
  tmc5160::Config c = motor.GetConfig();
  c.current.hold_ma = c.current.run_ma + 100;
  const auto refused = motor.SetCurrent(c.current.run_ma, c.current.hold_ma);
  return refused.error; // Refused: no tmc5160::Ack::HoldAboveRun in the configuration
}

Handle errors

// What each error asks of the application.
const char* Advice(tmc5160::Error e) {
  switch (e) {
  case tmc5160::Error::Bus:
  case tmc5160::Error::Timeout:
  case tmc5160::Error::Crc:
    return "retry the read; a write is not retried: look at the wiring"; // reads are retried twice
  case tmc5160::Error::UnexpectedReset:
    return "the chip lost its registers: EnsureInitialized() again";
  case tmc5160::Error::DeviceFault:
    return "short or overtemperature: remove the cause, then ClearFaults()";
  case tmc5160::Error::Refused:
  case tmc5160::Error::LimitExceeded:
    return "the guard stopped an unsafe request: change the request";
  default:
    return "see the error table";
  }
}
Signal Meaning What to do
Error::Bus The port failed a transfer or the bus bring-up Check the port and the wiring
Error::Timeout No UART reply, or a bounded wait ran out Check the single wire, the node address and the baud rate
Error::Crc A UART reply was corrupted Check the wire and grounding; reads are retried twice, writes never
Error::UnexpectedReset The chip reset: write-only registers are lost EnsureInitialized() again
Error::DeviceFault Short or overtemperature Remove the cause, then ClearFaults()
Error::Refused A guard stopped the call Change the request, or acknowledge the risk in the configuration
Error::LimitExceeded Above the motor, the board or the ramp limit Change the request
Error::ModeMismatch The strap or the bus does not match Config::mode Fix the strap or the configuration
Error::VerifyFailed A write-back or interface-counter check failed Rewrite with EnsureInitialized(); check the wire

Every value, with the calls that return it, is on the Contract page. tmc5160::ToString() names an error for a log.

Stop

// Release the driver: the chip is quiesced and every later call returns NotInitialized.
tmc5160::Error Shutdown(Motor& motor) {
  return motor.Deinitialize().error;
}

After Deinitialize() the chip is quiesced and every call returns NotInitialized until the next EnsureInitialized().

Next: Configuration.