TMC5160 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
tmc5160::TMC5160< Port > Class Template Reference

Driver for one TMC5160 on a platform port. More...

#include <tmc5160.hpp>

Public Member Functions

 TMC5160 (Port &port, const Config &config={}) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail.
 
 TMC5160 (const TMC5160 &)=delete
 One driver object per chip.
 
TMC5160 & operator= (const TMC5160 &)=delete
 One driver object per chip.
 
Lifecycle
Result< void > EnsureInitialized () noexcept
 Start the chip, once: the only way to initialise the driver.
 
bool IsInitialized () const noexcept
 
Result< void > Deinitialize () noexcept
 Switch the driver off (DRV_ENN inactive, TOFF 0) and mark the driver uninitialised.
 
const BeginReport & GetBeginReport () const &noexcept
 
void GetBeginReport () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 
Enable, faults, current
Result< void > Enable (Verify verify=Verify::None) noexcept
 Enable the driver: DRV_ENN active (when the port can), then TOFF from the configuration.
 
Result< void > Disable (Verify verify=Verify::None) noexcept
 Disable the driver: DRV_ENN inactive first, then TOFF 0, then (motion-controller mode) the ramp generator is stopped (VSTART 0, VMAX 0, velocity mode; XTARGET 0 in direct mode) so a later Enable() cannot resume the motion. The configured TOFF is kept.
 
bool IsEnabled () const noexcept
 
bool HasFault () const noexcept
 
Result< void > ClearFaults () noexcept
 Recover from a latched error once its cause is gone: disable (which stops the ramp generator), read DRV_STATUS, clear GSTAT, enable again when the driver was enabled.
 
Result< units::CurrentPlan > SetCurrent (uint32_t run_ma, uint32_t hold_ma, Verify verify=Verify::None) noexcept
 Set the run and hold current from the declared motor and sense resistor.
 
const units::CurrentPlan & GetCurrentPlan () const &noexcept
 
void GetCurrentPlan () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 
Result< void > SetStandstill (const Standstill &standstill, Verify verify=Verify::None) noexcept
 Set the standstill behaviour: IHOLDDELAY, TPOWERDOWN and fast standstill detection.
 
Motion (motion controller mode)
Result< void > SetRamp (const RampProfile &ramp, Verify verify=Verify::None) noexcept
 Replace the six-point ramp: the nine ramp registers in the order the datasheet allows.
 
Result< void > MoveTo (int32_t position, Verify verify=Verify::None) noexcept
 Move to an absolute position (position mode); the motor starts at once. Writes XTARGET, position mode, then VSTART and VMAX, so the motor never starts in the old velocity direction or towards an older target (pages 83, 84).
 
Result< void > MoveBy (int32_t delta, Verify verify=Verify::None) noexcept
 Move relative to the present position: reads XACTUAL, adds delta, writes XTARGET.
 
Result< void > RunVelocity (int32_t velocity, Verify verify=Verify::None) noexcept
 Run at a constant velocity until stopped.
 
Result< void > SetMaxVelocity (uint32_t vmax, Verify verify=Verify::None) noexcept
 Change VMAX (a running move follows it). VMAX must be at least VSTART, the chip's and the profile's (the next move writes the profile's again; page 40); VMAX 0 stops a position move, so VSTART 0 is written first (page 84). The value is kept for later moves: after VMAX 0, MoveTo() and MoveBy() are Refused until SetMaxVelocity() or SetRamp() gives a speed again (RunVelocity() does not). A failed call leaves the kept value as it was.
 
Result< void > Hold (Verify verify=Verify::None) noexcept
 Hold the velocity (RAMPMODE 3): the present velocity stays (a stop event still ends it). It does not slow the motor down; use Stop() for that.
 
Result< void > Stop (StopKind kind, Verify verify=Verify::None) noexcept
 Bring the motor to rest.
 
Result< void > SetHomePosition (int32_t position) noexcept
 Set the position counter (homing result): needs standstill (the check of Enable()); holds first, then writes XACTUAL and XTARGET.
 
Result< int32_t > ReadPosition () noexcept
 
Result< int32_t > ReadVelocity () noexcept
 
Result< int32_t > ReadTarget () noexcept
 
Result< bool > PositionReached () noexcept
 
Result< int32_t > ReadLatchedPosition () noexcept
 
Result< void > ReleaseStall () noexcept
 Release a stall stop: hold, check standstill (the check of Enable()), clear event_stop_sg. The motor does not restart by itself.
 
Chopper, StealthChop, CoolStep, StallGuard, DcStep
Result< void > SetChopper (const Chopper &chopper, Verify verify=Verify::None) noexcept
 Change the chopper (CHOPCONF); TOFF is written as 0 while the driver is disabled.
 
Result< void > SetStealthChop (const StealthChop &stealth, TuningPolicy policy=TuningPolicy::HoldAtRunForAt1, Verify verify=Verify::None) noexcept
 Change StealthChop (PWMCONF and GCONF.en_pwm_mode). Switching it on needs standstill (the check of Enable()) and writes IHOLD = IRUN first (page 32, 65).
 
Result< StealthChopState > ReadStealthChopState () noexcept
 
Result< void > SetThresholds (const Thresholds &thresholds, Verify verify=Verify::None) noexcept
 Set TPWMTHRS, TCOOLTHRS, THIGH and the hysteresis bit.
 
Result< void > SetCoolStep (const CoolStep &cool, Verify verify=Verify::None) noexcept
 Set CoolStep (COOLCONF); needs TCOOLTHRS of 1 or more when semin is non-zero.
 
Result< void > SetStallGuard (const StallGuard &stall, Verify verify=Verify::None) noexcept
 Set StallGuard2 (SGT and SFILT in COOLCONF).
 
Result< uint32_t > ReadStallGuard () noexcept
 
Result< void > SetDcStep (const DcStep &dcstep, Verify verify=Verify::None) noexcept
 Set DcStep (VDCMIN and DCCTRL); needs the default table, high_fullstep, high_const_off, TOFF 3 or more.
 
Result< uint32_t > ReadLostSteps () noexcept
 
Power stage
Result< void > SetBridge (const Bridge &bridge, AckSet ack={}, Verify verify=Verify::None) noexcept
 Write DRV_CONF from declared values; needs the driver disabled.
 
Result< void > SetProtection (const Protection &protection, AckSet ack={}, Verify verify=Verify::None) noexcept
 Write SHORT_CONF and the diss2g, diss2vs bits from declared values; needs the driver disabled.
 
Flags, DIAG, switches, compare, direct mode
Result< void > SetFlags (const Flags &flags, Verify verify=Verify::None) noexcept
 Change the general flags (GCONF).
 
Result< void > SetDiag (const Diag &diag, Verify verify=Verify::None) noexcept
 Change the DIAG outputs (GCONF); bits of the other SD_MODE are refused.
 
Result< void > SetSwitches (const Switches &switches, Verify verify=Verify::None) noexcept
 Change the reference switches and stop behaviour (SW_MODE).
 
Result< void > SetStopOnStall (bool enable, Verify verify=Verify::None) noexcept
 Stop on stall (sg_stop); needs TCOOLTHRS of 1 or more and no soft stop.
 
Result< void > SetPositionCompare (int32_t position) noexcept
 Arm the position compare output (X_COMPARE, DIAG1 pulse).
 
Result< void > EnterDirectMode () noexcept
 Enter direct mode: the coil currents come from XTARGET (page 110). Needs Ack::DirectMode in the configuration and a stopped motor.
 
Result< void > SetDirectCurrents (int32_t coil_a, int32_t coil_b) noexcept
 Write the two coil currents in direct mode (XTARGET: A in bits 8..0, B in bits 24..16).
 
Result< void > ExitDirectMode () noexcept
 Leave direct mode in the safe order: hold, clear direct_mode, XTARGET = XACTUAL.
 
Encoder and microstep table
Result< void > SetEncoder (const Encoder &encoder, Verify verify=Verify::None) noexcept
 Write ENCMODE, ENC_CONST and ENC_DEVIATION.
 
Result< int32_t > ReadEncoderPosition () noexcept
 
Result< void > SetEncoderPosition (int32_t position) noexcept
 Set the encoder counter.
 
Result< int32_t > ReadEncoderLatch () noexcept
 
Result< EncoderStatus > ReadEncoderStatus () noexcept
 
Result< void > ClearEncoderEvents (bool n_event, bool deviation_warn) noexcept
 Clear encoder events (write 1 to clear).
 
Result< void > SetMicrostepTable (const MicrostepTable &table) noexcept
 Write a microstep table. Needs MSCNT = 0 (read first), a motor at rest and a table that passes CheckTable().
 
Result< uint32_t > ReadMicrostepCounter () noexcept
 
Result< MicrostepCurrents > ReadMicrostepCurrents () noexcept
 
Status and diagnostics
Result< GlobalStatus > ReadGlobalStatus () noexcept
 
Result< void > ClearGlobalStatus (uint32_t mask) noexcept
 Clear GSTAT bits (write 1 to clear); bit 0 of mask is reset, 1 drv_err, 2 uv_cp.
 
Result< DriverStatus > ReadDriverStatus () noexcept
 
Result< RampStatus > ReadRampStatus () noexcept
 
Result< void > ClearRampEvents (uint32_t mask) noexcept
 Clear RAMP_STAT events: only the write-to-clear bits (mask 0x10CC) are ever written.
 
Result< InputPins > ReadInputs () noexcept
 
Result< Offsets > ReadOffsets () noexcept
 
Result< uint32_t > ReadStepTime () noexcept
 
Result< uint32_t > ReadInterfaceCounter () noexcept
 
Result< OtpImage > ReadOtp () noexcept
 
Result< uint32_t > ReadClockTrim () noexcept
 
Result< uint32_t > Identify () noexcept
 
Result< Snapshot > ReadSnapshot () noexcept
 
Result< Events > Service () noexcept
 After a DIAG0 interrupt: read GSTAT, DRV_STATUS, RAMP_STAT and ENC_STATUS and clear the events that were set.
 
Result< uint32_t > ReadRegister (uint8_t address) noexcept
 Read one readable register once, with no decoding (bring-up).
 
Result< bool > Diag0Active () noexcept
 
Result< bool > Diag1Active () noexcept
 
uint8_t GetLastStatusByte () const noexcept
 
UART nodes
Result< void > ProgramNode (uint8_t from_node, uint8_t new_node, bool nao_level) noexcept
 Program another node address into the chip at from_node (UART only), and set the NAO level.
 
Configuration
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 

Detailed Description

template<AnyPort Port>
class tmc5160::TMC5160< Port >

Driver for one TMC5160 on a platform port.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start (bus up, strap and version check, GSTAT cleared, every register written from the configuration with the driver still off), use, Deinitialize(). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded. After a chip reset (UnexpectedReset) the driver is uninitialised again: call EnsureInitialized().

Optional port hooks, found at compile time:

Hook Used for Without it
void DelayUs(uint32_t us) noexcept UART recovery, StealthChop tuning wait Compile error where a wait is needed
bool GpioSet(CtrlPin, GpioSignal) noexcept DRV_ENN, DcStep pins Enable() and Disable() use TOFF only; the pin must be tied low
bool GpioGet(InputPin, bool&) noexcept DIAG0, DIAG1, DcStep output levels Diag0Active() and Diag1Active() return Unsupported
uint32_t SckHz() const noexcept SPI clock check against the chip's limit No check
void Log(LogLevel, const char*) noexcept One line per lifecycle event or failure Nothing is logged
Template Parameters
PortYour class derived from SpiInterface<Port> or UartInterface<Port>.

Constructor & Destructor Documentation

◆ TMC5160()

template<AnyPort Port>
tmc5160::TMC5160< Port >::TMC5160 ( Port &  port,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port and store the configuration. No I/O, cannot fail.

Parameters
portThe port; it must outlive the driver.
configWhat EnsureInitialized() will apply; checked there, before any I/O.

Member Function Documentation

◆ ClearEncoderEvents()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::ClearEncoderEvents ( bool  n_event,
bool  deviation_warn 
)
noexcept

Clear encoder events (write 1 to clear).

Parameters
n_eventClear the N event.
deviation_warnClear the deviation warning.
Returns
Ok, NotInitialized, Unsupported, Bus, UnexpectedReset.

◆ ClearFaults()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::ClearFaults ( )
noexcept

Recover from a latched error once its cause is gone: disable (which stops the ramp generator), read DRV_STATUS, clear GSTAT, enable again when the driver was enabled.

A motor that is still turning when the call ends is not energised again: the faults are cleared, the driver stays disabled and the call returns Busy; call Enable() once the motor stands still.

Returns
Ok, NotInitialized, Busy (cleared, but not enabled again: the motor still turns), Refused (overtemperature or pre-warning still set, page 79), DeviceFault (the error returns at once), Bus or UnexpectedReset.

◆ ClearGlobalStatus()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::ClearGlobalStatus ( uint32_t  mask)
noexcept

Clear GSTAT bits (write 1 to clear); bit 0 of mask is reset, 1 drv_err, 2 uv_cp.

Parameters
maskThe bits to clear, 1 to 7.
Returns
Ok, NotInitialized, InvalidArgument, Bus, UnexpectedReset.

◆ ClearRampEvents()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::ClearRampEvents ( uint32_t  mask)
noexcept

Clear RAMP_STAT events: only the write-to-clear bits (mask 0x10CC) are ever written.

Parameters
maskThe bits to clear; any bit outside 0x10CC gives InvalidArgument.
Returns
Ok, NotInitialized, Unsupported, InvalidArgument, Bus, UnexpectedReset.

◆ Deinitialize()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::Deinitialize ( )
noexcept

Switch the driver off (DRV_ENN inactive, TOFF 0) and mark the driver uninitialised.

Also ends the ramp (VSTART 0, VMAX 0, velocity mode) as Disable() does. The driver is uninitialised afterwards even if a write failed; a failed switch-off keeps the duty, so a later Deinitialize() or Stop() sends it again. On a driver that never sent anything (no EnsureInitialized() call, or the last switch-off completed) it does nothing and returns Ok; after a failed start-up it still switches the chip off.

Returns
Ok, Bus, Timeout, Crc (UART), VerifyFailed or UnexpectedReset.

◆ Diag0Active()

template<AnyPort Port>
Result< bool > tmc5160::TMC5160< Port >::Diag0Active ( )
noexcept
Returns
DIAG0 level, active meaning the pin is low (open drain); Unsupported without GpioGet().

◆ Diag1Active()

template<AnyPort Port>
Result< bool > tmc5160::TMC5160< Port >::Diag1Active ( )
noexcept
Returns
DIAG1 level, active meaning the pin is low; Unsupported without GpioGet().

◆ Disable()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::Disable ( Verify  verify = Verify::None)
noexcept

Disable the driver: DRV_ENN inactive first, then TOFF 0, then (motion-controller mode) the ramp generator is stopped (VSTART 0, VMAX 0, velocity mode; XTARGET 0 in direct mode) so a later Enable() cannot resume the motion. The configured TOFF is kept.

Parameters
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, Bus, VerifyFailed or UnexpectedReset. The call never returns Busy: the bridge goes off whatever the motor does.

◆ Enable()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::Enable ( Verify  verify = Verify::None)
noexcept

Enable the driver: DRV_ENN active (when the port can), then TOFF from the configuration.

In the motion-controller mode the ramp generator must stand still first: the call returns Busy while RAMP_STAT.vzero is clear, a TZEROWAIT pause runs or, in position mode with VMAX not 0, position_reached is clear (one read, pages 44, 83 c: vzero alone is also set where the ramp turns back to a target it passed), so the bridge is never energised into a motion that began earlier. Call it again once the motor stands still. Ok does not mean the ramp is idle: a velocity-mode ramp held by a stop is left as it is. A stall stop is latched until ReleaseStall(); a reference switch stop holds only while the switch is active, and the motor restarts towards the target when the switch is released (pages 43, 44). A position move that a switch or a stall holds short of its target is Busy until Stop() or Hold() ends it.

Parameters
verifyExtra traffic to prove the CHOPCONF write.
Returns
Ok, NotInitialized, Busy (the motor is not at standstill), DeviceFault (an error is latched: ClearFaults()), Bus, VerifyFailed or UnexpectedReset.

◆ EnsureInitialized()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::EnsureInitialized ( )
noexcept

Start the chip, once: the only way to initialise the driver.

Validates the configuration and the current plan, brings the bus up, quiesces the chip (TOFF 0, DRV_ENN inactive), checks IOIN (VERSION 0x30, SD_MODE strap equals Config::mode), clears GSTAT, then writes every register from the configuration; the driver stays disabled unless Config::begin_enabled. Each write is verified as Config::verify says. It sends the start-up traffic of docs/configuration.md and blocks only in port calls.

Returns
Ok, InvalidArgument, LimitExceeded, Refused (the configuration or the current plan fails a guard; no I/O), Unsupported (the port's SPI clock is too fast), Bus, Timeout, Crc (UART), DeviceIdMismatch, ModeMismatch, DeviceFault, VerifyFailed or UnexpectedReset; with Config::begin_enabled also Busy (the motor of the last session is still turning or in its TZEROWAIT pause: the start-up is undone with the bridge off, call it again once the motor stands still).

◆ EnterDirectMode()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::EnterDirectMode ( )
noexcept

Enter direct mode: the coil currents come from XTARGET (page 110). Needs Ack::DirectMode in the configuration and a stopped motor.

Returns
Ok, NotInitialized, Unsupported, Refused (no acknowledgement), Busy, Bus, UnexpectedReset.

◆ ExitDirectMode()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::ExitDirectMode ( )
noexcept

Leave direct mode in the safe order: hold, clear direct_mode, XTARGET = XACTUAL.

Returns
Ok, NotInitialized, Bus, UnexpectedReset.

◆ GetBeginReport()

template<AnyPort Port>
const BeginReport & tmc5160::TMC5160< Port >::GetBeginReport ( ) const &
inlinenoexcept
Returns
What start-up learned; zeros before the first start. No I/O.

◆ GetConfig()

template<AnyPort Port>
const Config & tmc5160::TMC5160< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration in force. No I/O.

◆ GetCurrentPlan()

template<AnyPort Port>
const units::CurrentPlan & tmc5160::TMC5160< Port >::GetCurrentPlan ( ) const &
inlinenoexcept
Returns
The plan in force; zeros before the first start. No I/O.

◆ GetLastStatusByte()

template<AnyPort Port>
uint8_t tmc5160::TMC5160< Port >::GetLastStatusByte ( ) const
inlinenoexcept
Returns
The SPI status byte of the last transfer (bit 0 reset, 1 driver_error, 2 sg2, 3 standstill, 4 velocity_reached, 5 position_reached, 6 status_stop_l, 7 status_stop_r); one transfer old. 0 for UART. No I/O.

◆ HasFault()

template<AnyPort Port>
bool tmc5160::TMC5160< Port >::HasFault ( ) const
inlinenoexcept
Returns
true while a started driver has an error latched (SPI status bit 1 or GSTAT.drv_err); motion calls refuse. False before start-up and after a reset, which clears GSTAT. No I/O.

◆ Hold()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::Hold ( Verify  verify = Verify::None)
noexcept

Hold the velocity (RAMPMODE 3): the present velocity stays (a stop event still ends it). It does not slow the motor down; use Stop() for that.

Parameters
verifyExtra traffic to prove the write.
Returns
Ok, NotInitialized, Unsupported, Bus, VerifyFailed or UnexpectedReset.

◆ Identify()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::Identify ( )
noexcept
Returns
IOIN.VERSION (0x30), or NotInitialized, Bus, UnexpectedReset.

◆ IsEnabled()

template<AnyPort Port>
bool tmc5160::TMC5160< Port >::IsEnabled ( ) const
inlinenoexcept
Returns
true while the driver is enabled by Enable() or Config::begin_enabled. No I/O.

◆ IsInitialized()

template<AnyPort Port>
bool tmc5160::TMC5160< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized() and before Deinitialize() or a reset. No I/O.

◆ MoveBy()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::MoveBy ( int32_t  delta,
Verify  verify = Verify::None 
)
noexcept

Move relative to the present position: reads XACTUAL, adds delta, writes XTARGET.

Parameters
deltaDistance in microsteps.
verifyExtra traffic to prove the writes.
Returns
As MoveTo(), and LimitExceeded when the sum overflows 32 bits (after one read).

◆ MoveTo()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::MoveTo ( int32_t  position,
Verify  verify = Verify::None 
)
noexcept

Move to an absolute position (position mode); the motor starts at once. Writes XTARGET, position mode, then VSTART and VMAX, so the motor never starts in the old velocity direction or towards an older target (pages 83, 84).

Parameters
positionTarget in microsteps of the selected resolution.
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, Unsupported, DeviceFault (error latched), Refused (direct mode; the ramp not yet written; or VMAX 0 after SetMaxVelocity(0), until SetMaxVelocity() or SetRamp() gives a speed again: RunVelocity() does not, and the move could never start), Bus, VerifyFailed or UnexpectedReset.

◆ PositionReached()

template<AnyPort Port>
Result< bool > tmc5160::TMC5160< Port >::PositionReached ( )
noexcept
Returns
RAMP_STAT.position_reached, or NotInitialized, Bus, UnexpectedReset.

◆ ProgramNode()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::ProgramNode ( uint8_t  from_node,
uint8_t  new_node,
bool  nao_level 
)
noexcept

Program another node address into the chip at from_node (UART only), and set the NAO level.

Parameters
from_nodeThe address the chip answers to now.
new_nodeThe address to program, 0 to 254 (254 only in the addressing procedure, page 29).
nao_levelThe level of SDO_CFG0/NAO to the next chip (OUTPUT register).
Returns
Ok, NotInitialized, Unsupported (SPI), InvalidArgument, Bus, Timeout, Crc.

◆ ReadClockTrim()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::ReadClockTrim ( )
noexcept
Returns
FACTORY_CONF.FCLKTRIM (never written by the driver), or NotInitialized, Bus, UnexpectedReset.

◆ ReadDriverStatus()

template<AnyPort Port>
Result< DriverStatus > tmc5160::TMC5160< Port >::ReadDriverStatus ( )
noexcept
Returns
DRV_STATUS decoded, or NotInitialized, Bus, UnexpectedReset.

◆ ReadEncoderLatch()

template<AnyPort Port>
Result< int32_t > tmc5160::TMC5160< Port >::ReadEncoderLatch ( )
noexcept
Returns
ENC_LATCH, or NotInitialized, Unsupported, Bus, UnexpectedReset.

◆ ReadEncoderPosition()

template<AnyPort Port>
Result< int32_t > tmc5160::TMC5160< Port >::ReadEncoderPosition ( )
noexcept
Returns
X_ENC, or NotInitialized, Unsupported, Bus, UnexpectedReset.

◆ ReadEncoderStatus()

template<AnyPort Port>
Result< EncoderStatus > tmc5160::TMC5160< Port >::ReadEncoderStatus ( )
noexcept
Returns
ENC_STATUS decoded, or NotInitialized, Unsupported, Bus, UnexpectedReset.

◆ ReadGlobalStatus()

template<AnyPort Port>
Result< GlobalStatus > tmc5160::TMC5160< Port >::ReadGlobalStatus ( )
noexcept
Returns
GSTAT decoded; a set drv_err latches the fault, a set reset makes the call fail with UnexpectedReset.

◆ ReadInputs()

template<AnyPort Port>
Result< InputPins > tmc5160::TMC5160< Port >::ReadInputs ( )
noexcept
Returns
IOIN decoded (pin levels and VERSION), or NotInitialized, Bus, UnexpectedReset.

◆ ReadInterfaceCounter()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::ReadInterfaceCounter ( )
noexcept
Returns
IFCNT (UART only), or NotInitialized, Unsupported (SPI), Bus, Timeout, Crc.

◆ ReadLatchedPosition()

template<AnyPort Port>
Result< int32_t > tmc5160::TMC5160< Port >::ReadLatchedPosition ( )
noexcept
Returns
XLATCH, the position latched at a switch event, or NotInitialized, Bus, UnexpectedReset.

◆ ReadLostSteps()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::ReadLostSteps ( )
noexcept
Returns
LOST_STEPS (StepDir mode with DcStep), or NotInitialized, Unsupported (motion controller mode), Bus.

◆ ReadMicrostepCounter()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::ReadMicrostepCounter ( )
noexcept
Returns
MSCNT 0 to 1023, or NotInitialized, Bus, UnexpectedReset.

◆ ReadMicrostepCurrents()

template<AnyPort Port>
Result< MicrostepCurrents > tmc5160::TMC5160< Port >::ReadMicrostepCurrents ( )
noexcept
Returns
MSCURACT decoded, or NotInitialized, Bus, UnexpectedReset.

◆ ReadOffsets()

template<AnyPort Port>
Result< Offsets > tmc5160::TMC5160< Port >::ReadOffsets ( )
noexcept
Returns
OFFSET_READ decoded, or NotInitialized, Bus, UnexpectedReset.

◆ ReadOtp()

template<AnyPort Port>
Result< OtpImage > tmc5160::TMC5160< Port >::ReadOtp ( )
noexcept
Returns
OTP_READ decoded, or NotInitialized, Bus, UnexpectedReset.

◆ ReadPosition()

template<AnyPort Port>
Result< int32_t > tmc5160::TMC5160< Port >::ReadPosition ( )
noexcept
Returns
XACTUAL, or NotInitialized, Bus, UnexpectedReset.

◆ ReadRampStatus()

template<AnyPort Port>
Result< RampStatus > tmc5160::TMC5160< Port >::ReadRampStatus ( )
noexcept
Returns
RAMP_STAT decoded, or NotInitialized, Unsupported (StepDir mode), Bus, UnexpectedReset.

◆ ReadRegister()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::ReadRegister ( uint8_t  address)
noexcept

Read one readable register once, with no decoding (bring-up).

Parameters
addressA readable address (write-only registers are refused).
Returns
The value, or NotInitialized, Refused (write-only or absent; nothing sent), Bus, UnexpectedReset.

◆ ReadSnapshot()

template<AnyPort Port>
Result< Snapshot > tmc5160::TMC5160< Port >::ReadSnapshot ( )
noexcept
Returns
One pipelined batch (GSTAT, DRV_STATUS, RAMP_STAT, XACTUAL, VACTUAL, TSTEP, MSCNT).

◆ ReadStallGuard()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::ReadStallGuard ( )
noexcept
Returns
DRV_STATUS.SG_RESULT (0 to 1023), or NotInitialized, Bus, UnexpectedReset.

◆ ReadStealthChopState()

template<AnyPort Port>
Result< StealthChopState > tmc5160::TMC5160< Port >::ReadStealthChopState ( )
noexcept
Returns
PWM_SCALE and PWM_AUTO decoded (the tuning result), or NotInitialized, Bus, UnexpectedReset.

◆ ReadStepTime()

template<AnyPort Port>
Result< uint32_t > tmc5160::TMC5160< Port >::ReadStepTime ( )
noexcept
Returns
TSTEP, or NotInitialized, Bus, UnexpectedReset.

◆ ReadTarget()

template<AnyPort Port>
Result< int32_t > tmc5160::TMC5160< Port >::ReadTarget ( )
noexcept
Returns
XTARGET, or NotInitialized, Bus, UnexpectedReset.

◆ ReadVelocity()

template<AnyPort Port>
Result< int32_t > tmc5160::TMC5160< Port >::ReadVelocity ( )
noexcept
Returns
VACTUAL (signed 24 bit), or NotInitialized, Bus, UnexpectedReset.

◆ ReleaseStall()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::ReleaseStall ( )
noexcept

Release a stall stop: hold, check standstill (the check of Enable()), clear event_stop_sg. The motor does not restart by itself.

Returns
Ok, NotInitialized, Unsupported, Busy (the motor still moves), Bus or UnexpectedReset.

◆ RunVelocity()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::RunVelocity ( int32_t  velocity,
Verify  verify = Verify::None 
)
noexcept

Run at a constant velocity until stopped.

Write order: in the same velocity mode VMAX, VSTART, mode; from the other velocity mode the mode, VSTART, VMAX (the new speed never reaches the move the other way, and a start from rest begins at VSTART); from position mode the mode, VMAX, VSTART with no read; from hold mode one VACTUAL read decides (at rest or running the asked way: VMAX first; else the mode first).

A position ramp in its TZEROWAIT pause, or turning back after an overshoot, can start its own run-back before the mode write arrives. The backward travel is at most VSTART*t + a*t^2/2 + (VSTART + a*t)^2/(2*AMAX) microsteps, with t the time from the call to the accepted mode write (one SPI datagram, or one 8-byte UART frame: 80 bit times, 8.3 ms at 9600 baud) and a = max(A1, AMAX) when V1 > 0 and VSTART < V1, else AMAX (V1 = 0 disables A1, page 40). Set TZEROWAIT longer than t when the application calls this during a position stop (page 83 c). From position mode the motor also keeps, or speeds towards, the old VMAX for that one write before the new VMAX applies. The bound counts from the call: a run-back that already moves keeps its speed for that write too, and 8.3 ms is the least t at 9600 baud (the port and the line add to it).

Parameters
velocityVelocity register units, signed (see units::VelocityRegFromHz()).
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, Unsupported, DeviceFault, Refused, LimitExceeded (above the declared maximum or 2^23 - 512), InvalidArgument (AMAX 0), Bus, VerifyFailed, UnexpectedReset.

◆ Service()

template<AnyPort Port>
Result< Events > tmc5160::TMC5160< Port >::Service ( )
noexcept

After a DIAG0 interrupt: read GSTAT, DRV_STATUS, RAMP_STAT and ENC_STATUS and clear the events that were set.

Returns
What was found, or NotInitialized, Bus, UnexpectedReset (the reset flag of GSTAT).

◆ SetBridge()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetBridge ( const Bridge &  bridge,
AckSet  ack = {},
Verify  verify = Verify::None 
)
noexcept

Write DRV_CONF from declared values; needs the driver disabled.

Parameters
bridgeThe settings; declared must be true; break-before-make must be at least 130 percent of mosfet_switching_ns when that is non-zero.
ackThe acknowledgements: Ack::LowOtLevel for 120 degrees, or 136 degrees above 24 V.
verifyExtra traffic to prove the write.
Returns
Ok, NotInitialized, Busy (driver enabled), InvalidArgument, LimitExceeded, Refused, Bus, VerifyFailed, UnexpectedReset.

◆ SetChopper()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetChopper ( const Chopper &  chopper,
Verify  verify = Verify::None 
)
noexcept

Change the chopper (CHOPCONF); TOFF is written as 0 while the driver is disabled.

Parameters
chopperThe settings; Validate() rules apply.
verifyExtra traffic: ReadBack reads CHOPCONF back.
Returns
Ok, NotInitialized, InvalidArgument, Refused, Bus, VerifyFailed, UnexpectedReset.

◆ SetCoolStep()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetCoolStep ( const CoolStep &  cool,
Verify  verify = Verify::None 
)
noexcept

Set CoolStep (COOLCONF); needs TCOOLTHRS of 1 or more when semin is non-zero.

Parameters
coolThe settings.
verifyExtra traffic to prove the write.
Returns
Ok, NotInitialized, InvalidArgument, Bus, VerifyFailed, UnexpectedReset.

◆ SetCurrent()

template<AnyPort Port>
Result< units::CurrentPlan > tmc5160::TMC5160< Port >::SetCurrent ( uint32_t  run_ma,
uint32_t  hold_ma,
Verify  verify = Verify::None 
)
noexcept

Set the run and hold current from the declared motor and sense resistor.

The only way to write IHOLD_IRUN and GLOBALSCALER. The request is rounded down, checked against the ceiling and the sense resistor (units::PlanCurrent()), and nothing is written when a guard says no.

Parameters
run_maRun current, RMS mA.
hold_maHold current, RMS mA.
verifyExtra traffic: Echo one transfer (SPI), Counter one IFCNT read (UART).
Returns
The plan, or NotInitialized, InvalidArgument, LimitExceeded, Refused, Busy (StealthChop tuning needs the run current at or above the lower limit), Bus, VerifyFailed, UnexpectedReset.

◆ SetDcStep()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetDcStep ( const DcStep &  dcstep,
Verify  verify = Verify::None 
)
noexcept

Set DcStep (VDCMIN and DCCTRL); needs the default table, high_fullstep, high_const_off, TOFF 3 or more.

Parameters
dcstepThe settings.
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, InvalidArgument, Bus, VerifyFailed, UnexpectedReset.

◆ SetDiag()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetDiag ( const Diag &  diag,
Verify  verify = Verify::None 
)
noexcept

Change the DIAG outputs (GCONF); bits of the other SD_MODE are refused.

Parameters
diagThe settings.
verifyExtra traffic to prove the write.
Returns
Ok, NotInitialized, InvalidArgument, Bus, VerifyFailed, UnexpectedReset.

◆ SetDirectCurrents()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetDirectCurrents ( int32_t  coil_a,
int32_t  coil_b 
)
noexcept

Write the two coil currents in direct mode (XTARGET: A in bits 8..0, B in bits 24..16).

Parameters
coil_aPhase A, -248 to 248 (255 with Ack::VoltageModeNoCurrentLimit).
coil_bPhase B, same range.
Returns
Ok, NotInitialized, Refused (not in direct mode), LimitExceeded, Bus, UnexpectedReset.

◆ SetEncoder()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetEncoder ( const Encoder &  encoder,
Verify  verify = Verify::None 
)
noexcept

Write ENCMODE, ENC_CONST and ENC_DEVIATION.

Parameters
encoderThe settings; declared must be true.
verifyExtra traffic: ReadBack reads ENCMODE back.
Returns
Ok, NotInitialized, Unsupported (StepDir mode), InvalidArgument, Bus, VerifyFailed, UnexpectedReset.

◆ SetEncoderPosition()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetEncoderPosition ( int32_t  position)
noexcept

Set the encoder counter.

Parameters
positionThe new X_ENC.
Returns
Ok, NotInitialized, Unsupported, Bus, UnexpectedReset.

◆ SetFlags()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetFlags ( const Flags &  flags,
Verify  verify = Verify::None 
)
noexcept

Change the general flags (GCONF).

Parameters
flagsThe flags.
verifyExtra traffic to prove the write.
Returns
Ok, NotInitialized, Bus, VerifyFailed, UnexpectedReset.

◆ SetHomePosition()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetHomePosition ( int32_t  position)
noexcept

Set the position counter (homing result): needs standstill (the check of Enable()); holds first, then writes XACTUAL and XTARGET.

Parameters
positionThe new XACTUAL and XTARGET.
Returns
Ok, NotInitialized, Unsupported, Busy (the motor moves, or a position move has not reached its target: Stop() or Hold() first), Bus or UnexpectedReset.

◆ SetMaxVelocity()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetMaxVelocity ( uint32_t  vmax,
Verify  verify = Verify::None 
)
noexcept

Change VMAX (a running move follows it). VMAX must be at least VSTART, the chip's and the profile's (the next move writes the profile's again; page 40); VMAX 0 stops a position move, so VSTART 0 is written first (page 84). The value is kept for later moves: after VMAX 0, MoveTo() and MoveBy() are Refused until SetMaxVelocity() or SetRamp() gives a speed again (RunVelocity() does not). A failed call leaves the kept value as it was.

Parameters
vmaxThe new maximum velocity register value.
verifyExtra traffic to prove the write.
Returns
As RunVelocity(), and InvalidArgument for 0 < vmax < VSTART (nothing sent).

◆ SetMicrostepTable()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetMicrostepTable ( const MicrostepTable &  table)
noexcept

Write a microstep table. Needs MSCNT = 0 (read first), a motor at rest and a table that passes CheckTable().

Parameters
tableThe table.
Returns
Ok, NotInitialized, Refused (MSCNT is not 0 or the motor moves), InvalidArgument, Bus, UnexpectedReset.

◆ SetPositionCompare()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetPositionCompare ( int32_t  position)
noexcept

Arm the position compare output (X_COMPARE, DIAG1 pulse).

Parameters
positionThe position that makes the chip pulse.
Returns
Ok, NotInitialized, Unsupported, Bus, UnexpectedReset.

◆ SetProtection()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetProtection ( const Protection &  protection,
AckSet  ack = {},
Verify  verify = Verify::None 
)
noexcept

Write SHORT_CONF and the diss2g, diss2vs bits from declared values; needs the driver disabled.

Parameters
protectionThe settings; declared must be true.
ackAck::ShortProtectionOff when a protection is disabled.
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, Busy, InvalidArgument, Refused, Bus, VerifyFailed, UnexpectedReset.

◆ SetRamp()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetRamp ( const RampProfile &  ramp,
Verify  verify = Verify::None 
)
noexcept

Replace the six-point ramp: the nine ramp registers in the order the datasheet allows.

Parameters
rampThe profile; VMAX, D1 and VSTOP are checked (Validate() rules).
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, Unsupported (StepDir mode), InvalidArgument, Refused, Bus, VerifyFailed or UnexpectedReset.

◆ SetStallGuard()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetStallGuard ( const StallGuard &  stall,
Verify  verify = Verify::None 
)
noexcept

Set StallGuard2 (SGT and SFILT in COOLCONF).

Parameters
stallThe settings.
verifyExtra traffic to prove the write.
Returns
Ok, NotInitialized, InvalidArgument, Bus, VerifyFailed, UnexpectedReset.

◆ SetStandstill()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetStandstill ( const Standstill &  standstill,
Verify  verify = Verify::None 
)
noexcept

Set the standstill behaviour: IHOLDDELAY, TPOWERDOWN and fast standstill detection.

Parameters
standstillThe settings.
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, InvalidArgument, Refused, Bus, VerifyFailed or UnexpectedReset.

◆ SetStealthChop()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetStealthChop ( const StealthChop &  stealth,
TuningPolicy  policy = TuningPolicy::HoldAtRunForAt1,
Verify  verify = Verify::None 
)
noexcept

Change StealthChop (PWMCONF and GCONF.en_pwm_mode). Switching it on needs standstill (the check of Enable()) and writes IHOLD = IRUN first (page 32, 65).

Parameters
stealthThe settings.
policyWhether to wait for the chip's AT#1 phase and restore IHOLD.
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, Busy (moving), InvalidArgument, Refused (IRUN below 8 or below the lower limit for the declared coil resistance), Bus, VerifyFailed, UnexpectedReset.

◆ SetStopOnStall()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetStopOnStall ( bool  enable,
Verify  verify = Verify::None 
)
noexcept

Stop on stall (sg_stop); needs TCOOLTHRS of 1 or more and no soft stop.

Parameters
enabletrue to stop on a stall.
verifyExtra traffic to prove the write.
Returns
As SetSwitches().

◆ SetSwitches()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetSwitches ( const Switches &  switches,
Verify  verify = Verify::None 
)
noexcept

Change the reference switches and stop behaviour (SW_MODE).

Parameters
switchesThe settings; a hard stop with StealthChop needs Ack::HardStopWithStealthChop in the configuration.
verifyExtra traffic: ReadBack reads SW_MODE back.
Returns
Ok, NotInitialized, Unsupported, InvalidArgument, Refused, Bus, VerifyFailed, UnexpectedReset.

◆ SetThresholds()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::SetThresholds ( const Thresholds &  thresholds,
Verify  verify = Verify::None 
)
noexcept

Set TPWMTHRS, TCOOLTHRS, THIGH and the hysteresis bit.

Parameters
thresholdsThe thresholds; TPWMTHRS >= TCOOLTHRS >= THIGH where non-zero.
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, InvalidArgument, Bus, VerifyFailed, UnexpectedReset.

◆ Stop()

template<AnyPort Port>
Result< void > tmc5160::TMC5160< Port >::Stop ( StopKind  kind,
Verify  verify = Verify::None 
)
noexcept

Bring the motor to rest.

Parameters
kindRamp (velocity mode, VMAX 0), Immediate (VSTART and VMAX 0), HoldTarget (XTARGET = XACTUAL) or Emergency (driver off).
verifyExtra traffic to prove the writes.
Returns
Ok, NotInitialized, Unsupported, InvalidArgument, Bus, VerifyFailed or UnexpectedReset. Every kind is a ramp except Emergency.

The documentation for this class was generated from the following file: