Skip to content

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::InvalidArgument as well;
  • SetParam(Param::COMMUTATION_MODE, nonzero) is Error::Refused: only EnableDrive() leaves the system on;
  • SetParam(Param::MOTOR_TYPE, ...) is Error::Refused while COMMUTATION_MODE is 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).