Configuration¶

Every setting Initialize() applies, how to build a configuration, and what to change at run time.

DriverConfig¶

tmc51x0::DriverConfig (in inc/tmc51x0_types.hpp) holds the whole chip setup. Every member has a safe default; a minimal configuration sets only the motor and board values.

Member	Type	Sets	Page
`motor_spec`	`MotorSpec`	Currents (`GLOBAL_SCALER`, `IRUN`, `IHOLD`, `IHOLDDELAY`), steps per revolution	Current and chopper
`power_stage`	`PowerStageParameters`	`DRV_CONF`, `SHORT_CONF` (gate drive, BBM, short detection)	Current and chopper
`mechanical`	`MechanicalSystem`	Gearbox, lead screw or belt for unit conversion	Motion and units
`direction`	`MotorDirection`	Normal or inverted motor direction
`chopper`	`ChopperConfig`	`CHOPCONF`: SpreadCycle timing, microsteps, interpolation	Current and chopper
`stealthchop`	`StealthChopConfig`	`PWMCONF`, `TPWMTHRS`	Current and chopper
`global_config`	`GlobalConfig`	`GCONF`: StealthChop enable, DIAG outputs, direct mode
`ramp_config`	`RampConfig`	`VSTART`, `VSTOP`, `V1`, `VMAX`, `A1`, `AMAX`, `DMAX`, `D1`, `TPOWERDOWN`, `TZEROWAIT`	Motion and units
`external_clk_config`	`ExternalClockConfig`	f_CLK for all conversions; 0 = internal 12 MHz	Hardware
`stallguard`	`StallGuardConfig`	`SGT`, filter, `TCOOLTHRS`, stop on stall	StallGuard and homing
`coolstep`	`CoolStepConfig`	`COOLCONF`; disabled while `lower_threshold_sg` is 0	Current and chopper
`dcstep`	`DcStepConfig`	`DCCTRL`, `VDCMIN`; disabled by default
`reference_switch_config`	`ReferenceSwitchConfig`	`SW_MODE`: switch polarity, stop, latch
`encoder_config`	`EncoderConfig`	`ENCMODE`, resolution, deviation	API guide
`uart_config`	`UartConfig`	`NODECONF` (UART only)	Multi-chip

GetDriverConfig() returns the configuration with every change made since Initialize().

Fill the struct¶

tmc51x0::DriverConfig cfg{};

// Motor and board: the driver derives GLOBAL_SCALER, IRUN and IHOLD from these.
cfg.motor_spec.steps_per_rev = 200;
cfg.motor_spec.rated_current_ma = 2800;
cfg.motor_spec.winding_resistance_mohm = 1100;
cfg.motor_spec.winding_inductance_mh = 2.6f;
cfg.motor_spec.sense_resistor_mohm = 33;
cfg.motor_spec.supply_voltage_mv = 36000;

// Power stage (TMC5160 only: DRV_CONF, SHORT_CONF).
cfg.power_stage.mosfet_miller_charge_nc = 8.0f;   // from the MOSFET datasheet, sets DRVSTRENGTH
cfg.power_stage.bbm_time_ns = 100;                // break-before-make
cfg.power_stage.over_temp_protection = tmc51x0::OverTempProtection::Temp150C;

// Chopper: SpreadCycle with the driver's default timing, 256 microsteps.
cfg.chopper.mode = tmc51x0::ChopperMode::SPREAD_CYCLE;
cfg.chopper.toff = 5;
cfg.chopper.tbl = 2;
cfg.chopper.hstrt = 4;
cfg.chopper.hend = 0;
cfg.chopper.mres = tmc51x0::MicrostepResolution::MRES_256;

// StealthChop at low speed (GCONF.en_pwm_mode), SpreadCycle above TPWMTHRS.
cfg.global_config.en_stealthchop_mode = true;
cfg.stealthchop.pwm_freq = 1;

// Mechanics, for Unit::Mm: an 8 mm lead screw.
cfg.mechanical.system_type = tmc51x0::MechanicalSystemType::LeadScrew;
cfg.mechanical.lead_screw_pitch_mm = 8.0f;

// Ramp defaults applied by Initialize().
cfg.ramp_config.vmax = tmc51x0::VelocityValue::FromRPM(300.0f);
cfg.ramp_config.amax = tmc51x0::AccelerationValue::FromRevPerSec(5.0f);
return cfg;

Or use the builder¶

tmc51x0::ConfigBuilder (in inc/features/tmc51x0_config_builder.hpp) sets the same fields with chained calls and returns a DriverConfig:

return tmc51x0::ConfigBuilder()
    .WithMotorMa(200, 2800)
    .WithRunCurrentMa(2000)
    .WithSenseResistorMohm(33)
    .WithSupplyVoltageMv(36000)
    .WithChopperMode(tmc51x0::ChopperMode::SPREAD_CYCLE)
    .WithMicrostepResolution(tmc51x0::MicrostepResolution::MRES_256)
    .WithStealthChop(true)
    .WithStealthChopThreshold({120.0f, Unit::RPM})   // SpreadCycle above 120 RPM
    .WithMaxSpeed({300.0f, Unit::RPM})
    .WithAcceleration({5.0f, Unit::RevPerSec})
    .WithLeadScrew(8.0f)
    .Build();

Change settings at run time¶

Each subsystem changes its part of the configuration while the motor runs:

// Switch between StealthChop (quiet, low speed), SpreadCycle and full step by speed.
driver.thresholds.SetModeChangeSpeeds(1.0f, 0.5f, 5.0f, Unit::RevPerSec);   // TPWMTHRS, TCOOLTHRS, THIGH

// CoolStep: lower the current while the load is light (needs SpreadCycle and TCOOLTHRS).
tmc51x0::CoolStepConfig cool{};
cool.lower_threshold_sg = 100;
cool.upper_threshold_sg = 300;
cool.min_velocity = 0.5f;
cool.velocity_unit = Unit::RevPerSec;
driver.motorControl.ConfigureCoolStep(cool);

// Change the run and hold currents (IRUN, IHOLD: 0..31 of the GLOBAL_SCALER full scale).
driver.motorControl.SetCurrent(20, 8);

Change	Call
Currents	`motorControl.SetCurrent()`, `ConfigureMotorCurrent()`, `SetGlobalScaler()`, `SetIholdDelayMs()`
Chopper and microsteps	`motorControl.ConfigureChopper()`, `SetMicrostepResolution()`, `ConfigureStealthChop()`, `SetStealthChopEnabled()`
Mode-change speeds	`thresholds.SetModeChangeSpeeds()`, `SetModeHysteresis()`
Ramp	`rampControl.ConfigureRamp()` or the individual setters
Protection	`powerStage.ConfigurePowerStage()`, `ConfigureShortProtection()`

Starting points¶

Goal	Settings
Quiet at low speed	StealthChop on (`global_config.en_stealthchop_mode`), `pwm_autoscale` and `pwm_autograd` on, `TPWMTHRS` at the highest speed you need quiet
Torque and speed	StealthChop off, SpreadCycle with the default timing, `THIGH` with `vhighfs` for full step at high speed
Sensorless homing	SpreadCycle during homing, `TCOOLTHRS` below the homing speed, a tuned `SGT`
Step-loss detection	An ABN encoder, `SetResolution()` and `SetAllowedDeviation()`

The ESP32 examples' configuration¶

The examples split their settings into board, motor and platform structs in esp32_tmc51x0_test_config.hpp: BoardConfig_TMC51x0_EVAL (50 mΩ sense resistors) and BoardConfig_TMC51x0_BOB (110 mΩ), motor structs such as MotorConfig_17HS4401S, and platform structs for switches, encoder and mechanics. ConfigureDriverFromTestRig() combines them into a DriverConfig.

Compile-time switches are on the Installation page.