|
TMC5160 Driver 0.1.0
API 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). | |
The TMC5160 driver: everything it declares lives here; internals in detail.
|
strong |
|
constexprnoexcept |
The configuration menuconfig selected.
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().
|
inlineconstexpr |
SCK high to CSN high, t_CH before CSN high, minimum: more than one clock period + 10 ns (page 25).
|
inlineconstexpr |
Highest SCK frequency with the internal clock, 4 MHz; with an external clock fCLK/2 less 10 percent.
|
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).
|
inlineconstexpr |
The reply starts after SENDDELAY * 8 bit times (page 27); the port's timeout adds this margin in bit times.