13#ifndef TMC5160_UNITS_HPP
14#define TMC5160_UNITS_HPP
21namespace tmc5160::units {
34[[nodiscard]]
constexpr uint32_t
RmsMa(uint32_t rsense_mohm, uint32_t global_scaler,
35 uint32_t cs_plus_1)
noexcept {
36 if (rsense_mohm == 0U) {
39 const uint64_t num = uint64_t{
kVfsMv} * 1000U * global_scaler * cs_plus_1 *
kInvSqrt2Q16;
40 const uint64_t den = uint64_t{rsense_mohm} * 256U * 32U * 65'536U;
41 return static_cast<uint32_t
>(num / den);
58[[nodiscard]]
constexpr uint32_t ScaleFor(uint32_t rsense_mohm, uint32_t gs,
59 uint32_t target_ma)
noexcept {
61 for (uint32_t cs = 1U; cs <= 32U; ++cs) {
62 if (RmsMa(rsense_mohm, gs, cs) <= target_ma) {
70[[nodiscard]]
constexpr uint32_t Ceiling(
const Config& c)
noexcept {
71 uint32_t hard = c.motor.rated_rms_ma;
72 if ((c.motor.max_rms_ma != 0U) && (c.motor.max_rms_ma < hard)) {
73 hard = c.motor.max_rms_ma;
94 uint32_t hold_ma)
noexcept {
95 if ((run_ma == 0U) || (config.board.rsense_mohm == 0U)) {
101 const uint32_t ceiling = detail::Ceiling(config);
102 const uint32_t highest = (hold_ma > run_ma) ? hold_ma : run_ma;
103 const uint32_t fs256 =
RmsMa(config.board.rsense_mohm, 256U, 32U);
104 if ((highest > ceiling) || (highest > fs256)) {
108 while ((gs < 256U) && (
RmsMa(config.board.rsense_mohm, gs, 32U) < highest)) {
111 const uint32_t cs_run = detail::ScaleFor(config.board.rsense_mohm, gs, run_ma);
112 const uint32_t cs_hold = detail::ScaleFor(config.board.rsense_mohm, gs, hold_ma);
118 p.global_scaler_reg = (gs == 256U) ? 0U : gs;
119 p.irun = cs_run - 1U;
120 p.ihold = (cs_hold == 0U) ? 0U : (cs_hold - 1U);
121 p.run_ma =
RmsMa(config.board.rsense_mohm, gs, cs_run);
122 p.hold_ma =
RmsMa(config.board.rsense_mohm, gs, p.ihold + 1U);
123 p.full_scale_ma =
RmsMa(config.board.rsense_mohm, gs, 32U);
138 uint32_t coil_resistance_mohm)
noexcept {
139 constexpr std::array<uint32_t, 4> kBlank{16U, 24U, 36U, 54U};
140 constexpr std::array<uint32_t, 4> kPeriod{1024U, 683U, 512U, 410U};
141 if (coil_resistance_mohm == 0U) {
144 const uint64_t num = uint64_t{supply_mv} * 1000U * kBlank[tbl_code & 3U] * 2U;
145 return static_cast<uint32_t
>(num /
146 (uint64_t{coil_resistance_mohm} * kPeriod[pwm_freq_code & 3U]));
159 const uint64_t clocks = (uint64_t{1} << 20U) + (uint64_t{2} << 18U);
160 return static_cast<uint32_t
>(((clocks * 1'100'000U) / fclk_hz));
172 if (!(config.stealth.enable && config.stealth.autoscale)) {
175 const uint32_t lower =
177 config.motor.coil_resistance_mohm);
191 const uint64_t reg = (uint64_t{hz} << 24U) / fclk_hz;
203 uint32_t fclk_hz)
noexcept {
204 return static_cast<uint32_t
>((uint64_t{velocity_reg} * fclk_hz) >> 24U);
215 uint32_t fclk_hz)
noexcept {
216 if ((fclk_hz == 0U) || (hz_per_s > 0xFFFFFFU)) {
219 const uint64_t step1 = (uint64_t{hz_per_s} << 20U) / fclk_hz;
230 const uint64_t q = (uint64_t{accel_reg} * fclk_hz) >> 20U;
231 return static_cast<uint32_t
>((q * fclk_hz) >> 21U);
240 if (velocity_reg == 0U) {
243 const uint32_t t = (1U << 24U) / velocity_reg;
244 return (t > 0xFFFFFU) ? 0xFFFFFU : t;
253 return (tstep == 0U) ? 0U : ((1U << 24U) / tstep);
262[[nodiscard]]
constexpr uint32_t
RampSteps(uint32_t velocity_reg, uint32_t accel_reg)
noexcept {
263 return (accel_reg == 0U)
265 :
static_cast<uint32_t
>((uint64_t{velocity_reg} * velocity_reg) / accel_reg / 256U);
276[[nodiscard]]
constexpr uint64_t
RampTimeUs(uint32_t velocity_reg, uint32_t accel_reg,
277 uint32_t fclk_hz)
noexcept {
278 if ((accel_reg == 0U) || (fclk_hz == 0U)) {
281 return (uint64_t{velocity_reg} * 256U * 512U * 1'000'000U) / (uint64_t{accel_reg} * fclk_hz);
289[[nodiscard]]
constexpr uint32_t
ToffClocks(uint32_t toff)
noexcept {
290 return 24U + (32U * (toff & 15U));
299[[nodiscard]]
constexpr uint32_t
OffTimeNs(uint32_t toff, uint32_t fclk_hz)
noexcept {
300 return (fclk_hz == 0U)
302 :
static_cast<uint32_t
>((uint64_t{
ToffClocks(toff)} * 1'000'000'000U) / fclk_hz);
311[[nodiscard]]
constexpr uint64_t
PowerDownUs(uint32_t tpowerdown, uint32_t fclk_hz)
noexcept {
312 return (fclk_hz == 0U) ? 0U : (((uint64_t{tpowerdown & 255U} << 18U) * 1'000'000U) / fclk_hz);
321[[nodiscard]]
constexpr uint64_t
HoldDelayUs(uint32_t hold_delay, uint32_t fclk_hz)
noexcept {
322 return (fclk_hz == 0U) ? 0U : (((uint64_t{hold_delay & 15U} << 18U) * 1'000'000U) / fclk_hz);
331[[nodiscard]]
constexpr uint64_t
ZeroWaitUs(uint32_t zero_wait, uint32_t fclk_hz)
noexcept {
332 return (fclk_hz == 0U) ? 0U : ((uint64_t{zero_wait & 0xFFFFU} * 512U * 1'000'000U) / fclk_hz);
341[[nodiscard]]
constexpr uint32_t
DcStepVelocity(uint32_t vdcmin, uint32_t fclk_hz)
noexcept {
360 bool decimal,
bool negative)
noexcept {
361 if ((microsteps == 0U) || (counts == 0U) || ((microsteps / counts) > 32'767U)) {
364 const uint64_t unit = decimal ? 10'000U : 65'536U;
365 const uint64_t scaled = (uint64_t{microsteps} * unit) / counts;
368 s.integer =
static_cast<int16_t
>(scaled / unit);
369 s.fraction =
static_cast<uint16_t
>(scaled % unit);
370 s.negative = negative;
383 if (!scale.negative) {
384 return (
static_cast<uint32_t
>(
static_cast<uint16_t
>(scale.integer)) << 16U) | scale.fraction;
387 const uint32_t frac = (scale.fraction == 0U) ? 0U : (10'000U - scale.fraction);
388 const int32_t whole = (scale.fraction == 0U) ? -
static_cast<int32_t
>(scale.integer)
389 : (-
static_cast<int32_t
>(scale.integer) - 1);
390 return (
static_cast<uint32_t
>(
static_cast<uint16_t
>(
static_cast<int16_t
>(whole))) << 16U) |
393 const uint32_t magnitude =
394 (
static_cast<uint32_t
>(
static_cast<uint16_t
>(scale.integer)) << 16U) | scale.fraction;
395 return 0U - magnitude;
constexpr uint32_t kCurrentTolerancePercent
Full-scale current tolerance.
Definition tmc5160_types.hpp:574
constexpr uint32_t kVfsMv
Sense threshold, typical (page 123).
Definition tmc5160_types.hpp:573
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition tmc5160_types.hpp:39
@ HoldAboveRun
IHOLD above IRUN (page 38).
@ LimitExceeded
The request exceeds a declared motor, board or ramp limit.
@ InvalidArgument
An argument or a Config field is out of range; nothing was sent.
@ Refused
A guard refused the call: a missing acknowledgement or an unsafe order.
Everything EnsureInitialized() writes to the chip. See docs/configuration.md.
Definition tmc5160_types.hpp:536
The ENC_CONST accumulation factor (page 45, 107).
Definition tmc5160_types.hpp:495
bool decimal
ENCMODE.enc_sel_decimal: fraction in 1/10000 instead of 1/65536.
Definition tmc5160_types.hpp:496
The value of a call, or why there is none.
Definition tmc5160_types.hpp:111
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition tmc5160_types.hpp:137
static constexpr Result Success(T v) noexcept
A successful result.
Definition tmc5160_types.hpp:129
The registers a current request turns into (page 36, 38).
Definition tmc5160_units.hpp:45
uint32_t full_scale_ma
The current at IRUN 31 with this GLOBALSCALER.
Definition tmc5160_units.hpp:52
uint32_t run_ma
The nominal run current the registers give, in mA, rounded down.
Definition tmc5160_units.hpp:50
uint32_t ihold
IHOLD 0 to 31 (0 is 1/32 of full scale, not zero current).
Definition tmc5160_units.hpp:49
uint32_t global_scaler
GLOBALSCALER as a numerator, 129 to 256.
Definition tmc5160_units.hpp:46
uint32_t irun
IRUN 0 to 31.
Definition tmc5160_units.hpp:48
uint32_t global_scaler_reg
The register value: 0 stands for 256.
Definition tmc5160_units.hpp:47
uint32_t hold_ma
The nominal hold current the registers give, in mA.
Definition tmc5160_units.hpp:51
Public types of the TMC5160 driver: errors, Result<T>, configuration, validation and advice.
constexpr uint32_t HzFromVelocityReg(uint32_t velocity_reg, uint32_t fclk_hz) noexcept
The velocity a register value stands for: v_reg * fCLK / 2^24 (page 81).
Definition tmc5160_units.hpp:202
constexpr uint32_t DcStepVelocity(uint32_t vdcmin, uint32_t fclk_hz) noexcept
The velocity VDCMIN stands for: the same scale as VMAX (page 42).
Definition tmc5160_units.hpp:341
constexpr uint64_t kInvSqrt2Q16
1/sqrt(2) in 16.16 fixed point (46341 / 65536).
Definition tmc5160_units.hpp:24
constexpr uint64_t 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 p...
Definition tmc5160_units.hpp:276
constexpr uint64_t PowerDownUs(uint32_t tpowerdown, uint32_t fclk_hz) noexcept
TPOWERDOWN delay: 2^18 clocks per count (page 38).
Definition tmc5160_units.hpp:311
constexpr uint32_t VelocityFromStepTime(uint32_t tstep) noexcept
The velocity a TSTEP value stands for: 2^24 / TSTEP.
Definition tmc5160_units.hpp:252
constexpr uint32_t ToffClocks(uint32_t toff) noexcept
Chopper off time: 24 + 32 * TOFF clocks (page 51).
Definition tmc5160_units.hpp:289
constexpr uint32_t 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).
Definition tmc5160_units.hpp:262
constexpr Result< CurrentPlan > 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.
Definition tmc5160_units.hpp:93
constexpr Result< uint32_t > 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.
Definition tmc5160_units.hpp:214
constexpr uint32_t 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...
Definition tmc5160_units.hpp:34
constexpr Result< uint32_t > 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.
Definition tmc5160_units.hpp:187
constexpr uint32_t 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^1...
Definition tmc5160_units.hpp:155
constexpr uint64_t ZeroWaitUs(uint32_t zero_wait, uint32_t fclk_hz) noexcept
TZEROWAIT: 512 clocks per count (page 41).
Definition tmc5160_units.hpp:331
constexpr uint32_t HzPerSFromAccelReg(uint32_t accel_reg, uint32_t fclk_hz) noexcept
The acceleration a register value stands for: a_reg * fCLK^2 / 2^41.
Definition tmc5160_units.hpp:229
constexpr uint32_t OffTimeNs(uint32_t toff, uint32_t fclk_hz) noexcept
Chopper off time in nanoseconds.
Definition tmc5160_units.hpp:299
constexpr uint32_t EncConstWord(const EncoderScale &scale) noexcept
The 32-bit ENC_CONST register word for a scale: high 16 bits integer, low 16 bits fraction....
Definition tmc5160_units.hpp:382
constexpr Error 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 b...
Definition tmc5160_units.hpp:171
constexpr Result< EncoderScale > 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 enc...
Definition tmc5160_units.hpp:359
constexpr uint32_t 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 ...
Definition tmc5160_units.hpp:136
constexpr uint32_t StepTimeFromVelocity(uint32_t velocity_reg) noexcept
TSTEP for a velocity at 256 microsteps: 2^24 / v (page 38, A23).
Definition tmc5160_units.hpp:239
constexpr uint64_t HoldDelayUs(uint32_t hold_delay, uint32_t fclk_hz) noexcept
IHOLDDELAY per current step: 2^18 clocks per count (page 38).
Definition tmc5160_units.hpp:321