HF-TMC51x0 Driver (TMC5130 & TMC5160) 0.1.0-dev
Hardware Agnostic C++ Driver for the TMC51x0 (TMC5130 & TMC5160)
Loading...
Searching...
No Matches
tmc51x0::TMC51x0< CommType >::Status Struct Reference

Status / monitoring subsystem (read-only) More...

#include <tmc51x0.hpp>

Collaboration diagram for tmc51x0::TMC51x0< CommType >::Status:
[legend]

Public Member Functions

 Status (TMC51x0 &driver) noexcept
 Construct diagnostics subsystem.
 
DriverStatus GetStatus () noexcept
 Get driver status.
 
Result< bool > GetGlobalStatus (bool &drv_err, bool &uv_cp) noexcept
 Get global status flags (GSTAT)
 
Result< void > ClearGlobalStatus (bool clear_reset=true, bool clear_drv_err=true, bool clear_uv_cp=true) noexcept
 Clear global status flags (GSTAT)
 
Result< uint32_t > GetDriverStatusRegister () noexcept
 Get driver status register value.
 
Result< bool > IsOpenLoadA () noexcept
 Check if open load is detected on phase A.
 
Result< bool > IsOpenLoadB () noexcept
 Check if open load is detected on phase B.
 
Result< bool > CheckOpenLoad (bool &phase_a, bool &phase_b) noexcept
 Check if open load is detected on either phase.
 
Result< bool > IsOvertemperature () noexcept
 Check if overtemperature shutdown is active.
 
Result< bool > IsOvertempWarning () noexcept
 Check if overtemperature pre-warning is active.
 
Result< void > GetTemperatureStatus (bool &overtemp, bool &prewarning) noexcept
 Get both temperature status flags at once.
 
Result< bool > IsStealthChopActive () noexcept
 Check if StealthChop mode is currently active.
 
Result< bool > IsFullstepActive () noexcept
 Check if fullstep mode is currently active.
 
Result< uint8_t > GetActualCurrentScale () noexcept
 Get actual motor current scale (CS_ACTUAL)
 
Result< void > IsShortToSupply (bool &phase_a, bool &phase_b) noexcept
 Check for short to supply (VS) condition.
 
Result< void > IsShortToGround (bool &phase_a, bool &phase_b) noexcept
 Check for short to ground (GND) condition.
 
Result< void > GetShortCircuitStatus (bool &s2vs_a, bool &s2vs_b, bool &s2g_a, bool &s2g_b) noexcept
 Get all short circuit status flags at once.
 
Result< uint32_t > GetRampStatusRegister () noexcept
 Get ramp status register value.
 
Result< uint32_t > GetLostSteps () noexcept
 Get lost steps counter.
 
Result< uint32_t > GetTimeBetweenMicrosteps () noexcept
 Get actual time between microsteps.
 
Result< uint16_t > GetMicrostepCounter () noexcept
 Get microstep counter.
 
Result< int16_t > GetMicrostepCurrent (int16_t &phase_b) noexcept
 Get microstep current.
 
Result< uint8_t > GetPwmScale (int16_t &pwm_scale_auto) noexcept
 Get PWM scale results.
 
Result< uint8_t > GetPwmAuto (uint8_t &pwm_grad_auto) noexcept
 Get automatically determined PWM values.
 
Result< uint8_t > ReadFactoryConfig () noexcept
 Read factory configuration.
 
Result< uint8_t > ReadOtpConfig (bool &otp_s2_level, bool &otp_bbm, bool &otp_tbl) noexcept
 Read OTP configuration.
 
Result< uint8_t > GetUartTransmissionCount () noexcept
 Get UART transmission counter.
 
Result< uint8_t > ReadOffsetCalibration (uint8_t &phase_b) noexcept
 Read offset calibration results.
 
Result< void > VerifySetup () noexcept
 Run comprehensive startup verification.
 
uint8_t GetChipVersion () const noexcept
 Get detected chip version.
 
Result< void > ProgramOtpBit (uint8_t byte_index, uint8_t bit_index, bool confirm_permanent) noexcept
 Program a single OTP bit (PERMANENT - USE WITH EXTREME CAUTION!)
 
Result< void > ProgramOtpFclktrim (uint8_t fclktrim, bool confirm_permanent) noexcept
 Program OTP FCLKTRIM value (PERMANENT - USE WITH EXTREME CAUTION!)
 
Result< void > ProgramOtpS2Level (bool high_level, bool confirm_permanent) noexcept
 Program OTP short detection level default (PERMANENT!)
 
Result< void > ProgramOtpBbm (bool short_bbm, bool confirm_permanent) noexcept
 Program OTP BBM (break-before-make) default (PERMANENT!)
 
Result< void > ProgramOtpTbl (bool short_tbl, bool confirm_permanent) noexcept
 Program OTP TBL (blank time) default (PERMANENT!)
 

Private Attributes

TMC51x0driver_
 Reference to parent driver instance.
 

Detailed Description

template<typename CommType>
struct tmc51x0::TMC51x0< CommType >::Status

Status / monitoring subsystem (read-only)

Provides methods for reading status/telemetry and configuration/OTP info.

Constructor & Destructor Documentation

◆ Status()

template<typename CommType >
tmc51x0::TMC51x0< CommType >::Status::Status ( TMC51x0 & driver)
inlineexplicitnoexcept

Construct diagnostics subsystem.

Parameters
driverReference to parent TMC51x0 driver instance

Member Function Documentation

◆ CheckOpenLoad()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::CheckOpenLoad ( bool & phase_a,
bool & phase_b )
noexcept

Check if open load is detected on either phase.

Parameters
phase_aReference to store phase A status (true if open load detected)
phase_bReference to store phase B status (true if open load detected)
Returns
Result<bool> containing true if read successfully, false otherwise

Convenience method to check both phases at once.

Note
Requirements for reliable detection:
  • Must operate in SpreadCycle mode (StealthChop disabled)
  • Motor must be moving (minimum 4× microstep resolution in single direction)
  • Use low or nominal motor velocity
  • Cannot be detected in standstill (coils may have zero current)
Warning
Open load flags are informative only and do not cause driver action. Also triggered by undervoltage, high velocity, short circuit, or overtemperature conditions.
See also
Datasheet section 11.3: Open Load Diagnostics

◆ ClearGlobalStatus()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::ClearGlobalStatus ( bool clear_reset = true,
bool clear_drv_err = true,
bool clear_uv_cp = true )
noexcept

Clear global status flags (GSTAT)

Parameters
clear_resetClear the reset flag (IC was reset since last read)
clear_drv_errClear the driver error flag (short/overtemp occurred)
clear_uv_cpClear the undervoltage charge pump flag
Returns
Result<void> indicating success or error

GSTAT is a write-1-to-clear (W1C) register. Writing '1' to a bit clears that flag. Use this after handling a fault to acknowledge it.

Note
Reading GSTAT also clears the flags, so GetGlobalStatus() implicitly clears. Use this method when you want selective clearing.
See also
Datasheet section 4.1: GSTAT Register

◆ GetActualCurrentScale()

template<typename CommType >
Result< uint8_t > tmc51x0::TMC51x0< CommType >::Status::GetActualCurrentScale ( )
noexcept

Get actual motor current scale (CS_ACTUAL)

Returns
Result<uint8_t> containing current scale (0-31)

Returns the actual current scaling being applied to the motor, which may differ from IRUN due to:

  • CoolStep automatic current reduction (when load is light)
  • Current ramping (IHOLDDELAY transition between IRUN and IHOLD)
  • Standstill (showing IHOLD value)

To convert to actual current: I = (CS_ACTUAL + 1) / 32 * I_max

See also
Datasheet section 12: CoolStep Smart Current Control

◆ GetChipVersion()

template<typename CommType >
uint8_t tmc51x0::TMC51x0< CommType >::Status::GetChipVersion ( ) const
inlinenoexcept

Get detected chip version.

Returns
Chip version (0x11 = TMC5130, 0x30 = TMC5160, 0x00 = unknown)

◆ GetDriverStatusRegister()

template<typename CommType >
Result< uint32_t > tmc51x0::TMC51x0< CommType >::Status::GetDriverStatusRegister ( )
noexcept

Get driver status register value.

Parameters
statusReference to store the DRV_STATUS register value
Returns
Result<uint32_t> containing the value or error

◆ GetGlobalStatus()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::GetGlobalStatus ( bool & drv_err,
bool & uv_cp )
noexcept

Get global status flags (GSTAT)

Parameters
resetReference to store reset flag
drv_errReference to store driver error flag
uv_cpReference to store undervoltage charge pump flag
Returns
Result<bool> containing true if read successfully, false otherwise

◆ GetLostSteps()

template<typename CommType >
Result< uint32_t > tmc51x0::TMC51x0< CommType >::Status::GetLostSteps ( )
noexcept

Get lost steps counter.

Parameters
stepsReference to store the number of lost steps
Returns
Result<uint32_t> containing the value or error

Only valid when dcStep mode is enabled (SD_MODE = 1).

◆ GetMicrostepCounter()

template<typename CommType >
Result< uint16_t > tmc51x0::TMC51x0< CommType >::Status::GetMicrostepCounter ( )
noexcept

Get microstep counter.

Parameters
counterReference to store actual position in microstep table (0-1023)
Returns
Result<uint16_t> containing the value or error

Read-only register showing actual position in the microstep table.

◆ GetMicrostepCurrent()

template<typename CommType >
Result< int16_t > tmc51x0::TMC51x0< CommType >::Status::GetMicrostepCurrent ( int16_t & phase_b)
noexcept

Get microstep current.

Parameters
phase_aReference to store phase A current (signed, -256 to 255)
phase_bReference to store phase B current (signed, -256 to 255)
Returns
Result<int16_t> containing the value or error

Read-only register showing actual microstep current for both phases. Values are signed 9-bit as read from MSLUT (not scaled by current).

◆ GetPwmAuto()

template<typename CommType >
Result< uint8_t > tmc51x0::TMC51x0< CommType >::Status::GetPwmAuto ( uint8_t & pwm_grad_auto)
noexcept

Get automatically determined PWM values.

Parameters
pwm_ofs_autoReference to store auto-determined offset (0-255)
pwm_grad_autoReference to store auto-determined gradient (0-255)
Returns
Result<uint8_t> containing the value or error

Read-only register showing automatically determined PWM configuration values.

◆ GetPwmScale()

template<typename CommType >
Result< uint8_t > tmc51x0::TMC51x0< CommType >::Status::GetPwmScale ( int16_t & pwm_scale_auto)
noexcept

Get PWM scale results.

Parameters
pwm_scale_sumReference to store actual PWM duty cycle (0-255)
pwm_scale_autoReference to store automatic regulation result (signed -255...+255)
Returns
Result<uint8_t> containing the value or error

Read-only register showing stealthChop PWM scale results.

◆ GetRampStatusRegister()

template<typename CommType >
Result< uint32_t > tmc51x0::TMC51x0< CommType >::Status::GetRampStatusRegister ( )
noexcept

Get ramp status register value.

Parameters
statusReference to store the RAMP_STAT register value
Returns
Result<uint32_t> containing the value or error

◆ GetShortCircuitStatus()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::GetShortCircuitStatus ( bool & s2vs_a,
bool & s2vs_b,
bool & s2g_a,
bool & s2g_b )
noexcept

Get all short circuit status flags at once.

Parameters
s2vs_aShort to VS on phase A
s2vs_bShort to VS on phase B
s2g_aShort to GND on phase A
s2g_bShort to GND on phase B
Returns
Result<void> indicating success or error

More efficient than calling individual short check methods separately.

◆ GetStatus()

template<typename CommType >
DriverStatus tmc51x0::TMC51x0< CommType >::Status::GetStatus ( )
noexcept

Get driver status.

Returns
DriverStatus enumeration indicating current status

◆ GetTemperatureStatus()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::GetTemperatureStatus ( bool & overtemp,
bool & prewarning )
noexcept

Get both temperature status flags at once.

Parameters
overtempReference to store overtemperature shutdown status
prewarningReference to store pre-warning status
Returns
Result<void> indicating success or error

More efficient than calling IsOvertemperature() and IsOvertempWarning() separately as it only requires one register read.

◆ GetTimeBetweenMicrosteps()

template<typename CommType >
Result< uint32_t > tmc51x0::TMC51x0< CommType >::Status::GetTimeBetweenMicrosteps ( )
noexcept

Get actual time between microsteps.

Parameters
timeReference to store time between microsteps in clock cycles
Returns
Result<uint32_t> containing the value or error

Read-only register showing actual time between microsteps.

◆ GetUartTransmissionCount()

template<typename CommType >
Result< uint8_t > tmc51x0::TMC51x0< CommType >::Status::GetUartTransmissionCount ( )
noexcept

Get UART transmission counter.

Returns
UART transmission counter value, or 0 on error

Returns the number of UART transmissions since last read.

◆ IsFullstepActive()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::IsFullstepActive ( )
noexcept

Check if fullstep mode is currently active.

Returns
Result<bool> true if motor is running in fullstep mode

Fullstep becomes active when:

  • Velocity exceeds THIGH threshold AND CHOPCONF.vhighfs=1
  • OR dcStep is active

In fullstep mode, the motor runs at native full steps (not microstepping).

See also
Datasheet section 8: High Velocity Operation

◆ IsOpenLoadA()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::IsOpenLoadA ( )
noexcept

Check if open load is detected on phase A.

Returns
Result<bool> containing true if open load detected on phase A, false otherwise

Open load detection indicates an interrupted cable or connector issue.

Note
Requirements for reliable detection:
  • Must operate in SpreadCycle mode (StealthChop disabled)
  • Motor must be moving (minimum 4× microstep resolution in single direction)
  • Use low or nominal motor velocity
  • Cannot be detected in standstill (coils may have zero current)
Warning
Open load flags are informative only and do not cause driver action. Also triggered by undervoltage, high velocity, short circuit, or overtemperature conditions.
See also
Datasheet section 11.3: Open Load Diagnostics

◆ IsOpenLoadB()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::IsOpenLoadB ( )
noexcept

Check if open load is detected on phase B.

Returns
Result<bool> containing true if open load detected on phase B, false otherwise

Open load detection indicates an interrupted cable or connector issue.

Note
Requirements for reliable detection:
  • Must operate in SpreadCycle mode (StealthChop disabled)
  • Motor must be moving (minimum 4× microstep resolution in single direction)
  • Use low or nominal motor velocity
  • Cannot be detected in standstill (coils may have zero current)
Warning
Open load flags are informative only and do not cause driver action. Also triggered by undervoltage, high velocity, short circuit, or overtemperature conditions.
See also
Datasheet section 11.3: Open Load Diagnostics

◆ IsOvertemperature()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::IsOvertemperature ( )
noexcept

Check if overtemperature shutdown is active.

Returns
Result<bool> true if chip is in overtemperature shutdown

When true, the bridge drivers are disabled due to excessive die temperature. The motor will not be driven until temperature drops below the threshold.

Note
The overtemperature threshold is set via DRV_CONF.OTSELECT: 0=150°C, 1=143°C, 2=136°C, 3=120°C
See also
Datasheet section 5.1: Overtemperature Protection

◆ IsOvertempWarning()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::IsOvertempWarning ( )
noexcept

Check if overtemperature pre-warning is active.

Returns
Result<bool> true if chip temperature is approaching shutdown threshold

Pre-warning typically activates ~20°C before shutdown. Use this to implement thermal management (reduce current, add cooling, slow motion).

Note
Can be routed to DIAG0 pin via GCONF.diag0_otpw for hardware interrupt.
See also
Datasheet section 5.1: Overtemperature Protection

◆ IsShortToGround()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::IsShortToGround ( bool & phase_a,
bool & phase_b )
noexcept

Check for short to ground (GND) condition.

Parameters
phase_aReference to store phase A short-to-GND status
phase_bReference to store phase B short-to-GND status
Returns
Result<void> indicating success or error

Short to GND occurs when a high-side FET output is unexpectedly low. This can indicate:

  • Damaged motor winding shorting to ground
  • PCB fault
  • Damaged high-side FET
Note
Sensitivity is controlled by SHORT_CONF.S2G_LEVEL
Warning
Short detection causes immediate driver shutdown for protection.
See also
Datasheet section 5.2: Short Protection

◆ IsShortToSupply()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::IsShortToSupply ( bool & phase_a,
bool & phase_b )
noexcept

Check for short to supply (VS) condition.

Parameters
phase_aReference to store phase A short-to-VS status
phase_bReference to store phase B short-to-VS status
Returns
Result<void> indicating success or error

Short to VS occurs when a low-side FET output is unexpectedly high. This can indicate:

  • Damaged motor winding shorting to supply
  • PCB fault
  • Damaged low-side FET
Note
Sensitivity is controlled by SHORT_CONF.S2VS_LEVEL
Warning
Short detection causes immediate driver shutdown for protection.
See also
Datasheet section 5.2: Short Protection

◆ IsStealthChopActive()

template<typename CommType >
Result< bool > tmc51x0::TMC51x0< CommType >::Status::IsStealthChopActive ( )
noexcept

Check if StealthChop mode is currently active.

Returns
Result<bool> true if motor is being driven in StealthChop mode

StealthChop is active when:

  • GCONF.en_pwm_mode = 1 (StealthChop enabled globally)
  • Velocity is below TPWMTHRS threshold
  • Motor is not in standstill with IHOLD=0
See also
Datasheet section 9: StealthChop

◆ ProgramOtpBbm()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::ProgramOtpBbm ( bool short_bbm,
bool confirm_permanent )
noexcept

Program OTP BBM (break-before-make) default (PERMANENT!)

Parameters
short_bbmtrue for BBMCLKS=2 (shorter), false for BBMCLKS=4
confirm_permanentMust be true to confirm permanent operation
Returns
Result<void> indicating success or error

WARNING: This permanently changes the reset default for BBMCLKS. Once set to short (1), it cannot be changed back.

Note
Programs bit 6 of OTP byte 0.

◆ ProgramOtpBit()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::ProgramOtpBit ( uint8_t byte_index,
uint8_t bit_index,
bool confirm_permanent )
noexcept

Program a single OTP bit (PERMANENT - USE WITH EXTREME CAUTION!)

Parameters
byte_indexOTP byte index (0 only for TMC5160)
bit_indexBit index within the byte (0-7)
confirm_permanentMust be true to confirm permanent operation
Returns
Result<void> indicating success or error

CRITICAL WARNING: OTP memory can only be programmed ONCE. Bits can only be set (0→1), never cleared. This operation is IRREVERSIBLE.

OTP bit mapping for byte 0 (TMC5160):

  • Bits 4..0: OTP_FCLKTRIM - Clock frequency trim (factory calibrated!)
  • Bit 5: OTP_S2_LEVEL - Short detection level (0: level=6, 1: level=12)
  • Bit 6: OTP_BBM - Break-before-make (0: BBMCLKS=4, 1: BBMCLKS=2)
  • Bit 7: OTP_TBL - Blank time (0: TBL=2 ~3µs, 1: TBL=1 ~2µs)
Note
Requires minimum 10ms programming time per bit (handled internally).
The function will fail if confirm_permanent is false.
See also
Datasheet Section 6: One-Time Programmable Memory

◆ ProgramOtpFclktrim()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::ProgramOtpFclktrim ( uint8_t fclktrim,
bool confirm_permanent )
noexcept

Program OTP FCLKTRIM value (PERMANENT - USE WITH EXTREME CAUTION!)

Parameters
fclktrimClock trim value (0-31, affects internal oscillator)
confirm_permanentMust be true to confirm permanent operation
Returns
Result<void> indicating success or error

CRITICAL WARNING: This permanently changes the internal clock frequency. The factory already programs this for 12MHz. Only use if you need a different clock frequency AND understand the implications.

Note
This programs bits 4..0 of OTP byte 0. Since OTP bits can only be set (not cleared), you can only increase the FCLKTRIM value from the current OTP setting.

◆ ProgramOtpS2Level()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::ProgramOtpS2Level ( bool high_level,
bool confirm_permanent )
noexcept

Program OTP short detection level default (PERMANENT!)

Parameters
high_leveltrue for level=12 (less sensitive), false for level=6
confirm_permanentMust be true to confirm permanent operation
Returns
Result<void> indicating success or error

WARNING: This permanently changes the reset default for S2G_LEVEL and S2VS_LEVEL. Once set to high (1), it cannot be changed back.

Note
Programs bit 5 of OTP byte 0.

◆ ProgramOtpTbl()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::ProgramOtpTbl ( bool short_tbl,
bool confirm_permanent )
noexcept

Program OTP TBL (blank time) default (PERMANENT!)

Parameters
short_tbltrue for TBL=1 (~2µs), false for TBL=2 (~3µs)
confirm_permanentMust be true to confirm permanent operation
Returns
Result<void> indicating success or error

WARNING: This permanently changes the reset default for TBL. Once set to short (1), it cannot be changed back.

Note
Programs bit 7 of OTP byte 0.

◆ ReadFactoryConfig()

template<typename CommType >
Result< uint8_t > tmc51x0::TMC51x0< CommType >::Status::ReadFactoryConfig ( )
noexcept

Read factory configuration.

Parameters
fclktrimReference to store FCLKTRIM value (0-31)
Returns
Result<uint8_t> containing the value or error

Reads the factory configuration/clock trim value.

◆ ReadOffsetCalibration()

template<typename CommType >
Result< uint8_t > tmc51x0::TMC51x0< CommType >::Status::ReadOffsetCalibration ( uint8_t & phase_b)
noexcept

Read offset calibration results.

Parameters
phase_aReference to store phase A offset (0-255)
phase_bReference to store phase B offset (0-255)
Returns
Result<uint8_t> containing the value or error

Reads the results from offset calibration procedure.

◆ ReadOtpConfig()

template<typename CommType >
Result< uint8_t > tmc51x0::TMC51x0< CommType >::Status::ReadOtpConfig ( bool & otp_s2_level,
bool & otp_bbm,
bool & otp_tbl )
noexcept

Read OTP configuration.

Parameters
otp_fclktrimReference to store OTP FCLKTRIM (0-31)
otp_s2_levelReference to store OTP S2 level (0-1)
otp_bbmReference to store OTP BBM (0-1)
otp_tblReference to store OTP TBL (0-1)
Returns
Result<uint8_t> containing the value or error

Reads the one-time programmable configuration memory.

◆ VerifySetup()

template<typename CommType >
Result< void > tmc51x0::TMC51x0< CommType >::Status::VerifySetup ( )
noexcept

Run comprehensive startup verification.

Performs a full verification of the driver setup including:

  • IC Version check
  • Input pin state logging
  • Critical register checks

Logs all findings using the system logger.

Returns
Result<void> indicating success or error

Member Data Documentation

◆ driver_

template<typename CommType >
TMC51x0& tmc51x0::TMC51x0< CommType >::Status::driver_
private

Reference to parent driver instance.


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