TMC5160 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions
Driver types

Errors, results, configuration and presets. More...

Classes

struct  tmc5160::Result< T >
 The value of a call, or why there is none. More...
 
struct  tmc5160::Result< void >
 The result of a call that returns no value. More...
 
struct  tmc5160::AckSet
 A set of acknowledgements. More...
 
struct  tmc5160::Motor
 The motor as its data sheet declares it; the current ceiling comes from here. More...
 
struct  tmc5160::Board
 The power stage as built: the sense resistor and the supply. More...
 
struct  tmc5160::Clock
 The clock: internal 12 MHz or an external clock on CLK (page 119). More...
 
struct  tmc5160::Current
 Run and hold current requests, RMS in mA; PlanCurrent() turns them into registers. More...
 
struct  tmc5160::Standstill
 Standstill behaviour (IHOLD_IRUN.IHOLDDELAY, TPOWERDOWN, GCONF.faststandstill). More...
 
struct  tmc5160::Chopper
 Chopper configuration (CHOPCONF, section 6.5.2 page 51). More...
 
struct  tmc5160::StealthChop
 StealthChop settings (PWMCONF, GCONF.en_pwm_mode, section 6.5.2 page 54). More...
 
struct  tmc5160::Thresholds
 Velocity thresholds as TSTEP values (page 39); 0 disables. More...
 
struct  tmc5160::CoolStep
 CoolStep (COOLCONF, section 13, page 87). More...
 
struct  tmc5160::StallGuard
 StallGuard2 (COOLCONF, section 13, page 87). More...
 
struct  tmc5160::DcStep
 DcStep (VDCMIN, DCCTRL, section 17, page 100). More...
 
struct  tmc5160::Bridge
 Gate driver settings (DRV_CONF, section 6.1 page 35); written only when declared. More...
 
struct  tmc5160::Protection
 Short protection (SHORT_CONF, section 11.2 page 78); written only when declared. More...
 
struct  tmc5160::Flags
 General flags (GCONF). More...
 
struct  tmc5160::Diag
 DIAG0 and DIAG1 outputs (GCONF bits 5 to 13, section 6.1 page 32). More...
 
struct  tmc5160::RampProfile
 The six-point ramp (page 40). Defaults are the datasheet's quick-start values (page 116). More...
 
struct  tmc5160::Switches
 Reference switches and stop behaviour (SW_MODE, page 43). More...
 
struct  tmc5160::NEvent
 Encoder N-channel event conditions (ENCMODE, page 46). More...
 
struct  tmc5160::EncoderScale
 The ENC_CONST accumulation factor (page 45, 107). More...
 
struct  tmc5160::Encoder
 Incremental encoder (ABN), written only when declared. More...
 
struct  tmc5160::MicrostepTable
 A microstep table (MSLUT, MSLUTSEL, MSLUTSTART, section 6.5 page 47). More...
 
struct  tmc5160::UartOptions
 The UART options (used by a UART port only). More...
 
struct  tmc5160::SpiOptions
 The SPI options (used by an SPI port only). More...
 
struct  tmc5160::Config
 Everything EnsureInitialized() writes to the chip. See docs/configuration.md. More...
 
class  tmc5160::CheckedConfig
 A configuration proven valid at build time. More...
 

Enumerations

enum class  tmc5160::Error : uint8_t {
  tmc5160::Error::Ok = 0 , tmc5160::Error::NotInitialized = 1 , tmc5160::Error::InvalidArgument = 2 , tmc5160::Error::Bus = 3 ,
  tmc5160::Error::Timeout = 4 , tmc5160::Error::DeviceIdMismatch = 5 , tmc5160::Error::Crc = 6 , tmc5160::Error::Busy = 7 ,
  tmc5160::Error::DeviceFault = 8 , tmc5160::Error::Unsupported = 9 , tmc5160::Error::UnexpectedReset , tmc5160::Error::VerifyFailed = 17 ,
  tmc5160::Error::Refused = 18 , tmc5160::Error::ModeMismatch = 19 , tmc5160::Error::LimitExceeded = 20
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  tmc5160::LogLevel : uint8_t { tmc5160::LogLevel::Error = 0 , tmc5160::LogLevel::Warning , tmc5160::LogLevel::Info , tmc5160::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  tmc5160::CtrlPin : uint8_t { tmc5160::CtrlPin::DrvEnn = 0 , tmc5160::CtrlPin::DcEnable = 1 , tmc5160::CtrlPin::DcIn = 2 }
 Output pins the port may drive through the optional GpioSet() hook. More...
 
enum class  tmc5160::InputPin : uint8_t { tmc5160::InputPin::Diag0 = 0 , tmc5160::InputPin::Diag1 = 1 , tmc5160::InputPin::DcOut = 2 }
 Input pins the port may read through the optional GpioGet() hook. More...
 
enum class  tmc5160::GpioSignal : uint8_t { tmc5160::GpioSignal::INACTIVE = 0 , tmc5160::GpioSignal::ACTIVE = 1 }
 Logical level of a control pin; the port maps it to the physical polarity. More...
 
enum class  tmc5160::BusStatus : uint8_t { tmc5160::BusStatus::Ok = 0 , tmc5160::BusStatus::Fault = 1 , tmc5160::BusStatus::Timeout = 2 }
 Result of one UART exchange as the port reports it. More...
 
enum class  tmc5160::Mode : uint8_t { tmc5160::Mode::MotionController = 0 , tmc5160::Mode::StepDir = 1 }
 Where the chip's step pulses come from (SD_MODE strap, section 2.2 page 13). More...
 
enum class  tmc5160::Verify : uint8_t { tmc5160::Verify::None = 0 , tmc5160::Verify::Echo = 1 , tmc5160::Verify::ReadBack = 2 , tmc5160::Verify::Counter = 3 }
 Extra traffic a setter spends to prove a write (handbook KB-ARCH-041). More...
 
enum class  tmc5160::ChopperMode : uint8_t { tmc5160::ChopperMode::SpreadCycle = 0 , tmc5160::ChopperMode::ConstOffTime = 1 }
 Chopper mode (CHOPCONF.chm). More...
 
enum class  tmc5160::Microsteps : uint8_t {
  tmc5160::Microsteps::M256 = 0 , tmc5160::Microsteps::M128 = 1 , tmc5160::Microsteps::M64 = 2 , tmc5160::Microsteps::M32 = 3 ,
  tmc5160::Microsteps::M16 = 4 , tmc5160::Microsteps::M8 = 5 , tmc5160::Microsteps::M4 = 6 , tmc5160::Microsteps::M2 = 7 ,
  tmc5160::Microsteps::Full = 8
}
 Microstep resolution (CHOPCONF.MRES): the value is the shift from 256 microsteps. More...
 
enum class  tmc5160::OtLevel : uint8_t { tmc5160::OtLevel::C150 = 0 , tmc5160::OtLevel::C143 = 1 , tmc5160::OtLevel::C136 = 2 , tmc5160::OtLevel::C120 = 3 }
 Overtemperature shutdown level (DRV_CONF.OTSELECT, page 36). More...
 
enum class  tmc5160::Freewheel : uint8_t { tmc5160::Freewheel::Normal = 0 , tmc5160::Freewheel::Freewheel = 1 , tmc5160::Freewheel::ShortLowSide = 2 , tmc5160::Freewheel::ShortHighSide = 3 }
 Standstill mode with IHOLD = 0 (PWMCONF.freewheel, page 38). More...
 
enum class  tmc5160::RampMode : uint8_t { tmc5160::RampMode::Position = 0 , tmc5160::RampMode::VelocityPositive = 1 , tmc5160::RampMode::VelocityNegative = 2 , tmc5160::RampMode::Hold = 3 }
 Ramp generator mode (RAMPMODE, page 40). More...
 
enum class  tmc5160::StopKind : uint8_t { tmc5160::StopKind::Ramp = 0 , tmc5160::StopKind::Immediate = 1 , tmc5160::StopKind::HoldTarget = 2 , tmc5160::StopKind::Emergency = 3 }
 How Stop() brings the motor to rest (section 6.3.2, page 43). More...
 
enum class  tmc5160::Ack : uint8_t {
  tmc5160::Ack::HoldAboveRun = 1U << 0 , tmc5160::Ack::ShortProtectionOff = 1U << 1 , tmc5160::Ack::LowOtLevel = 1U << 2 , tmc5160::Ack::HardStopWithStealthChop = 1U << 3 ,
  tmc5160::Ack::VstartAboveVstop = 1U << 4 , tmc5160::Ack::DirectMode = 1U << 5 , tmc5160::Ack::VoltageModeNoCurrentLimit = 1U << 6
}
 Acknowledgements: each lets one call do what the datasheet warns against. More...
 
enum class  tmc5160::Advice : uint16_t {
  tmc5160::Advice::IrunBelow16 = 1U << 0 , tmc5160::Advice::GlobalScalerBelow129 = 1U << 1 , tmc5160::Advice::VstopBelow10 = 1U << 2 , tmc5160::Advice::PwmLimBelow5 = 1U << 3 ,
  tmc5160::Advice::PwmFrequency = 1U << 4 , tmc5160::Advice::ToffBelow2 = 1U << 5 , tmc5160::Advice::ExternalClock = 1U << 6 , tmc5160::Advice::TblOutside = 1U << 7 ,
  tmc5160::Advice::HoldAbove70 = 1U << 8
}
 Soft guidance bits from Advise(); never an error. More...
 

Functions

constexpr const char * tmc5160::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Error tmc5160::CheckTable (const MicrostepTable &table) noexcept
 Whether a table is acceptable: segment starts ordered, every entry within -248 to 247 (the peak may reach 248), and START_SIN90 equal to the last decoded entry (page 47, 105, A6).
 
constexpr Error tmc5160::CheckAcks (const Config &c) noexcept
 The guards that an acknowledgement can lift (section 2.5 of the design): each returns Refused when the configuration needs an Ack it does not carry.
 
constexpr Error tmc5160::Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
constexpr uint32_t tmc5160::Advise (const Config &config) noexcept
 Soft guidance for a configuration: bits of Advice, never an error.
 
void tmc5160::ConfigIsInvalid () noexcept
 Reached only when a CheckedConfig is built from an invalid configuration: it is never defined, so the build fails and names it (KB-CPP20-013).
 
constexpr Config tmc5160::MakeConfig (const Motor &motor, const Board &board) noexcept
 A valid configuration for a declared motor and power stage: run current 90 percent of the rated current less the tolerance reserve, hold current 30 percent of run (page 38), the datasheet's quick-start ramp, SpreadCycle with TOFF 3.
 
constexpr const char * tmc5160::GetDriverVersion () noexcept
 
constexpr uint32_t tmc5160::GetDriverVersionMajor () noexcept
 
constexpr uint32_t tmc5160::GetDriverVersionMinor () noexcept
 
constexpr uint32_t tmc5160::GetDriverVersionPatch () noexcept
 

Constants

constexpr uint32_t tmc5160::kInternalClockHz = 12'000'000
 Internal oscillator (page 119).
 
constexpr uint32_t tmc5160::kExternalClockMinHz = 4'000'000
 Lowest external clock (page 122).
 
constexpr uint32_t tmc5160::kExternalClockMaxHz = 18'000'000
 Highest external clock (page 122).
 
constexpr uint32_t tmc5160::kVfsMv = 325
 Sense threshold, typical (page 123).
 
constexpr uint32_t tmc5160::kCurrentTolerancePercent = 5
 Full-scale current tolerance.
 
constexpr uint32_t tmc5160::kVsMinMv = 10'000
 Lowest VS (page 120).
 
constexpr uint32_t tmc5160::kVsMaxMv = 55'000
 Highest VS (page 120).
 
constexpr uint32_t tmc5160::kUartMinBaud = 9000
 Lowest UART baud rate (page 26).
 
constexpr uint32_t tmc5160::kUartRecoveryBits = 12
 Idle bit times after a UART error.
 
constexpr uint32_t tmc5160::kUartReadRetries = 2
 Extra attempts of a failed UART read.
 
constexpr uint32_t tmc5160::kMaxChain = 8
 Longest SPI daisy chain the driver frames.
 
constexpr uint32_t tmc5160::kVmaxLimit = (1U << 23) - 512U
 Highest VMAX (page 41).
 
constexpr uint32_t tmc5160::kMaxSckInternalHz
 SPI clock with the internal clock (page 25).
 

Detailed Description

Errors, results, configuration and presets.

Enumeration Type Documentation

◆ Ack

enum class tmc5160::Ack : uint8_t
strong

Acknowledgements: each lets one call do what the datasheet warns against.

A call that needs one without it returns Error::Refused and writes nothing. docs/configuration.md lists each with its reason.

Enumerator
HoldAboveRun 

IHOLD above IRUN (page 38).

ShortProtectionOff 

diss2g or diss2vs set (page 22).

LowOtLevel 

120 degrees shutdown, or 136 degrees above 24 V (page 36).

HardStopWithStealthChop 

Hard stop in StealthChop: overcurrent risk (page 43).

VstartAboveVstop 

VSTOP below VSTART (page 41).

DirectMode 

Direct mode: coil currents from XTARGET (page 110).

VoltageModeNoCurrentLimit 

Direct mode with a voltage-mode chopper (page 110).

◆ Advice

enum class tmc5160::Advice : uint16_t
strong

Soft guidance bits from Advise(); never an error.

Enumerator
IrunBelow16 

IRUN below 16: coarse microsteps (page 38).

GlobalScalerBelow129 

GLOBALSCALER below 129 (page 36).

VstopBelow10 

VSTOP below 10 (page 41).

PwmLimBelow5 

PWM_LIM below 5 (page 54).

PwmFrequency 

PWM frequency outside 20 to 50 kHz (page 59).

ToffBelow2 

TOFF below 2 (page 51).

ExternalClock 

External clock outside 10 to 16 MHz (page 122).

TblOutside 

TBL outside 1 to 2 (page 51).

HoldAbove70 

Hold current above 70 percent of run (page 38).

◆ BusStatus

enum class tmc5160::BusStatus : uint8_t
strong

Result of one UART exchange as the port reports it.

Enumerator
Ok 

All bytes were sent and all expected bytes received.

Fault 

The line or the peripheral failed.

Timeout 

The reply did not arrive in time.

◆ ChopperMode

enum class tmc5160::ChopperMode : uint8_t
strong

Chopper mode (CHOPCONF.chm).

Enumerator
SpreadCycle 

Hysteresis decay, page 51.

ConstOffTime 

Classic constant off time.

◆ CtrlPin

enum class tmc5160::CtrlPin : uint8_t
strong

Output pins the port may drive through the optional GpioSet() hook.

Enumerator
DrvEnn 

DRV_ENN, active low on the package pin: ACTIVE means the driver is enabled.

DcEnable 

ENCB_DCEN_CFG4: DcStep enable input (STEP/DIR mode).

DcIn 

ENCA_DCIN_CFG5: DcStep input or emergency stop input.

◆ Error

enum class tmc5160::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; chip-specific values start at 16. [[nodiscard]] on the type: a function that returns a bare Error cannot have it ignored either (KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize() ran since.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

A port hook returned false.

Timeout 

The chip did not answer in the allowed time or a bounded wait ran out.

DeviceIdMismatch 

IOIN.VERSION is not 0x30: another chip, no chip or a wiring fault.

Crc 

The CRC-8 of a UART reply did not match (never produced on SPI).

Busy 

The motor is moving or a ramp is running: the call needs standstill.

DeviceFault 

The driver reports an error (GSTAT.drv_err): short or overtemperature.

Unsupported 

The hook, bus or mode this call needs is absent.

UnexpectedReset 

The chip reset (GSTAT.reset, SPI status bit 0): every write-only register is lost.

VerifyFailed 

A write-back, echo or interface-counter check did not match.

Refused 

A guard refused the call: a missing acknowledgement or an unsafe order.

ModeMismatch 

The SD_MODE strap or the bus does not match Config::mode.

LimitExceeded 

The request exceeds a declared motor, board or ramp limit.

◆ Freewheel

enum class tmc5160::Freewheel : uint8_t
strong

Standstill mode with IHOLD = 0 (PWMCONF.freewheel, page 38).

Enumerator
Normal 

Normal operation.

Freewheel 

Both bridges floating.

ShortLowSide 

Coils shorted through the low-side MOSFETs.

ShortHighSide 

Coils shorted through the high-side MOSFETs.

◆ GpioSignal

enum class tmc5160::GpioSignal : uint8_t
strong

Logical level of a control pin; the port maps it to the physical polarity.

Enumerator
INACTIVE 

The pin function is deasserted.

ACTIVE 

The pin function is asserted.

◆ InputPin

enum class tmc5160::InputPin : uint8_t
strong

Input pins the port may read through the optional GpioGet() hook.

Enumerator
Diag0 

DIAG0_SWN: interrupt or error output.

Diag1 

DIAG1_SWP: position compare or stall output.

DcOut 

ENCN_DCO_CFG6: DcStep ready output.

◆ LogLevel

enum class tmc5160::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events: initialised, reset.

Debug 

Detail for bring-up.

◆ Microsteps

enum class tmc5160::Microsteps : uint8_t
strong

Microstep resolution (CHOPCONF.MRES): the value is the shift from 256 microsteps.

Enumerator
M256 

256 microsteps per full step.

M128 

128.

M64 

64.

M32 

32.

M16 

16.

M8 

8.

M4 

4.

M2 

2.

Full 

Full steps.

◆ Mode

enum class tmc5160::Mode : uint8_t
strong

Where the chip's step pulses come from (SD_MODE strap, section 2.2 page 13).

Enumerator
MotionController 

SD_MODE low: the internal ramp generator moves the motor. Default.

StepDir 

SD_MODE high: STEP and DIR pins; serial configuration, no ramp.

◆ OtLevel

enum class tmc5160::OtLevel : uint8_t
strong

Overtemperature shutdown level (DRV_CONF.OTSELECT, page 36).

Enumerator
C150 

150 degrees Celsius.

C143 

143 degrees Celsius.

C136 

136 degrees Celsius.

C120 

120 degrees Celsius.

◆ RampMode

enum class tmc5160::RampMode : uint8_t
strong

Ramp generator mode (RAMPMODE, page 40).

Enumerator
Position 

Move to XTARGET with the six-point ramp.

VelocityPositive 

Run at VMAX in the positive direction.

VelocityNegative 

Run at VMAX in the negative direction.

Hold 

Velocity stays constant; used as the safe state.

◆ StopKind

enum class tmc5160::StopKind : uint8_t
strong

How Stop() brings the motor to rest (section 6.3.2, page 43).

Enumerator
Ramp 

Velocity mode with VMAX 0: decelerate with AMAX (page 83).

Immediate 

VSTART 0 and VMAX 0 in velocity mode: still the AMAX ramp (no VSTART floor).

HoldTarget 

XTARGET = XACTUAL, then position mode: decelerates with DMAX/D1 past that position and, after TZEROWAIT, runs back to it (12.2.4 c, page 83).

Emergency 

Driver off (DRV_ENN, TOFF 0): the motor is not held.

◆ Verify

enum class tmc5160::Verify : uint8_t
strong

Extra traffic a setter spends to prove a write (handbook KB-ARCH-041).

Enumerator
None 

No extra traffic.

Echo 

SPI: one more transfer; its reply must mirror the data just written (page 24).

ReadBack 

Read the register back where the chip allows it (one or two transfers).

Counter 

UART: one IFCNT read; it must have counted this write (page 33).

Function Documentation

◆ Advise()

constexpr uint32_t tmc5160::Advise ( const Config &  config)
constexprnoexcept

Soft guidance for a configuration: bits of Advice, never an error.

Parameters
configThe configuration.
Returns
The Advice bits that apply.

◆ CheckAcks()

constexpr Error tmc5160::CheckAcks ( const Config &  c)
constexprnoexcept

The guards that an acknowledgement can lift (section 2.5 of the design): each returns Refused when the configuration needs an Ack it does not carry.

Parameters
cThe configuration.
Returns
Ok or Refused.

◆ CheckTable()

constexpr Error tmc5160::CheckTable ( const MicrostepTable &  table)
constexprnoexcept

Whether a table is acceptable: segment starts ordered, every entry within -248 to 247 (the peak may reach 248), and START_SIN90 equal to the last decoded entry (page 47, 105, A6).

Parameters
tableThe table.
Returns
Ok or InvalidArgument.

◆ GetDriverVersion()

constexpr const char * tmc5160::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0", from the generated tmc5160_version.h. No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t tmc5160::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t tmc5160::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t tmc5160::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ MakeConfig()

constexpr Config tmc5160::MakeConfig ( const Motor &  motor,
const Board &  board 
)
constexprnoexcept

A valid configuration for a declared motor and power stage: run current 90 percent of the rated current less the tolerance reserve, hold current 30 percent of run (page 38), the datasheet's quick-start ramp, SpreadCycle with TOFF 3.

Parameters
motorThe motor; rated_rms_ma must be set.
boardThe power stage; rsense_mohm and supply_mv must be set.
Returns
The configuration; check it with Validate().

◆ ToString()

constexpr const char * tmc5160::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Timeout"; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error tmc5160::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the chip.

Rejects every combination the datasheet forbids: the declared motor and power stage are missing or out of range, a field is out of range, the chopper, thresholds, ramp, bridge, diag or table rules of section 2.5 of the design are broken. Rules that need a current plan (the ceiling) are checked by PlanCurrent().

Parameters
configThe configuration.
Returns
Error::Ok or Error::InvalidArgument.

Variable Documentation

◆ kMaxSckInternalHz

constexpr uint32_t tmc5160::kMaxSckInternalHz
inlineconstexpr
Initial value:
=
4'000'000

SPI clock with the internal clock (page 25).