TMC5160 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
tmc5160_units.hpp
Go to the documentation of this file.
1
13#ifndef TMC5160_UNITS_HPP
14#define TMC5160_UNITS_HPP
15
16#include <array>
17#include <cstdint>
18
19#include "tmc5160_types.hpp"
20
21namespace tmc5160::units {
22
24inline constexpr uint64_t kInvSqrt2Q16 = 46'341;
25
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) {
37 return 0U;
38 }
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);
42}
43
46 uint32_t global_scaler{0};
47 uint32_t global_scaler_reg{0};
48 uint32_t irun{0};
49 uint32_t ihold{0};
50 uint32_t run_ma{0};
51 uint32_t hold_ma{0};
52 uint32_t full_scale_ma{0};
53};
54
55namespace detail {
58[[nodiscard]] constexpr uint32_t ScaleFor(uint32_t rsense_mohm, uint32_t gs,
59 uint32_t target_ma) noexcept {
60 uint32_t best = 0U;
61 for (uint32_t cs = 1U; cs <= 32U; ++cs) {
62 if (RmsMa(rsense_mohm, gs, cs) <= target_ma) {
63 best = cs;
64 }
65 }
66 return best;
67}
68
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;
74 }
75 return c.include_tolerance ? ((hard * 100U) / (100U + kCurrentTolerancePercent)) : hard;
76}
77} // namespace detail
78
93[[nodiscard]] constexpr Result<CurrentPlan> PlanCurrent(const Config& config, uint32_t run_ma,
94 uint32_t hold_ma) noexcept {
95 if ((run_ma == 0U) || (config.board.rsense_mohm == 0U)) {
97 }
98 if ((hold_ma > run_ma) && !config.ack.Has(Ack::HoldAboveRun)) {
100 }
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)) {
106 }
107 uint32_t gs = 129U;
108 while ((gs < 256U) && (RmsMa(config.board.rsense_mohm, gs, 32U) < highest)) {
109 ++gs;
110 }
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);
113 if (cs_run == 0U) {
115 }
116 CurrentPlan p{};
117 p.global_scaler = gs;
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);
125}
126
136[[nodiscard]] constexpr uint32_t StealthChopLowerLimitMa(uint32_t tbl_code, uint32_t pwm_freq_code,
137 uint32_t supply_mv,
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) {
142 return 0U;
143 }
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]));
147}
148
155[[nodiscard]] constexpr uint32_t StealthChopAt1Us(uint32_t fclk_hz) noexcept {
156 if (fclk_hz == 0U) {
157 return 0U;
158 }
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));
161}
162
171[[nodiscard]] constexpr Error StealthGuard(const Config& config, const CurrentPlan& plan) noexcept {
172 if (!(config.stealth.enable && config.stealth.autoscale)) {
173 return Error::Ok;
174 }
175 const uint32_t lower =
176 StealthChopLowerLimitMa(config.chopper.tbl, config.stealth.freq, config.board.supply_mv,
177 config.motor.coil_resistance_mohm);
178 return ((plan.irun >= 8U) && (plan.run_ma >= lower)) ? Error::Ok : Error::Refused;
179}
180
187[[nodiscard]] constexpr Result<uint32_t> VelocityRegFromHz(uint32_t hz, uint32_t fclk_hz) noexcept {
188 if (fclk_hz == 0U) {
190 }
191 const uint64_t reg = (uint64_t{hz} << 24U) / fclk_hz;
192 return (reg > 0xFFFF'FFFFU) ? Result<uint32_t>::Failure(Error::InvalidArgument)
193 : Result<uint32_t>::Success(static_cast<uint32_t>(reg));
194}
195
202[[nodiscard]] constexpr uint32_t HzFromVelocityReg(uint32_t velocity_reg,
203 uint32_t fclk_hz) noexcept {
204 return static_cast<uint32_t>((uint64_t{velocity_reg} * fclk_hz) >> 24U);
205}
206
214[[nodiscard]] constexpr Result<uint32_t> AccelRegFromHzPerS(uint32_t hz_per_s,
215 uint32_t fclk_hz) noexcept {
216 if ((fclk_hz == 0U) || (hz_per_s > 0xFFFFFFU)) {
218 }
219 const uint64_t step1 = (uint64_t{hz_per_s} << 20U) / fclk_hz;
220 return Result<uint32_t>::Success(static_cast<uint32_t>((step1 << 21U) / fclk_hz));
221}
222
229[[nodiscard]] constexpr uint32_t HzPerSFromAccelReg(uint32_t accel_reg, uint32_t fclk_hz) noexcept {
230 const uint64_t q = (uint64_t{accel_reg} * fclk_hz) >> 20U;
231 return static_cast<uint32_t>((q * fclk_hz) >> 21U);
232}
233
239[[nodiscard]] constexpr uint32_t StepTimeFromVelocity(uint32_t velocity_reg) noexcept {
240 if (velocity_reg == 0U) {
241 return 0xFFFFFU;
242 }
243 const uint32_t t = (1U << 24U) / velocity_reg;
244 return (t > 0xFFFFFU) ? 0xFFFFFU : t;
245}
246
252[[nodiscard]] constexpr uint32_t VelocityFromStepTime(uint32_t tstep) noexcept {
253 return (tstep == 0U) ? 0U : ((1U << 24U) / tstep);
254}
255
262[[nodiscard]] constexpr uint32_t RampSteps(uint32_t velocity_reg, uint32_t accel_reg) noexcept {
263 return (accel_reg == 0U)
264 ? 0U
265 : static_cast<uint32_t>((uint64_t{velocity_reg} * velocity_reg) / accel_reg / 256U);
266}
267
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)) {
279 return 0U;
280 }
281 return (uint64_t{velocity_reg} * 256U * 512U * 1'000'000U) / (uint64_t{accel_reg} * fclk_hz);
282}
283
289[[nodiscard]] constexpr uint32_t ToffClocks(uint32_t toff) noexcept {
290 return 24U + (32U * (toff & 15U));
291}
292
299[[nodiscard]] constexpr uint32_t OffTimeNs(uint32_t toff, uint32_t fclk_hz) noexcept {
300 return (fclk_hz == 0U)
301 ? 0U
302 : static_cast<uint32_t>((uint64_t{ToffClocks(toff)} * 1'000'000'000U) / fclk_hz);
303}
304
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);
313}
314
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);
323}
324
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);
333}
334
341[[nodiscard]] constexpr uint32_t DcStepVelocity(uint32_t vdcmin, uint32_t fclk_hz) noexcept {
342 return HzFromVelocityReg(vdcmin, fclk_hz);
343}
344
359[[nodiscard]] constexpr Result<EncoderScale> EncoderScaleFor(uint32_t microsteps, uint32_t counts,
360 bool decimal, bool negative) noexcept {
361 if ((microsteps == 0U) || (counts == 0U) || ((microsteps / counts) > 32'767U)) {
363 }
364 const uint64_t unit = decimal ? 10'000U : 65'536U;
365 const uint64_t scaled = (uint64_t{microsteps} * unit) / counts;
366 EncoderScale s{};
367 s.decimal = decimal;
368 s.integer = static_cast<int16_t>(scaled / unit);
369 s.fraction = static_cast<uint16_t>(scaled % unit);
370 s.negative = negative;
372}
373
382[[nodiscard]] constexpr uint32_t EncConstWord(const EncoderScale& scale) noexcept {
383 if (!scale.negative) {
384 return (static_cast<uint32_t>(static_cast<uint16_t>(scale.integer)) << 16U) | scale.fraction;
385 }
386 if (scale.decimal) {
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) |
391 frac;
392 }
393 const uint32_t magnitude =
394 (static_cast<uint32_t>(static_cast<uint16_t>(scale.integer)) << 16U) | scale.fraction;
395 return 0U - magnitude;
396}
397
398} // namespace tmc5160::units
399
400#endif // TMC5160_UNITS_HPP
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.
@ Ok
The call succeeded.
@ 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