Ambiguities and unverified items¶
The three TMC9660 documents (datasheet, Parameter Mode Reference Manual, Register Mode Reference Manual) disagree with
each other in places, or leave a detail open. For each, the driver reads the documents one way by default and a knob
in Config or Quirks selects the other reading, so a bench check can settle it without a code change. The frame
encoders are proved against the documents' worked examples with static_assert.
| Id | The documents | Default reading | Knob |
|---|---|---|---|
| A1 | Bootloader CRC-8: the prose reflects the output, the worked examples (0x1D, 0xA3) do not |
Not reflected | Quirks::crc8_reflect_output |
| A2 | TMCL: where the type bits [11:8] sit in the byte shared with the motor number: the manual's bit table puts the motor number in the high nibble, a vendor example the other way |
Auto: probed at start, refuses if both or neither layout answers (fail closed) |
Quirks::tmcl_layout (Auto, MotorHigh, TypeHigh) |
| A3 | Register SPI: a 9-bit offset in the table, registers up to 0x208, and a RAMDebug example with 10 bits |
Table layout; offsets above 0x1FF return Unsupported |
Quirks::reg_spi_wide_offset |
| A4 | Register UART: order of the fields in a datagram | Table order, block in the top 5 bits of byte 3 | Quirks::reg_uart_msb_fields |
| A5 | TMCL SPI: what to do on NOT_READY or CHECKSUM_ERROR |
Repeat only the reply request, up to the retry count | Config::spi_reply_retries |
| A6 | TMCL UART: the gap that discards a partial message, 100 ms or 10 ms | 100 ms assumed; the resync waits uart_resync_us (150 ms, a 50 % margin) before it drains; a port must not pause more than 10 ms inside a frame |
Config::reply_timeout_us (and your port) |
| A7 | Parameter mode has no reset flag in a UART reply | A canary variable written at start and read before each write (UART); Service() also reads GENERAL_ERROR_FLAGS and treats a WATCHDOG_EVENT that was not set at the start as a restart (a watchdog reset only; a power-on reset sets no flag the driver knows of, and the driver never clears the word) |
Config::uart_canary, canary_variable, canary_value |
| A8 | Parameter 165: range 1 to 8, reset value 0 | The reset value is accepted, the range is enforced for other writes | the model accepts 0 |
| A9 | T_WAKE is given as a typical value only |
boot_timeout_ms is 500 and bounds the identity wait (after a pin reset the driver first waits 50 ms): each failed poll is charged its pause and, on UART, its reply wait and resync (see Configuration) |
Config::boot_timeout_ms |
| A10 | ABN2_B offset printed as 32, probably 34 | 34 | raw BootConfig::SetWord() |
| A11 | The version string has no usual checksum | GetInfo is used for the identity |
none |
| A12 | BL_UART_RX text mentions the "TX pin" |
Read as RX | none |
| A13 | The Boot reply is sent before the new configuration applies |
The reply is read, then the driver waits | Config::settle_us |
| A14 | Errata 2 and 6 need explicit values; erratum 5 may cut the host link | Never applied automatically; DisableSpi1Slave() is an explicit call |
none |
| A15 | Which flags forbid starting | Any non-zero GENERAL_ERROR_FLAGS or GDRV_ERROR_FLAGS; a warning bit therefore also stops EnableDrive() (stricter than needed) |
none: clear the flags first |
| A16 | SPI encoder chip-select polarity printed as bit 19 of a 16-bit word | Not exposed as a typed field | raw BootConfig::SetWord() |
| A17 | RAMDebug index width: 5 bits (bit ranges) or 6 (offset example 640) | 5 | Quirks::ram_debug_index_bits |
| A18 | FAULTN low in an application: a reset or a fault | Not a reset. With faultn_is_reset set, a gate-driver fault that pulls FAULTN low makes every register-UART write, including the write that clears the fault, return UnexpectedReset and uninitialise the driver; the stop is never gated by it |
Config::faultn_is_reset |
| A20 | Register mode: the reset value of GDRV_HW is printed as 0x03300FFF in the manual's text and 0x03000FFF in its register table |
The table (0x03000FFF); the driver never relies on the reset value |
none |
| A21 | TMCL SPI reply: the reply layout is given as a table and as prose that differ in the position of the status byte | The table: status, module, command, value | none (TmclSpiRequest is the same either way) |
| A22 | GetInfo type 0 (ID): the format of the value is not given |
Compared with the chip ID 0x544D0001 |
none |
| A23 | Bootloader SPI Table 3: the literal byte layout | Request command, value[4], reply status, value[4], as the worked examples |
none |
| A24 | Bootloader: whether writing the boot-mode word starts the application on a 0-to-1 change of START_MOTOR_CTRL or on any write with the bit set (the datasheet, "Launching Applications", p. 76, says only that the manually triggered sequence "is run when the boot configuration register is written to"), and whether the bootloader shows the bit set after Boot from an auto-started application (datasheet Figures 32, 34, 35) |
Any write of the word with the bit set is treated as a start: the driver follows it and falls back to the bootloader when that still answers | none |
| A19 | UART reply time: neither manual bounds the time from the last request byte to the first reply byte | 1 ms assumed | kTurnaroundUs (a port reads it; the driver itself waits on the port) |
Not verified¶
These are open because the documents do not settle them and no real chip has been available:
- The format of
GetInfotype 0 in parameter mode (the driver compares it with the chip ID;Confighas no knob). - The SPI parameter-mode frame laid out literally as in PM Table 3 (type in bits 8 to 19 and motor in bits 20 to 23 of
the 32-bit word, MSB first, so type[11:4] in byte 1) is not supported (A2): a read-only probe decodes type 299 as
0x2B0, the chip answers an error to both probes, and the start is refused with nothing written. Supporting it needs
a code change (a third
TmclLayout); it is a bench item. UART is not affected. - The nibble order (A2) is probed at start-up and refused when it does not decide; which of the two layouts the chip uses, whether it ignores the motor nibble, and the register offset width and UART field order (A3, A4) are bench items, and so is what a parameter-mode stop does when it reaches a register-mode chip over SPI (the frame lands on block 1 offset 9 and block 63 offset 0x100 in the table layout, on MCC 0x104, 0x109 and 0x22b or RAMDebug 0x300 in the wide one).
- Whether
GDRV_STATUS_EN= 0 stops the status from latching, which status bits latch at power-up, and how long the bootstrap capacitors need before the protection words are written are bench items (settle_usis used). - The UART reply time (A19) is an assumption.
- Register-mode UART and bootloader UART have no reset evidence in their replies; only FAULTN can show an unseen
reset, and only when your port has
GpioGet(). WATCHDOG_EVENTis a read-write-clear flag the driver does not clear: a chip adopted with it already set cannot show a new watchdog reset through that flag (UART still has the canary, SPI theFIRST_CMDstatus).- Whether
IDLE_MOTOR_PWM_BEHAVIOR0 on a real stage keeps the outputs driven afterCOMMUTATION_MODE0 as the manual says is a bench item; the driver treats it as written. - Whether scripts on the chip can energise the stage: the driver refuses only
SAPandAAPofCOMMUTATION_MODEin a downloaded script (Refused); it does not analyse anything else, andScriptRun()starts whatever the chip already holds. - The meaning of every bit of the warning subset of the flag parameters.
- The parameter-mode
GetStatustype value (0 assumed). - The numbering of the SIO and GIO pins for
SetIo()andGetIo(). - The
Verifytrailing arguments that other drivers of the family have are not implemented here: writes are checked by the chip's reply and, for the configuration, by reading back. - One corrupted status byte on SPI can hide
FIRST_CMD(see Safety). readParamRawignores itsguardedargument for reads; reads never energise anything.- The ESP32 example is compiled against a stub of ESP-IDF only; a build with the real SDK is pending.
- The MISRA C++:2023 scan (CodeQL) runs in CI, not in this host build.
When you settle one on a bench, report it: the change is a default and a changelog line.