Skip to content

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.