TMC5160 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Namespaces | Functions | Variables
tmc5160_units.hpp File Reference

Pure integer conversions between datasheet register units and physical units, and the current plan that ties the coil current to the declared motor and sense resistor. More...

#include <array>
#include <cstdint>
#include "tmc5160_types.hpp"

Go to the source code of this file.

Classes

struct  tmc5160::units::CurrentPlan
 The registers a current request turns into (page 36, 38). More...
 

Namespaces

namespace  tmc5160
 The TMC5160 driver: everything it declares lives here; internals in detail.
 

Functions

constexpr uint32_t tmc5160::units::RmsMa (uint32_t rsense_mohm, uint32_t global_scaler, uint32_t cs_plus_1) noexcept
 The RMS coil current for a sense resistor, GLOBALSCALER and current scale (section 9 page 74): GS/256 * CS/32 * VFS / RSENSE / sqrt(2), rounded down.
 
constexpr Result< CurrentPlan > tmc5160::units::PlanCurrent (const Config &config, uint32_t run_ma, uint32_t hold_ma) noexcept
 Turn a run and hold current request into register values, or refuse it.
 
constexpr uint32_t tmc5160::units::StealthChopLowerLimitMa (uint32_t tbl_code, uint32_t pwm_freq_code, uint32_t supply_mv, uint32_t coil_resistance_mohm) noexcept
 The StealthChop lower current limit for automatic tuning (section 7.3.1 page 62): tBLANK * fPWM * VM / RCOIL.
 
constexpr uint32_t tmc5160::units::StealthChopAt1Us (uint32_t fclk_hz) noexcept
 How long StealthChop's first tuning phase AT#1 can take: the chip must stand still for 2^20 + 2 * 2^18 clocks (page 58), plus 10 percent.
 
constexpr Error tmc5160::units::StealthGuard (const Config &config, const CurrentPlan &plan) noexcept
 The StealthChop guard of design section 2.5: with automatic scaling the run current scale IRUN must be 8 or more (page 62) and, when the coil resistance is declared, the nominal run current must reach the lower limit (page 62).
 
constexpr Result< uint32_t > tmc5160::units::VelocityRegFromHz (uint32_t hz, uint32_t fclk_hz) noexcept
 A velocity in microsteps per second as a VMAX-style register value: v * 2^24 / fCLK.
 
constexpr uint32_t tmc5160::units::HzFromVelocityReg (uint32_t velocity_reg, uint32_t fclk_hz) noexcept
 The velocity a register value stands for: v_reg * fCLK / 2^24 (page 81).
 
constexpr Result< uint32_t > tmc5160::units::AccelRegFromHzPerS (uint32_t hz_per_s, uint32_t fclk_hz) noexcept
 An acceleration in microsteps per second squared as a register value: a * 2^41 / fCLK^2.
 
constexpr uint32_t tmc5160::units::HzPerSFromAccelReg (uint32_t accel_reg, uint32_t fclk_hz) noexcept
 The acceleration a register value stands for: a_reg * fCLK^2 / 2^41.
 
constexpr uint32_t tmc5160::units::StepTimeFromVelocity (uint32_t velocity_reg) noexcept
 TSTEP for a velocity at 256 microsteps: 2^24 / v (page 38, A23).
 
constexpr uint32_t tmc5160::units::VelocityFromStepTime (uint32_t tstep) noexcept
 The velocity a TSTEP value stands for: 2^24 / TSTEP.
 
constexpr uint32_t tmc5160::units::RampSteps (uint32_t velocity_reg, uint32_t accel_reg) noexcept
 Microsteps a ramp from rest to v takes with acceleration a: v^2 / a / 2^8 (page 81).
 
constexpr uint64_t tmc5160::units::RampTimeUs (uint32_t velocity_reg, uint32_t accel_reg, uint32_t fclk_hz) noexcept
 Time of a ramp from rest to v with acceleration a, in microseconds: the velocity changes by a / 256 per update tick of 512 clocks (section 12.1).
 
constexpr uint32_t tmc5160::units::ToffClocks (uint32_t toff) noexcept
 Chopper off time: 24 + 32 * TOFF clocks (page 51).
 
constexpr uint32_t tmc5160::units::OffTimeNs (uint32_t toff, uint32_t fclk_hz) noexcept
 Chopper off time in nanoseconds.
 
constexpr uint64_t tmc5160::units::PowerDownUs (uint32_t tpowerdown, uint32_t fclk_hz) noexcept
 TPOWERDOWN delay: 2^18 clocks per count (page 38).
 
constexpr uint64_t tmc5160::units::HoldDelayUs (uint32_t hold_delay, uint32_t fclk_hz) noexcept
 IHOLDDELAY per current step: 2^18 clocks per count (page 38).
 
constexpr uint64_t tmc5160::units::ZeroWaitUs (uint32_t zero_wait, uint32_t fclk_hz) noexcept
 TZEROWAIT: 512 clocks per count (page 41).
 
constexpr uint32_t tmc5160::units::DcStepVelocity (uint32_t vdcmin, uint32_t fclk_hz) noexcept
 The velocity VDCMIN stands for: the same scale as VMAX (page 42).
 
constexpr Result< EncoderScale > tmc5160::units::EncoderScaleFor (uint32_t microsteps, uint32_t counts, bool decimal, bool negative) noexcept
 The ENC_CONST value for an encoder resolution (section 20 page 107): the factor that turns counts encoder counts per revolution into microsteps microsteps per revolution.
 
constexpr uint32_t tmc5160::units::EncConstWord (const EncoderScale &scale) noexcept
 The 32-bit ENC_CONST register word for a scale: high 16 bits integer, low 16 bits fraction. A negative binary constant is the two's complement of the 16.16 value; a negative decimal constant has the integer part decremented by one and the fraction 10000 - fraction (page 107).
 

Variables

constexpr uint64_t tmc5160::units::kInvSqrt2Q16 = 46'341
 1/sqrt(2) in 16.16 fixed point (46341 / 65536).
 

Detailed Description

Pure integer conversions between datasheet register units and physical units, and the current plan that ties the coil current to the declared motor and sense resistor.

Every function is constexpr, integer only, allocates nothing and does no I/O. All times, velocities and accelerations scale with the clock frequency fclk_hz (section 12.1, page 81). Products that can exceed 64 bits are split in two steps; the result is within one unit of the exact quotient.

Function Documentation

◆ AccelRegFromHzPerS()

constexpr Result< uint32_t > tmc5160::units::AccelRegFromHzPerS ( uint32_t  hz_per_s,
uint32_t  fclk_hz 
)
constexprnoexcept

An acceleration in microsteps per second squared as a register value: a * 2^41 / fCLK^2.

Parameters
hz_per_sThe acceleration.
fclk_hzThe clock frequency.
Returns
The register value (within 1 of exact), or InvalidArgument for a zero clock or an acceleration above 2^24 - 1.

◆ DcStepVelocity()

constexpr uint32_t tmc5160::units::DcStepVelocity ( uint32_t  vdcmin,
uint32_t  fclk_hz 
)
constexprnoexcept

The velocity VDCMIN stands for: the same scale as VMAX (page 42).

Parameters
vdcminThe register value.
fclk_hzThe clock frequency.
Returns
Microsteps per second.

◆ EncConstWord()

constexpr uint32_t tmc5160::units::EncConstWord ( const EncoderScale &  scale)
constexprnoexcept

The 32-bit ENC_CONST register word for a scale: high 16 bits integer, low 16 bits fraction. A negative binary constant is the two's complement of the 16.16 value; a negative decimal constant has the integer part decremented by one and the fraction 10000 - fraction (page 107).

Parameters
scaleThe scale.
Returns
The register word.

◆ EncoderScaleFor()

constexpr Result< EncoderScale > tmc5160::units::EncoderScaleFor ( uint32_t  microsteps,
uint32_t  counts,
bool  decimal,
bool  negative 
)
constexprnoexcept

The ENC_CONST value for an encoder resolution (section 20 page 107): the factor that turns counts encoder counts per revolution into microsteps microsteps per revolution.

Binary: microsteps / counts in 16.16, negative values as two's complement. Decimal: the integer part and the fraction in 1/10000; a negative value follows the page 107 rule (the fraction is subtracted from the integer part).

Parameters
microstepsMicrosteps per motor revolution, 1 or more.
countsEncoder counts per revolution (4 x the pulses), 1 or more.
decimaltrue for the decimal register format.
negativetrue when the encoder counts against the motor.
Returns
The scale, or InvalidArgument for a zero argument or a ratio above 32767.

◆ HoldDelayUs()

constexpr uint64_t tmc5160::units::HoldDelayUs ( uint32_t  hold_delay,
uint32_t  fclk_hz 
)
constexprnoexcept

IHOLDDELAY per current step: 2^18 clocks per count (page 38).

Parameters
hold_delayThe register value 0 to 15 (0 is treated as 1 by the chip).
fclk_hzThe clock frequency.
Returns
Microseconds.

◆ HzFromVelocityReg()

constexpr uint32_t tmc5160::units::HzFromVelocityReg ( uint32_t  velocity_reg,
uint32_t  fclk_hz 
)
constexprnoexcept

The velocity a register value stands for: v_reg * fCLK / 2^24 (page 81).

Parameters
velocity_regThe register value.
fclk_hzThe clock frequency.
Returns
Microsteps per second.

◆ HzPerSFromAccelReg()

constexpr uint32_t tmc5160::units::HzPerSFromAccelReg ( uint32_t  accel_reg,
uint32_t  fclk_hz 
)
constexprnoexcept

The acceleration a register value stands for: a_reg * fCLK^2 / 2^41.

Parameters
accel_regThe register value, 0 to 65535.
fclk_hzThe clock frequency.
Returns
Microsteps per second squared.

◆ OffTimeNs()

constexpr uint32_t tmc5160::units::OffTimeNs ( uint32_t  toff,
uint32_t  fclk_hz 
)
constexprnoexcept

Chopper off time in nanoseconds.

Parameters
toffTOFF.
fclk_hzThe clock frequency, 1 or more.
Returns
Nanoseconds.

◆ PlanCurrent()

constexpr Result< CurrentPlan > tmc5160::units::PlanCurrent ( const Config &  config,
uint32_t  run_ma,
uint32_t  hold_ma 
)
constexprnoexcept

Turn a run and hold current request into register values, or refuse it.

The run and hold current, rounded down, must stay at or under the ceiling min(max_rms_ma, rated_rms_ma), reduced by the 5 percent tolerance when include_tolerance is set (section 9 page 74, 28.2 page 123), and the sense resistor must be able to carry the run current. GLOBALSCALER is chosen from 129 to 256 (page 36 recommends above 128).

Parameters
configThe configuration (motor, board, tolerance, acknowledgements).
run_maRequested run current, RMS mA.
hold_maRequested hold current, RMS mA.
Returns
The plan, LimitExceeded (ceiling or sense resistor), Refused (hold above run without Ack::HoldAboveRun) or InvalidArgument (a zero request or a missing sense resistor).

◆ PowerDownUs()

constexpr uint64_t tmc5160::units::PowerDownUs ( uint32_t  tpowerdown,
uint32_t  fclk_hz 
)
constexprnoexcept

TPOWERDOWN delay: 2^18 clocks per count (page 38).

Parameters
tpowerdownThe register value 0 to 255.
fclk_hzThe clock frequency.
Returns
Microseconds.

◆ RampSteps()

constexpr uint32_t tmc5160::units::RampSteps ( uint32_t  velocity_reg,
uint32_t  accel_reg 
)
constexprnoexcept

Microsteps a ramp from rest to v takes with acceleration a: v^2 / a / 2^8 (page 81).

Parameters
velocity_regFinal velocity register value.
accel_regAcceleration register value, 1 or more; 0 gives 0.
Returns
The number of microsteps.

◆ RampTimeUs()

constexpr uint64_t tmc5160::units::RampTimeUs ( uint32_t  velocity_reg,
uint32_t  accel_reg,
uint32_t  fclk_hz 
)
constexprnoexcept

Time of a ramp from rest to v with acceleration a, in microseconds: the velocity changes by a / 256 per update tick of 512 clocks (section 12.1).

Parameters
velocity_regFinal velocity register value.
accel_regAcceleration register value; 0 gives 0.
fclk_hzThe clock frequency.
Returns
The time in microseconds.

◆ RmsMa()

constexpr uint32_t tmc5160::units::RmsMa ( uint32_t  rsense_mohm,
uint32_t  global_scaler,
uint32_t  cs_plus_1 
)
constexprnoexcept

The RMS coil current for a sense resistor, GLOBALSCALER and current scale (section 9 page 74): GS/256 * CS/32 * VFS / RSENSE / sqrt(2), rounded down.

Parameters
rsense_mohmThe sense resistor in milliohm, 1 or more.
global_scalerGLOBALSCALER as a divisor numerator, 32 to 256 (register 0 means 256).
cs_plus_1IRUN or IHOLD plus one, 1 to 32.
Returns
The current in mA; 0 for a zero sense resistor.

◆ StealthChopAt1Us()

constexpr uint32_t tmc5160::units::StealthChopAt1Us ( uint32_t  fclk_hz)
constexprnoexcept

How long StealthChop's first tuning phase AT#1 can take: the chip must stand still for 2^20 + 2 * 2^18 clocks (page 58), plus 10 percent.

Parameters
fclk_hzThe clock frequency.
Returns
Microseconds.

◆ StealthChopLowerLimitMa()

constexpr uint32_t tmc5160::units::StealthChopLowerLimitMa ( uint32_t  tbl_code,
uint32_t  pwm_freq_code,
uint32_t  supply_mv,
uint32_t  coil_resistance_mohm 
)
constexprnoexcept

The StealthChop lower current limit for automatic tuning (section 7.3.1 page 62): tBLANK * fPWM * VM / RCOIL.

Parameters
tbl_codeCHOPCONF.TBL 0 to 3 (16, 24, 36, 54 clocks).
pwm_freq_codePWMCONF.pwm_freq 0 to 3 (2/1024, 2/683, 2/512, 2/410 of fCLK).
supply_mvMotor supply in mV.
coil_resistance_mohmCoil resistance in mOhm; 0 gives 0 (unknown).
Returns
The limit in mA.

◆ StealthGuard()

constexpr Error tmc5160::units::StealthGuard ( const Config &  config,
const CurrentPlan &  plan 
)
constexprnoexcept

The StealthChop guard of design section 2.5: with automatic scaling the run current scale IRUN must be 8 or more (page 62) and, when the coil resistance is declared, the nominal run current must reach the lower limit (page 62).

Parameters
configThe configuration.
planThe current plan.
Returns
Ok or Refused.

◆ StepTimeFromVelocity()

constexpr uint32_t tmc5160::units::StepTimeFromVelocity ( uint32_t  velocity_reg)
constexprnoexcept

TSTEP for a velocity at 256 microsteps: 2^24 / v (page 38, A23).

Parameters
velocity_regVACTUAL-style velocity.
Returns
TSTEP, 0xFFFFF for velocity 0 and capped at 20 bits.

◆ ToffClocks()

constexpr uint32_t tmc5160::units::ToffClocks ( uint32_t  toff)
constexprnoexcept

Chopper off time: 24 + 32 * TOFF clocks (page 51).

Parameters
toffTOFF 1 to 15.
Returns
Clocks.

◆ VelocityFromStepTime()

constexpr uint32_t tmc5160::units::VelocityFromStepTime ( uint32_t  tstep)
constexprnoexcept

The velocity a TSTEP value stands for: 2^24 / TSTEP.

Parameters
tstepTSTEP; 0 gives 0.
Returns
The VACTUAL-style velocity.

◆ VelocityRegFromHz()

constexpr Result< uint32_t > tmc5160::units::VelocityRegFromHz ( uint32_t  hz,
uint32_t  fclk_hz 
)
constexprnoexcept

A velocity in microsteps per second as a VMAX-style register value: v * 2^24 / fCLK.

Parameters
hzVelocity in microsteps per second (256 per full step at the finest setting).
fclk_hzThe clock frequency.
Returns
The register value, or InvalidArgument for a zero clock or a value above 32 bits.

◆ ZeroWaitUs()

constexpr uint64_t tmc5160::units::ZeroWaitUs ( uint32_t  zero_wait,
uint32_t  fclk_hz 
)
constexprnoexcept

TZEROWAIT: 512 clocks per count (page 41).

Parameters
zero_waitThe register value 0 to 65535.
fclk_hzThe clock frequency.
Returns
Microseconds.