API guide¶
The driver's API by task, with code that compiles: start, set the current, move, tune, watch, handle errors and stop.
The shape of the API¶
| Group | Calls | Page |
|---|---|---|
| Lifecycle | EnsureInitialized(), IsInitialized(), Enable(), Disable(), Deinitialize() |
below |
| Current | SetCurrent() and the declared motor |
Current and limits |
| Motion | MoveTo(), MoveBy(), RunVelocity(), Stop(), SetRamp(), PositionReached() |
Motion |
| Chopper | SetChopper(), SetStealthChop(), SetThresholds() |
Chopper |
| Load | SetStallGuard(), SetStopOnStall(), ReleaseStall(), CoolStep |
StallGuard and CoolStep |
| Status | Service(), ReadRampStatus(), ClearFaults() |
Diagnostics and status |
| Guards | Ack, Verify |
Guards |
Every call that touches the chip returns Result<T>: check ok() (or the bool conversion) and read value, or
read error. Result is [[nodiscard]], so an unchecked call is a compiler warning.
Start, enable, stop¶
// Start, enable, stop. Every call returns a Result: check it.
tmc5160::Error RunAndStop(Motor& motor) {
if (auto r = motor.EnsureInitialized(); !r) { // writes every register; the driver stays off
return r.error;
}
if (auto r = motor.Enable(); !r) { // refuses after a chip reset or a driver fault
return r.error;
}
if (auto r = motor.RunVelocity(50'000); !r) { // VMAX in the chip's own units, signed
return r.error;
}
if (auto r = motor.Stop(tmc5160::StopKind::Ramp); !r) { // decelerate with the programmed ramp
return r.error;
}
return motor.Disable().error; // DRV_ENN inactive; the motor is not held
}
The constructor stores the port and the configuration and does no I/O. EnsureInitialized() is the one way to start
the chip; it leaves the power stage off. Enable() switches it on, and refuses after a chip reset or a driver fault.
Config{} is not valid: build one with MakeConfig() from the motor and the sense resistor (Configuration).
Once EnsureInitialized() has succeeded it returns Ok at once with no I/O. After a failure the driver stays
uninitialised and the next call starts again. Before it succeeds every call returns NotInitialized and sends nothing.
Set the current¶
// The current is always checked against the declared motor and the sense resistor.
tmc5160::Error SetCurrents(Motor& motor) {
const auto plan = motor.SetCurrent(800, 240); // run and hold, mA rms
if (!plan) {
return plan.error; // LimitExceeded: above the motor or the 5 % ceiling, or below one CS step
}
// `plan.value` holds GLOBALSCALER, IRUN, IHOLD and the realised currents.
return tmc5160::Error::Ok;
}
Move¶
// Position mode: the ramp generator moves to XTARGET. Poll PositionReached().
tmc5160::Error GoTo(Motor& motor, int32_t target) {
if (auto r = motor.MoveTo(target); !r) {
return r.error;
}
for (int i = 0; i < 1000; ++i) { // bounded: the caller decides how long a move may take
const auto done = motor.PositionReached();
if (!done) {
return done.error;
}
if (done.value) {
return tmc5160::Error::Ok;
}
}
return tmc5160::Error::Timeout;
}
Quiet running and stall detection¶
// StealthChop below a velocity, SpreadCycle above it.
tmc5160::Error QuietMotor(Motor& motor) {
tmc5160::StealthChop stealth;
stealth.enable = true;
if (auto r = motor.SetStealthChop(stealth); !r) { // waits the automatic tuning time at standstill
return r.error;
}
return motor.SetThresholds(tmc5160::Thresholds{.pwm = 500})
.error; // TSTEP above 500 is StealthChop
}
// StallGuard2 with a stop on stall. The motor stays stopped until ReleaseStall().
tmc5160::Error SensorlessStop(Motor& motor) {
if (auto r = motor.SetThresholds(tmc5160::Thresholds{.cool = 200'000}); !r) {
return r.error;
}
if (auto r = motor.SetStallGuard(tmc5160::StallGuard{.threshold = 4, .filter = true}); !r) {
return r.error;
}
if (auto r = motor.SetStopOnStall(true); !r) {
return r.error;
}
const auto ramp = motor.ReadRampStatus();
if (ramp && ramp.value.event_stop_stall) {
return motor.ReleaseStall().error; // clear the event: the motor may move again
}
return ramp.error;
}
Watch the chip¶
// A periodic service call: one batch read, the events decoded and the latched ones cleared.
tmc5160::Error ServiceLoop(Motor& motor) {
const auto events = motor.Service();
if (!events) {
return events.error; // UnexpectedReset: write-only registers are lost, Enable() refuses
}
if (events.value.driver.over_temp || events.value.driver.s2g_a || events.value.driver.s2g_b) {
return tmc5160::Error::DeviceFault;
}
return tmc5160::Error::Ok;
}
Dangerous writes¶
// A guarded write: IHOLD above IRUN is refused unless the call acknowledges it.
tmc5160::Error HoldAboveRun(Motor& motor) {
tmc5160::Config c = motor.GetConfig();
c.current.hold_ma = c.current.run_ma + 100;
const auto refused = motor.SetCurrent(c.current.run_ma, c.current.hold_ma);
return refused.error; // Refused: no tmc5160::Ack::HoldAboveRun in the configuration
}
Handle errors¶
// What each error asks of the application.
const char* Advice(tmc5160::Error e) {
switch (e) {
case tmc5160::Error::Bus:
case tmc5160::Error::Timeout:
case tmc5160::Error::Crc:
return "retry the read; a write is not retried: look at the wiring"; // reads are retried twice
case tmc5160::Error::UnexpectedReset:
return "the chip lost its registers: EnsureInitialized() again";
case tmc5160::Error::DeviceFault:
return "short or overtemperature: remove the cause, then ClearFaults()";
case tmc5160::Error::Refused:
case tmc5160::Error::LimitExceeded:
return "the guard stopped an unsafe request: change the request";
default:
return "see the error table";
}
}
| Signal | Meaning | What to do |
|---|---|---|
Error::Bus |
The port failed a transfer or the bus bring-up | Check the port and the wiring |
Error::Timeout |
No UART reply, or a bounded wait ran out | Check the single wire, the node address and the baud rate |
Error::Crc |
A UART reply was corrupted | Check the wire and grounding; reads are retried twice, writes never |
Error::UnexpectedReset |
The chip reset: write-only registers are lost | EnsureInitialized() again |
Error::DeviceFault |
Short or overtemperature | Remove the cause, then ClearFaults() |
Error::Refused |
A guard stopped the call | Change the request, or acknowledge the risk in the configuration |
Error::LimitExceeded |
Above the motor, the board or the ramp limit | Change the request |
Error::ModeMismatch |
The strap or the bus does not match Config::mode |
Fix the strap or the configuration |
Error::VerifyFailed |
A write-back or interface-counter check failed | Rewrite with EnsureInitialized(); check the wire |
Every value, with the calls that return it, is on the Contract page. tmc5160::ToString()
names an error for a log.
Stop¶
// Release the driver: the chip is quiesced and every later call returns NotInitialized.
tmc5160::Error Shutdown(Motor& motor) {
return motor.Deinitialize().error;
}
After Deinitialize() the chip is quiesced and every call returns NotInitialized until the next
EnsureInitialized().
Next: Configuration.