API guide¶
The calls of the driver, task by task. Every call returns Result<T>: check ok() before you use value.
Datasheet sections this page relies on
From Analog Devices (Trinamic) 19-101926 1:
- Bootloader commands and reply status codes: Bootloader, Commands, p. 76
All of them, with the driver API for each: Datasheet map.
Start¶
tmc9660::Error BringUp(Chip& chip) {
// The one entry point: starts on the first call, then returns Ok with no I/O. After a failure the
// next call starts again from the beginning.
const auto r = chip.EnsureInitialized();
if (!r) {
std::printf("TMC9660 init: %s\n", tmc9660::ToString(r.error));
}
return r.error;
}
EnsureInitialized() is the only call that starts the driver; it returns Ok with no I/O once it has succeeded. It
checks the identity of the chip in the mode named by Config::mode. The chip is not reset unless you set
Config::hardware_reset. After a failure the next call starts again.
Start the application from the bootloader¶
tmc9660::Error StartApplication(Chip& chip) {
// The chip comes up in its bootloader. Read the configuration, change one field, write it back:
// only the words that differ are written, the boot-mode word last, and the driver refuses a start
// that would hang the chip.
auto cfg = chip.BlReadConfig();
if (!cfg) {
return cfg.error;
}
tmc9660::BootConfig next = cfg.value;
if (const auto e = next.Set(tmc9660::BootField::BootMode, 2U); e != tmc9660::Error::Ok) {
return e; // 2 is parameter mode
}
if (const auto e = next.Set(tmc9660::BootField::StartMotorCtrl, 1U); e != tmc9660::Error::Ok) {
return e;
}
return chip.BlWriteConfig(next).error; // follows the chip into parameter mode
}
A freshly powered chip is in its bootloader (Mode::Bootloader). BlWriteConfig() writes only the words that differ,
the boot-mode word last, verifies by reading back, and follows the chip into the new mode. It refuses a start that
would use a reserved boot mode or a clock other than 40 MHz, and a change of the LDO outputs unless you allow it.
BlStartApplication(BootMode::Parameter) does the same in one call. More in Bootloader.
Set and read parameters¶
tmc9660::Error SetLimits(Chip& chip) {
// Every parameter is checked against the datasheet's range and coded set before a byte is sent.
if (auto r = chip.SetParam(tmc9660::Param::MOTOR_TYPE, 3); !r) { // 3: BLDC; needs the system off
return r.error;
}
if (auto r = chip.SetParam(tmc9660::Param::MAX_TORQUE, 1500); !r) {
return r.error; // InvalidArgument above 65535: nothing was sent
}
return chip.StoreParams().error;
}
SetParam() and GetParam() check the parameter against Table 57 first: access, range, coded values and the motor
number. StoreParams() saves the settings in the chip's external memory. More in Parameter mode.
Drive the motor¶
tmc9660::Error RunMotor(Chip& chip) {
// The only way to a non-zero commutation mode. The guards read the flag words first; DRV_EN rises
// only after they are clean, then the mode is set.
if (auto r = chip.EnableDrive(3); !r) {
return r.error; // DeviceFault: an error flag is latched; Refused is never returned here
}
const auto r = chip.SetTargetVelocity(500);
if (!r) {
static_cast<void>(
chip.DisableDrive()); // never refused: DRV_EN first, then the commutation mode
return r.error;
}
return tmc9660::Error::Ok;
}
EnableDrive(mode) is the only way to a non-zero commutation mode: it reads the error flags (DeviceFault if one is
set), raises DRV_EN and only then writes the mode. DisableDrive() drops DRV_EN, then writes mode 0, and is never
refused; Deinitialize() does the same stop before it forgets the chip. See Safety.
Register mode¶
tmc9660::Error StartGateDriver(Chip& chip) {
// Register mode: the gate driver starts only through GateDriverStart(), which runs the manual's
// sequence with the fault and undervoltage guards before the energising write. WriteReg() refuses
// those bits.
tmc9660::GateDriverRegConfig cfg{};
cfg.gdrv_cfg = 0x0003'0000U; // gate currents and adaptive mode: see the register reference
return chip.GateDriverStart(cfg).error;
}
ReadReg(), WriteReg() and UpdateReg() work on the 163 registers; ReadField() and WriteField() take a
fields::<register>::<Field> type. GateDriverStart() runs the manual's start sequence with the fault guards before
the energising write, and the energising bits are refused anywhere else. See Register mode.
Notice a reset¶
tmc9660::Error KeepAlive(Chip& chip) {
const auto r = chip.Service(); // FAULTN and a heartbeat read: the way to notice a reset
if (r.error == tmc9660::Error::UnexpectedReset) {
static_cast<void>(chip.DisableDrive()); // the pin first
return chip.EnsureInitialized().error; // the chip lost its configuration: start it again
}
return r.error;
}
A reset of the chip loses its configuration and, in parameter mode, the drive settings. The driver watches each
transport for evidence (the status byte on SPI, the canary variable on UART, the boot bit and counter in register mode)
and returns UnexpectedReset instead of sending a write that might act on a chip it no longer knows. Call Service()
from your main loop: it reads FAULTN when the port has GpioGet() and Config::faultn_is_reset is set, and polls one
status parameter in parameter mode.
Handle errors¶
const char* Describe(tmc9660::Error e) {
switch (e) {
case tmc9660::Error::Bus:
case tmc9660::Error::DeviceIdMismatch:
return "check the bus wiring, the mode and the device address";
case tmc9660::Error::WrongMode:
return "the chip is in another mode: nothing was sent";
case tmc9660::Error::Refused:
return "a safety guard said no: read the documentation of the call";
case tmc9660::Error::UnexpectedReset:
return "the chip restarted: call EnsureInitialized() again";
default:
return tmc9660::ToString(e);
}
}
| Signal | Meaning | What to do |
|---|---|---|
Error::Bus |
The port failed a transfer or the bus bring-up | Check the port and the wiring; retry, or Deinitialize() and EnsureInitialized() |
Error::Timeout |
No reply, or the PLL did not lock | Check VCC_IO and RSTN; raise boot_timeout_ms or reply_timeout_us |
Error::DeviceIdMismatch |
The chip ID is wrong | Check the mode, the device address and the wiring |
Error::Crc, Error::BadReply |
A reply was corrupted on the bus | Lower the bus clock; check grounding; the value was discarded |
Error::Busy |
The bootloader stayed busy | Retry after a delay; raise spi_reply_retries |
Error::DeviceFault |
An error flag is latched | Read and clear the flags after fixing the cause |
Error::Nack |
The chip refused the command | LastStatus() has the chip's status code |
Error::WrongMode |
The call belongs to another mode | Nothing was sent; start the right mode |
Error::Refused |
A safety guard said no | Read the guard on Safety; nothing was changed |
Error::VerifyFailed |
A read back differed | The chip did not take the write; do not start the application |
Error::UnexpectedReset |
The chip restarted | EnsureInitialized(), then configure again |
Error::Unsupported |
An offset or hook this setup cannot reach | See A3 or add the GpioSet() hook |
Every value, with the calls that return it, is on the Contract page.
tmc9660::ToString() names an error for a log.
Diagnostics¶
| Call | I/O | What it gives |
|---|---|---|
IsInitialized() |
none | Whether the driver is started |
GetMode() |
none | The mode the driver speaks |
LastStatus() |
none | The status code of the last reply (TMCL status, bootloader status, register-mode flag) |
GetLastReply() |
none | Status, command number and value of the last valid parameter-mode reply |
ReadRawParam() |
one command | A GAP with a parameter number taken as given; the unsigned reply value; nothing is written |
GetConfig() |
none | The configuration in use |
GetChipId(), GetVersion() |
one command | The chip ID and version (parameter mode); BlGetInfo() in the bootloader |
Shut down¶
void PowerDown(Chip& chip) {
if (auto r = chip.Deinitialize(); !r) { // drops DRV_EN and sets the system off first
std::printf("TMC9660 shutdown write failed: %s\n", tmc9660::ToString(r.error));
}
}
After Deinitialize() every call returns NotInitialized until the next EnsureInitialized(). The drive is switched
off first, with DRV_EN dropped before the chip is told.
Next: Configuration.