Skip to content

Configuration

Every field of tmc5160::Config, how a configuration is built and checked, and the optional Kconfig layer.

Datasheet sections this page relies on

From Analog Devices (Trinamic) TMC5160A-DS 1.18:

  • Register map and reset values: 6 Register Mapping, p. 31
  • General configuration registers: 6.1 General Configuration Registers, p. 32
  • Quick configuration guide: 22 Quick Configuration Guide, p. 111
  • Clock oscillator and input: 26 Clock Oscillator and Input, p. 119

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

Start from the motor

Config{} holds the chip's reset values, but it is not a usable configuration: it declares no motor and no sense resistor, and the driver derives every current register from those two. Validate(Config{}) returns InvalidArgument. Build a configuration with MakeConfig(motor, board), which sets the run current to 85 percent of the motor's ceiling and the hold current to 30 percent of that, then change fields:

tmc5160::Config StealthConfig() {
  tmc5160::Config c =
      tmc5160::MakeConfig(tmc5160::Motor{.rated_rms_ma = 1500, .coil_resistance_mohm = 2000},
                          tmc5160::Board{.rsense_mohm = 75, .supply_mv = 24'000});
  c.current.run_ma = 1000; // the run current in mA rms: never above the declared motor
  c.current.hold_ma = 300; // the hold current
  c.chopper.mres = tmc5160::Microsteps::M16; // 16 microsteps per full step
  c.stealth.enable = true;
  return c; // tmc5160::Validate(c) checks it without the chip
}

tmc5160::Error StartStealth(MyPort& port) {
  static tmc5160::TMC5160<MyPort> motor(port, StealthConfig()); // stored, no I/O
  return motor.EnsureInitialized()
      .error; // InvalidArgument if a value is out of range or above the motor
}

Fields

Field Default Meaning Registers
mode MotionController MotionController or StepDir; must match the SD_MODE strap GCONF, IOIN
clock internal 12 MHz external and hz (4 to 18 MHz) all time and velocity values
motor none rated_rms_ma, max_rms_ma, coil_resistance_mohm, fullsteps_per_rev the current ceiling
board none rsense_mohm, supply_mv (10 000 to 55 000), supply_max_mv GLOBALSCALER, guards
max_velocity_reg 0 Optional ceiling for VMAX VMAX
include_tolerance true Reduce the ceiling by the 5 percent full-scale tolerance current plan
current from MakeConfig() run_ma, hold_ma GLOBALSCALER, IHOLD_IRUN
standstill datasheet hold_delay, power_down_delay, fast_standstill IHOLD_IRUN, TPOWERDOWN, GCONF
chopper SpreadCycle, TOFF 3 mode, TOFF, TBL, hysteresis, mres, high-velocity options CHOPCONF
stealth off enable, autoscale, autograd, frequency, regulation, limits, offsets, freewheel PWMCONF, GCONF
thresholds 0 pwm, cool, high, small_hysteresis TPWMTHRS, TCOOLTHRS, THIGH
cool, stall, dcstep off CoolStep, StallGuard2, DcStep COOLCONF, DCCTRL, VDCMIN
bridge, protection not declared Gate-driver and short-protection values, written only when declared DRV_CONF, SHORT_CONF
flags, diag off General flags; DIAG outputs GCONF
ramp datasheet quick start The six-point ramp VSTART to TZEROWAIT
switches off Reference switches and stop behaviour SW_MODE
encoder not declared ENCMODE, ENC_CONST, deviation ENCMODE and following
custom_table, table default table A custom microstep table MSLUT, MSLUTSEL, MSLUTSTART
uart node 0, 115200 baud node, send_delay, multi_node, baud NODECONF
spi chain of 1 chain_length, chain_index transfer length
verify None The check EnsureInitialized() applies to its writes
ack none Acknowledgements that lift guards (Guards)
begin_enabled false Leave the driver enabled after EnsureInitialized(); a motor that is still turning (or in its TZEROWAIT pause) makes the start-up fail with Busy, bridge off CHOPCONF.TOFF

TOFF defaults to 3 where the chip's reset value is 0 (off): the chip's CHOPCONF reset word is 0x10410150, but the driver writes TOFF only in Enable(), so a configured chopper never runs before you ask for it.

Validation

Validate(config) checks a configuration without touching the chip, and EnsureInitialized() calls it before any I/O. It returns InvalidArgument when a field is out of range, the motor or the sense resistor is missing, a current is above the motor's ceiling, or a combination breaks a guard. CheckedConfig runs it at build time: constexpr CheckedConfig kBoard{MakeConfig(...)} does not compile when the configuration is invalid.

Kconfig

Under ESP-IDF, idf.py menuconfig shows TMC5160 stepper driver when the driver is a component of the project (Installation); the menu is _config/Kconfig. The options reach the code only through inc/tmc5160_kconfig.hpp, never through a driver signature:

tmc5160::Error StartFromMenuconfig(MyPort& port) {
  static tmc5160::TMC5160<MyPort> motor(port, tmc5160::KconfigDefaults());
  return motor.EnsureInitialized().error;
}
Option Default Config field
CONFIG_TMC5160_MOTOR_RATED_MA 1000 motor.rated_rms_ma
CONFIG_TMC5160_MOTOR_MAX_MA 0 motor.max_rms_ma
CONFIG_TMC5160_RSENSE_MOHM 100 board.rsense_mohm
CONFIG_TMC5160_SUPPLY_MV 24000 board.supply_mv
CONFIG_TMC5160_RUN_MA, CONFIG_TMC5160_HOLD_MA 0 (from MakeConfig()) current
CONFIG_TMC5160_MRES 0 (256 microsteps) chopper.mres
CONFIG_TMC5160_STEALTHCHOP n stealth.enable
CONFIG_TMC5160_UART_BAUD, CONFIG_TMC5160_UART_NODE 115200, 0 uart
CONFIG_TMC5160_SPI_CHAIN_LENGTH, CONFIG_TMC5160_SPI_CHAIN_INDEX 1, 0 spi
CONFIG_TMC5160_VERIFY_STARTUP n verify

Without Kconfig (plain CMake, other platforms) KconfigDefaults() returns Config{}, which Validate() rejects: declare the motor yourself. Both cases are host tests.

Next: Porting.