tmc51x0::MotorSpec Struct Reference

Motor specification structure. More...

#include <tmc51x0_types.hpp>

Public Member Functions
	MotorSpec ()=default
	Default constructor.

Public Attributes
MotorType	motor_type {MotorType::STEPPER}
uint16_t	steps_per_rev {200}
uint16_t	rated_current_ma {1500}
	Rated motor current in milliamps (RMS)
uint32_t	winding_resistance_mohm {3}
	Winding resistance in milliohms (required for StealthChop lower limit calc)
float	winding_inductance_mh {0.0F}
	Winding inductance in millihenries (optional, 0 = not specified) (for StealthChop)
uint16_t	run_current_ma {0}
	Desired run current in milliamps (0 = use rated_current_ma)
uint16_t	hold_current_ma {0}
	Desired hold current in milliamps (0 = auto-calculate as 30% of run)
uint32_t	sense_resistor_mohm {50}
	Sense resistor value in milliohms (e.g., 50 for 0.05Ω, 0 = not specified)
uint32_t	supply_voltage_mv {24000}
	Motor supply voltage in millivolts (e.g., 24000 for 24V, 0 = not specified)
float	scaler_adjustment_percent {0.0F}
	Percentage adjustment for GLOBAL_SCALER calculation.
float	irun_adjustment_percent {0.0F}
	Percentage adjustment for IRUN calculation.
float	ihold_adjustment_percent {0.0F}
	Percentage adjustment for IHOLD calculation.
float	iholddelay_ms {100.0F}
	Total motor power down delay time (IHOLDDELAY)

Detailed Description

Motor specification structure.

High-level motor specifications for easy setup from physical parameters. Includes motor electrical specs and driver hardware configuration (sense resistor, supply voltage). Current settings (IRUN, IHOLD, GLOBAL_SCALER) can be automatically calculated from these parameters.

Note

If sense_resistor_mohm and supply_voltage_mv are set, current settings can be calculated automatically using CalculateMotorCurrent() from tmc5160_motor_calc.hpp

Constructor & Destructor Documentation

MotorSpec()

tmc51x0::MotorSpec::MotorSpec ( )

default

Default constructor.

Initializes with common NEMA 17 motor defaults. Sense resistor defaults to 50mΩ (0.05Ω) which is common on TMC51x0 boards. Supply voltage defaults to 24V which is common for stepper motors. Current settings (IRUN, IHOLD, GLOBAL_SCALER) are automatically calculated during initialization.

Member Data Documentation

hold_current_ma

uint16_t tmc51x0::MotorSpec::hold_current_ma {0}

Desired hold current in milliamps (0 = auto-calculate as 30% of run)

ihold_adjustment_percent

float tmc51x0::MotorSpec::ihold_adjustment_percent {0.0F}

Percentage adjustment for IHOLD calculation.

Applied after IHOLD is calculated but before constraining to valid range (0-31). Allows fine-tuning the calculated hold current.

Range: -50.0 to +50.0 (percentage) Example: -10.0 means decrease calculated IHOLD by 10%

Note

Formula: adjusted_ihold = calculated_ihold * (1.0 + adjustment_percent / 100.0)

Default: 0.0 (no adjustment)

iholddelay_ms

float tmc51x0::MotorSpec::iholddelay_ms {100.0F}

Total motor power down delay time (IHOLDDELAY)

Controls the total delay time for motor power down after motion as soon as standstill is detected (stst=1) and TPOWERDOWN has expired. The smooth transition avoids a motor jerk upon power down.

How Motor Power Down Works:

The motor current is reduced in steps: IRUN → (IRUN-1) → (IRUN-2) → ... → IHOLD

• Number of current reduction steps = (IRUN - IHOLD)
• Each step waits for IHOLDDELAY × (2^18 / f_clk) seconds
• Total delay = (IRUN - IHOLD) × IHOLDDELAY × (2^18 / f_clk)

Example: IRUN=31, IHOLD=16, desired total delay=500ms, f_clk=12MHz

• Steps: 31 → 30 → ... → 16 (15 steps total)
• Per-step delay needed: 500ms / 15 = 33.33 ms per step
• IHOLDDELAY = round(33.33ms / (2^18 / 12MHz)) = round(33.33 / 21.85) = 2
• Actual total delay: 15 × 2 × 21.85ms = 655.5ms

Calculation Formula:

The register value (0-15) is calculated from the desired total delay:

• Per-step delay = total_delay_ms / (IRUN - IHOLD)
• IHOLDDELAY = round((per_step_delay_ms * f_clk) / (1000 * 2^18))
• Constrained to range 0-15

Important Notes:

• If IRUN == IHOLD, there are no reduction steps, so total delay is always 0 (IHOLDDELAY is ignored)
• The actual total delay may differ slightly from the desired value due to quantization
• IHOLDDELAY is calculated after IRUN and IHOLD are determined during initialization

Typical Total Delay Ranges:

Clock Frequency	Typical Total Delay Range	Notes
8 MHz	0-500 ms	For IRUN=31, IHOLD=16: 0-491ms
12 MHz	0-500 ms	For IRUN=31, IHOLD=16: 0-328ms
16 MHz	0-500 ms	For IRUN=31, IHOLD=16: 0-246ms
24 MHz	0-500 ms	For IRUN=31, IHOLD=16: 0-164ms

Usage Guidelines:

• 0.0 ms: Instant power down (no delay, IHOLDDELAY = 0) - fastest, may cause jerk
• 100-300 ms: Typical range for most applications (smooth transition)
• 300-500 ms: For applications requiring very smooth power down
• **>500 ms**: Rarely needed, only for special applications

Note on Resolution: The delay time is quantized to discrete register values (0-15) per step. The actual total delay depends on (IRUN - IHOLD) and may differ from the desired value.

Note

This value specifies total delay time, not per-step delay.

The delay time is automatically converted to register value (0-15) during initialization.

Higher values provide smoother power down transition but longer total delay.

Lower values provide faster power down but may cause motor jerk.

Default: 0.0 (instant power down, can be set to desired total delay time)

Calculation: IHOLDDELAY = round((total_delay_ms / (IRUN - IHOLD)) * f_clk / (1000 * 262144))

If IRUN == IHOLD, the delay is always 0 regardless of this setting Total motor power down delay time in milliseconds (0.0 = instant, auto-calculated to register value 0-15)

irun_adjustment_percent

float tmc51x0::MotorSpec::irun_adjustment_percent {0.0F}

Percentage adjustment for IRUN calculation.

Applied after IRUN is calculated but before constraining to valid range (0-31). Allows fine-tuning the calculated run current.

Range: -50.0 to +50.0 (percentage) Example: +5.0 means increase calculated IRUN by 5%

Note

Formula: adjusted_irun = calculated_irun * (1.0 + adjustment_percent / 100.0)

Default: 0.0 (no adjustment)

motor_type

MotorType tmc51x0::MotorSpec::motor_type {MotorType::STEPPER}

Motor type (stepper, DC motor, or solenoid) Used for documentation. Direct mode can be enabled for any motor type via global_config.direct_mode

rated_current_ma

uint16_t tmc51x0::MotorSpec::rated_current_ma {1500}

Rated motor current in milliamps (RMS)

run_current_ma

uint16_t tmc51x0::MotorSpec::run_current_ma {0}

Desired run current in milliamps (0 = use rated_current_ma)

scaler_adjustment_percent

float tmc51x0::MotorSpec::scaler_adjustment_percent {0.0F}

Percentage adjustment for GLOBAL_SCALER calculation.

Applied after GLOBAL_SCALER is calculated but before constraining to valid range (32-256). Allows fine-tuning the calculated current scaling value.

Range: -50.0 to +50.0 (percentage) Example: +10.0 means increase calculated GLOBAL_SCALER by 10%

Note

Formula: adjusted_scaler = calculated_scaler * (1.0 + adjustment_percent / 100.0)

Default: 0.0 (no adjustment)

sense_resistor_mohm

uint32_t tmc51x0::MotorSpec::sense_resistor_mohm {50}

Sense resistor value in milliohms (e.g., 50 for 0.05Ω, 0 = not specified)

steps_per_rev

uint16_t tmc51x0::MotorSpec::steps_per_rev {200}

Steps per revolution (typically 200 for 1.8° motors) Not used for DC motors/solenoids (set to 0 or ignore)

supply_voltage_mv

uint32_t tmc51x0::MotorSpec::supply_voltage_mv {24000}

Motor supply voltage in millivolts (e.g., 24000 for 24V, 0 = not specified)

winding_inductance_mh

float tmc51x0::MotorSpec::winding_inductance_mh {0.0F}

Winding inductance in millihenries (optional, 0 = not specified) (for StealthChop)

winding_resistance_mohm

uint32_t tmc51x0::MotorSpec::winding_resistance_mohm {3}

Winding resistance in milliohms (required for StealthChop lower limit calc)

---

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

• tmc51x0_types.hpp