TMC5160 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions
tmc5160 Namespace Reference

The TMC5160 driver: everything it declares lives here; internals in detail. More...

Namespaces

namespace  reg
 The TMC5160 register map.
 

Classes

struct  AckSet
 A set of acknowledgements. More...
 
struct  BeginReport
 What start-up learned about the chip. More...
 
struct  Board
 The power stage as built: the sense resistor and the supply. More...
 
struct  Bridge
 Gate driver settings (DRV_CONF, section 6.1 page 35); written only when declared. More...
 
class  CheckedConfig
 A configuration proven valid at build time. More...
 
struct  Chopper
 Chopper configuration (CHOPCONF, section 6.5.2 page 51). More...
 
struct  Clock
 The clock: internal 12 MHz or an external clock on CLK (page 119). More...
 
struct  Config
 Everything EnsureInitialized() writes to the chip. See docs/configuration.md. More...
 
struct  CoolStep
 CoolStep (COOLCONF, section 13, page 87). More...
 
struct  Current
 Run and hold current requests, RMS in mA; PlanCurrent() turns them into registers. More...
 
struct  DcStep
 DcStep (VDCMIN, DCCTRL, section 17, page 100). More...
 
struct  Diag
 DIAG0 and DIAG1 outputs (GCONF bits 5 to 13, section 6.1 page 32). More...
 
struct  DriverStatus
 DRV_STATUS, decoded (page 56). More...
 
struct  Encoder
 Incremental encoder (ABN), written only when declared. More...
 
struct  EncoderScale
 The ENC_CONST accumulation factor (page 45, 107). More...
 
struct  EncoderStatus
 ENC_STATUS, decoded (page 45). More...
 
struct  Events
 What Service() found and cleared. More...
 
struct  Flags
 General flags (GCONF). More...
 
struct  GlobalStatus
 GSTAT, decoded (page 33). More...
 
struct  InputPins
 IOIN, decoded (page 34). More...
 
struct  MicrostepCurrents
 MSCURACT, decoded (page 47): the unscaled microstep currents, -255 to 255. More...
 
struct  MicrostepTable
 A microstep table (MSLUT, MSLUTSEL, MSLUTSTART, section 6.5 page 47). More...
 
struct  Motor
 The motor as its data sheet declares it; the current ceiling comes from here. More...
 
struct  NEvent
 Encoder N-channel event conditions (ENCMODE, page 46). More...
 
struct  Offsets
 OFFSET_READ, decoded (page 36). More...
 
struct  OtpImage
 OTP_READ, decoded (page 35, 37). More...
 
struct  Protection
 Short protection (SHORT_CONF, section 11.2 page 78); written only when declared. More...
 
struct  RampProfile
 The six-point ramp (page 40). Defaults are the datasheet's quick-start values (page 116). More...
 
struct  RampStatus
 RAMP_STAT, decoded (page 44). More...
 
struct  Result
 The value of a call, or why there is none. More...
 
struct  Result< void >
 The result of a call that returns no value. More...
 
struct  Snapshot
 One pipelined batch of the values a monitor wants together. More...
 
class  SpiInterface
 CRTP base of the platform SPI port. More...
 
struct  SpiOptions
 The SPI options (used by an SPI port only). More...
 
struct  StallGuard
 StallGuard2 (COOLCONF, section 13, page 87). More...
 
struct  Standstill
 Standstill behaviour (IHOLD_IRUN.IHOLDDELAY, TPOWERDOWN, GCONF.faststandstill). More...
 
struct  StealthChop
 StealthChop settings (PWMCONF, GCONF.en_pwm_mode, section 6.5.2 page 54). More...
 
struct  StealthChopState
 PWM_SCALE and PWM_AUTO, decoded (page 48). More...
 
struct  Switches
 Reference switches and stop behaviour (SW_MODE, page 43). More...
 
struct  Thresholds
 Velocity thresholds as TSTEP values (page 39); 0 disables. More...
 
class  TMC5160
 Driver for one TMC5160 on a platform port. More...
 
class  UartInterface
 CRTP base of the platform UART port. More...
 
struct  UartOptions
 The UART options (used by a UART port only). More...
 

Concepts

concept  AnyPort
 Satisfied by a port of exactly one bus kind.
 
concept  SpiPort
 Satisfied by a class that derives from SpiInterface<Port> and implements the required hooks with exactly the types above, noexcept (KB-CPP20-006).
 
concept  UartPort
 Satisfied by a class that derives from UartInterface<Port> and implements the required hooks with exactly the types above.
 

Enumerations

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

Functions

constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected.
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Error 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 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 Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
constexpr uint32_t Advise (const Config &config) noexcept
 Soft guidance for a configuration: bits of Advice, never an error.
 
void 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 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 * GetDriverVersion () noexcept
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 

Variables

Bus requirements

What the TMC5160 needs from the UART (section 5, page 26).

constexpr uint8_t kSpiMode = 3
 SPI mode: SCK idles high, data is latched on the rising edge ("usually referred to as mode 3").
 
constexpr bool kMsbFirst = true
 Each byte is clocked most significant bit first.
 
constexpr uint32_t kMaxClockHz = 4'000'000
 
constexpr uint32_t kDatagramBytes = 5
 A datagram is 40 bits; the whole datagram (5 bytes per chip in a chain) is one CSN low period.
 
constexpr uint32_t kMinCsHighNs = 200
 CSN high time between datagrams is more than 2 clocks + 10 ns: 200 ns covers the slowest clock.
 
constexpr uint32_t kCsHoldNs = 100
 
constexpr uint32_t kCsSetupNs = 10
 CSN low to the first SCK edge, t_CC, minimum.
 
constexpr bool kContinuousWord = true
 true: the chip needs the 40 bits of a datagram without a CSN pulse in between.
 
constexpr uint8_t kUartDataBits = 8
 Data bits of a frame: 8N1, one start bit and one stop bit.
 
constexpr uint32_t kUartGapResetBits = 63
 A gap of more than this many bit times between start bits resets the chip's receiver (page 26).
 
constexpr uint32_t kUartReplyMarginBits = 64
 
constexpr uint32_t kMaxBaudRate = 750'000
 Highest baud rate: fCLK / 16 (page 26); 750 kBaud with the internal 12 MHz clock.
 
constexpr uint32_t kTurnaroundUs = 12'500
 
Constants
constexpr uint32_t kInternalClockHz = 12'000'000
 Internal oscillator (page 119).
 
constexpr uint32_t kExternalClockMinHz = 4'000'000
 Lowest external clock (page 122).
 
constexpr uint32_t kExternalClockMaxHz = 18'000'000
 Highest external clock (page 122).
 
constexpr uint32_t kVfsMv = 325
 Sense threshold, typical (page 123).
 
constexpr uint32_t kCurrentTolerancePercent = 5
 Full-scale current tolerance.
 
constexpr uint32_t kVsMinMv = 10'000
 Lowest VS (page 120).
 
constexpr uint32_t kVsMaxMv = 55'000
 Highest VS (page 120).
 
constexpr uint32_t kUartMinBaud = 9000
 Lowest UART baud rate (page 26).
 
constexpr uint32_t kUartRecoveryBits = 12
 Idle bit times after a UART error.
 
constexpr uint32_t kUartReadRetries = 2
 Extra attempts of a failed UART read.
 
constexpr uint32_t kMaxChain = 8
 Longest SPI daisy chain the driver frames.
 
constexpr uint32_t kVmaxLimit = (1U << 23) - 512U
 Highest VMAX (page 41).
 
constexpr uint32_t kMaxSckInternalHz
 SPI clock with the internal clock (page 25).
 

Detailed Description

The TMC5160 driver: everything it declares lives here; internals in detail.

Enumeration Type Documentation

◆ TuningPolicy

enum class tmc5160::TuningPolicy : uint8_t
strong

What SetStealthChop() does about IHOLD while the chip tunes itself (page 58, 65).

Enumerator
HoldAtRunForAt1 

Wait the AT#1 time at IHOLD = IRUN, then restore the hold current.

LeaveHoldAtRun 

Leave IHOLD = IRUN; the caller restores it with SetCurrent().

Function Documentation

◆ KconfigDefaults()

constexpr Config tmc5160::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected.

Returns
Config{} when CONFIG_TMC5160_MOTOR_RATED_MA is not defined (no Kconfig); otherwise MakeConfig() of the declared motor and board with the other options applied. Check it with Validate().

Variable Documentation

◆ kCsHoldNs

constexpr uint32_t tmc5160::kCsHoldNs = 100
inlineconstexpr

SCK high to CSN high, t_CH before CSN high, minimum: more than one clock period + 10 ns (page 25).

◆ kMaxClockHz

constexpr uint32_t tmc5160::kMaxClockHz = 4'000'000
inlineconstexpr

Highest SCK frequency with the internal clock, 4 MHz; with an external clock fCLK/2 less 10 percent.

◆ kTurnaroundUs

constexpr uint32_t tmc5160::kTurnaroundUs = 12'500
inlineconstexpr

Last request byte to the first reply byte, at most: SENDDELAY 15 is 120 bit times, 12.5 ms at the lowest baud rate of 9600 (page 27).

◆ kUartReplyMarginBits

constexpr uint32_t tmc5160::kUartReplyMarginBits = 64
inlineconstexpr

The reply starts after SENDDELAY * 8 bit times (page 27); the port's timeout adds this margin in bit times.