Parameter mode¶
In parameter mode the chip's processor runs TMCL, Trinamic's command language, and adds software features on top of
the hardware: ramps, fault handling, brake chopper, step/direction, scripts. The driver exposes it as
Mode::Parameter: SetParam(), GetParam() and friends.
Datasheet sections this page relies on
- Application modes: Analog Devices (Trinamic) 19-101926 1, Application Modes, p. 16
- TMCL frames over UART and SPI: Analog Devices (Trinamic) n/a 0, Communication Interfaces, p. 8
- Parameter table: Analog Devices (Trinamic) n/a 0, Table 57, Full list of parameters, p. 102
All of them, with the driver API for each: Datasheet map.
Frames¶
| Bus | Frame | Driver |
|---|---|---|
| UART | 9 bytes, LSB first: address, command, type, motor, value (4 bytes), checksum | One Exchange() per command |
| SPI | 8 bytes: command, type, motor, value (4 bytes), checksum; the reply comes in the next transfer | Two Transfer() calls: the command, then a reply request (FF 00 00 00 00 00 00 FF) |
On SPI the reply request is repeated up to Config::spi_reply_retries times while the status says NOT_READY or
CHECKSUM_ERROR (ambiguity A5); the command is never sent twice. The first frame after a reset carries 0x0C
(FIRST_CMD) in the status byte. The driver looks for it on every frame: a command frame, its reply request and the
reply of a write probe. When it sees it, the chip restarted since the last validated reply, and the call returns
Error::UnexpectedReset without a write following it.
The placement of the type bits in the UART frame is ambiguity A2 (Quirks::tmcl_layout). By default (Auto) the
driver reads two flag parameters under each layout at start-up and uses the one the chip answers; if both or neither
answer it refuses to start (Refused) and no write has been sent.
Parameters¶
inc/tmc9660_params.hpp has the 289 parameters of Table 57 of the Parameter Mode Reference Manual, generated by
tools/gen_tables/gen_tables.py (see Testing). Each row carries the
number, name, access (read, write, read/write, write-to-clear), range, reset value, and for coded parameters the
allowed values. GetParam() and SetParam() check against that row before any byte is sent:
- a value outside the range, a coded value that is not allowed, or a motor number above 15 is
Error::InvalidArgument, nothing sent; - writing a read-only parameter or reading a write-only one is
Error::InvalidArgumentas well; SetParam(Param::COMMUTATION_MODE, nonzero)isError::Refused: onlyEnableDrive()leaves the system on;SetParam(Param::MOTOR_TYPE, ...)isError::RefusedwhileCOMMUTATION_MODEis not zero.
ClearFlags() writes a mask to a write-to-clear flag parameter. StoreParams() and FactoryDefault(confirm) run
the matching TMCL commands; the second needs confirm true and the system off. Global parameters (GetGlobal(),
SetGlobal()) are checked against inc/tmc9660_globals.hpp, for example the serial address must be odd.
The other TMCL commands¶
| Area | Calls |
|---|---|
| Motion | EnableDrive(), DisableDrive(), MotorStop(), ReferenceSearchCommand() |
| GPIO | SetIo(), GetIo() |
| Debug | RamDebug() |
| Scripts | ScriptDownload(), ScriptRun(), ScriptStop(), ScriptStep(), ScriptReset(), ScriptStatus(), ScriptReadMem() |
| System | PowerDown(), ReturnToBootloader(), DisableSpi1Slave(), GetChipId(), GetVersion() |
A script runs on the chip with its own authority over the motor. The driver downloads and starts scripts but does not analyse them; see Safety and the coverage table in Datasheet map.
Detecting a reset on UART¶
SPI parameter mode shows a reset in the status byte. UART replies have no such flag, so the driver writes a canary
value (Config::canary_value) to a user variable (Config::canary_variable, 15) when it starts and reads it before
every write. A different value means the chip restarted, and the write is not sent (ambiguity A7). The check adds
one read per write; Config::uart_canary = false turns it off for a link where it is too slow, at the cost of an
unseen reset going unnoticed. FAULTN, through Service(), is the second way (A18).