Configuration¶
Config is the whole configuration of the driver; Config{} is the chip's reset configuration. Nothing in it is
written to the chip: it says how the driver talks and waits.
Datasheet sections this page relies on
From Analog Devices (Trinamic) 19-101926 1:
- Boot configuration list, LDO and bootstrap configuration: Bootloader, Configuration, p. 83
All of them, with the driver API for each: Datasheet map.
Fields¶
| Field | Default | Range | What it does |
|---|---|---|---|
mode |
Mode::Parameter |
Bootloader, Parameter, Register |
The protocol the chip is in at EnsureInitialized() |
device_address |
1 | 1 to 255, odd for TMCL and register mode on UART | The UART device address (the upper 7 bits are the TMCL address) |
host_address |
255 | 1 to 255 | Host address in bootloader UART replies |
tmcl_host_address |
2 | 1 to 255 | Host address in TMCL and register-mode UART replies |
reply_timeout_us |
50 000 | 1 or more | How long the UART port waits for a reply |
boot_timeout_ms |
500 | 1 or more | Bounds every identity wait after a reset, a start or Boot (A9). Each failed poll is charged the 10 ms pause and, on UART, the longest it can take: reply_timeout_us, uart_resync_us and three 5 ms drains (225 ms with the defaults), so a chip that never answers is given up after about boot_timeout_ms plus one poll: two or three polls on UART, 50 on SPI |
settle_us |
20 000 | Wait after a write that reconfigures the chip (A13) | |
spi_gap_us |
1 000 | Gap between a TMCL SPI command and its reply request | |
spi_reply_retries |
5 | 0 to 50 | Repeats of the reply request on NOT_READY or CHECKSUM_ERROR (A5) |
uart_canary |
true | Parameter mode over UART: detect an unseen reset (A7) | |
canary_variable |
15 | 0 to 15 | The user variable that holds the canary |
canary_value |
0x5AC3A55A |
The canary | |
hardware_reset |
false | needs GpioSet() |
Pulse RSTN at start instead of adopting the chip, then wait 50 ms (T_WAKE is 44 ms typical, A9) before the first identity poll; that wait is not charged to boot_timeout_ms |
faultn_is_reset |
false | needs GpioGet() |
Service() treats FAULTN low outside the bootloader as a reset (A18) |
allow_pwm_in_system_off |
false | Allow SetParam(IDLE_MOTOR_PWM_BEHAVIOR, 0) (the PWM stays active in System off). The stop of a port without a DRV_EN hook sets the parameter to 1 whatever this says |
|
uart_resync_us |
150 000 | The gap after a failed UART exchange before the line is drained: the chip's discard gap of about 100 ms (A6) with a 50 % margin; a stop is sent before it | |
quirks |
see below | Readings of ambiguous documentation |
tmc9660::Config UartConfig() {
tmc9660::Config c{}; // the defaults
c.mode = tmc9660::Mode::Parameter;
c.device_address = 3; // UART: odd, as set in the boot configuration
c.boot_timeout_ms = 750; // how long to wait for the chip after a reset
c.uart_canary = true; // detect an unseen reset through a user variable
return c; // tmc9660::Validate(c) checks it without the chip
}
tmc9660::Error StartOnUart(MyUartPort& port) {
static tmc9660::TMC9660<MyUartPort> chip(port, UartConfig()); // stored, no I/O
return chip.EnsureInitialized().error; // InvalidArgument if the config is out of range
}
Readings of ambiguous documents¶
Where the documents disagree the driver reads them one way by default; Quirks selects the other
(Ambiguities):
| Field | Default | Ambiguity |
|---|---|---|
crc8_reflect_output |
false | A1: the bootloader CRC-8 output reflection |
tmcl_layout |
Auto |
A2: the type bits of a TMCL frame; Auto probes with two reads, MotorHigh or TypeHigh is verified the same way |
reg_spi_wide_offset |
false | A3: 9-bit or 10-bit register offset on SPI |
reg_uart_msb_fields |
false | A4: field order of register UART datagrams |
ram_debug_index_bits |
5 | A17: 5 or 6 |
tmc9660::Config RegisterModeWithOtherReadings() {
tmc9660::Config c{};
c.mode = tmc9660::Mode::Register;
c.quirks.reg_spi_wide_offset =
true; // ambiguity A3: the other reading of the register datagram layout
c.quirks.ram_debug_index_bits = 6; // ambiguity A17: a 6-bit RAMDebug index
return c;
}
Validation¶
tmc9660::Validate(config) checks a configuration without touching the chip, and EnsureInitialized() calls it
before any I/O. It returns Error::InvalidArgument when mode is not an enumerator, an address, timeout or the
canary variable is out of range, or ram_debug_index_bits is not 5 or 6. EnsureInitialized() also rejects an even
device address on UART in parameter or register mode, and hardware_reset without a GpioSet() hook (Unsupported).
A configuration can be proven at build time, so that a wrong one does not compile:
// A configuration proven at build time: an invalid one does not compile.
constexpr tmc9660::CheckedConfig kBoardConfig{tmc9660::Config{.mode = tmc9660::Mode::Register}};
tmc9660::Mode BoardMode() {
return kBoardConfig.Get().mode;
}
Kconfig¶
Under ESP-IDF, idf.py menuconfig shows TMC9660 servo controller when the driver is a component of the project
(Installation); the menu is _config/Kconfig. The options reach the code only
through inc/tmc9660_kconfig.hpp, never through a driver signature:
tmc9660::Error StartFromMenuconfig(MyPort& port) {
static tmc9660::TMC9660<MyPort> chip(port, tmc9660::KconfigDefaults());
return chip.EnsureInitialized().error;
}
| Option | Default | Config field |
|---|---|---|
CONFIG_TMC9660_MODE_* |
Parameter mode | mode |
CONFIG_TMC9660_DEVICE_ADDRESS |
1 | device_address |
CONFIG_TMC9660_BOOT_TIMEOUT_MS |
500 | boot_timeout_ms |
CONFIG_TMC9660_HARDWARE_RESET |
n | hardware_reset |
CONFIG_TMC9660_NO_UART_CANARY |
n | uart_canary (inverted) |
Without Kconfig (plain CMake, other platforms) KconfigDefaults() returns Config{}. Both cases are host tests.
Next: Porting.