Skip to content

Guards and acknowledgements

Which writes the driver refuses, why, and the acknowledgement that lifts a guard for one configuration.

Datasheet sections this page relies on

From Analog Devices (Trinamic) TMC5160A-DS 1.18:

  • Sample circuits and gate drive: 3 Sample Circuits, p. 15
  • Selecting sense resistors and the current scale: 9 Selecting Sense Resistors, p. 74
  • Temperature sensors and short protection: 11 Diagnostics and Protection, p. 78
  • DC motor and direct mode: 21 DC Motor or Solenoid, p. 110
  • Absolute maximum ratings and operational range: 28.1 Operational Range, p. 120

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

A stepper driver has registers that can destroy the motor or the bridge. The driver never exposes them raw: the current comes from the declared motor and sense resistor (Current and limits), and every other dangerous value has a guard. A guarded call returns an error and writes nothing.

Acknowledgements

Config::ack is a set of Ack values. Each one lifts exactly one guard, and the configuration that carries it says in code that the application accepted the risk.

Ack Lifts Datasheet
HoldAboveRun IHOLD above IRUN section 6.2, page 38
ShortProtectionOff diss2g or diss2vs (short protection disabled) section 11.2, page 78
LowOtLevel The 120 degree shutdown level, or 136 degrees with a supply above 24 V section 6.1, page 36
HardStopWithStealthChop A hard stop while StealthChop is enabled section 6.3, page 43
VstartAboveVstop VSTART above VSTOP section 6.3, page 41
DirectMode Direct mode (coil currents from XTARGET) section 21, page 110
VoltageModeNoCurrentLimit Direct mode with a voltage-mode chopper, which has no current limit section 21, page 110
// 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
}

The guards

Guard Rule Result
Current ceiling Run and hold current, rounded down, at most the smaller of max_rms_ma and rated_rms_ma, reduced by the 5 percent tolerance LimitExceeded
Sense resistor bound The sense resistor must allow the request (VFS / Rsense / sqrt(2)) LimitExceeded
No raw current registers GLOBALSCALER, IHOLD and IRUN are set only from a current plan; GLOBALSCALER 129 to 256 by type
Hold current Hold at most run Refused
Supply supply_mv 10 000 to 55 000 InvalidArgument
Bridge Written only when declared; break-before-make at least 130 percent of the declared MOSFET switching time; bbm_time at most 24; only with the driver off LimitExceeded
Short levels s2vs_level 4 to 15, s2g_level 2 to 15, and 12 to 15 when the highest supply is above 52 V Refused
Short protection off diss2g, diss2vs Refused
Overtemperature 136 C above 24 V and 120 C Refused
Chopper toff 1 to 15 (0 only through Disable()); toff 1 needs tbl 2 or more; effective hysteresis sum at most 16 InvalidArgument
Thresholds TPWMTHRS at least TCOOLTHRS at least THIGH where non-zero; CoolStep and stop on stall need TCOOLTHRS InvalidArgument
StealthChop With autoscale: IRUN at least 8, TPOWERDOWN at least 2, the run current above the lower limit when the coil resistance is known; only at standstill (the check of Enable()) Refused, Busy
StealthChop and stop A hard stop with StealthChop enabled Refused
Soft stop and stall soft_stop together with stop_on_stall Refused
DcStep Needs the default table, high_fullstep and high_const_off, TOFF 3 or more, VDCMIN 0 or 256 or more InvalidArgument
Ramp VMAX within the register limit and max_velocity_reg; D1 and VSTOP at least 1; VSTOP at least VSTART LimitExceeded, InvalidArgument
Motion MoveTo() and MoveBy() need the nine ramp registers written and a VMAX that is not 0 (after SetMaxVelocity(0), until SetMaxVelocity() or SetRamp() gives a speed again); SetMaxVelocity() refuses 0 < VMAX < VSTART (the chip's or the profile's) Refused, InvalidArgument
Home position SetHomePosition() needs standstill: vzero, no TZEROWAIT pause and, in position mode with VMAX not 0, the target reached (Stop() or Hold() ends a move a switch or stall holds) Busy
Stall release ReleaseStall() holds, verifies standstill, then clears the event; the motor never restarts by itself. Switching the stop off while its event is latched first ends the ramp at the present position Busy
Microstep table Only when MSCNT is 0; the decoded wave inside the allowed range; segments in order Refused
Direct mode Ack::DirectMode; entry refused while moving; currents within the range of the chopper mode Refused
DIAG Bits that belong to the other mode are refused; steps_skipped is exclusive InvalidArgument
UART addressing send_delay at least 2 with several nodes; node 0 to 253 (254 with multi_node); ProgramNode() over SPI Refused, Unsupported
Clock External clock 4 to 18 MHz; the SPI clock when the port reports it InvalidArgument
Encoder Encoder calls in STEP/DIR mode Unsupported

Registers the driver never writes

OTP_PROG and FACTORY_CONF are never written (the owner excluded OTP programming; a test sends every call and checks the register was not touched). GCONF.test_mode is never set. Read-only registers are never written, and reserved bits are written as 0.

After a reset

Reading a write-only register returns Refused: the chip's answer is undefined (A4). The driver keeps a write-through shadow of those registers and never reads them back. A chip reset (undervoltage, power-up) clears them all: UnexpectedReset is returned, the driver becomes uninitialised, and Enable() refuses until EnsureInitialized() has rewritten everything.