Protection¶
Stepper-C switches the outputs off in the context that detects a problem, within the fast loop period in which the sample shows it. This page lists every protection of the library, what it detects, when it acts and how the application sees it, and what the firmware around the library has to add.
Overview¶
| Protection | Detects | Acts | Reaction | Reported as |
|---|---|---|---|---|
| Phase overcurrent | \(\lvert i_A \rvert\) or \(\lvert i_B \rvert\) above i_trip_ma |
Every fast loop period: current drive, voltage drive with i_trip_voltage_drive, during the self-test |
Outputs off in the same period, fault latched | SSTEP_FAULT_OVERCURRENT (with SSTEP_FAULT_STALL while the stall detector counts) |
| Shared-leg overcurrent | \(\lvert i_A + i_B \rvert\) above i_trip_ma: the current of the common leg |
As above, SSTEP_TOPOLOGY_SHARED_LEG only |
As above | SSTEP_FAULT_OVERCURRENT |
| Overvoltage, undervoltage | Bus voltage above vbus_max_mv or below vbus_min_mv |
Every fast loop period with the outputs on | As above | SSTEP_FAULT_OVERVOLTAGE, SSTEP_FAULT_UNDERVOLTAGE |
| Bus voltage at the start | The last bus voltage sample outside the trip limits | sstep_enable(), sstep_selftest() |
The call is refused, nothing is switched on, nothing latched | SSTEP_ERR_VBUS |
| Self-test | A switch that conducts, an open phase, a short, a current of the wrong sign, a phase on the wrong legs | sstep_selftest(), before the first enable |
Outputs off, fault latched | SSTEP_FAULT_SELFTEST, result in sstep_status::selftest |
| Stall detection | The rotor does not follow the commanded angle | Slow loop, after stall_time_ms |
Outputs off, fault latched | SSTEP_FAULT_STALL |
| Callback errors | pwm_write() or output_enable() returned an error |
Where the callback is called | Outputs off, fault latched | SSTEP_FAULT_HAL |
| External faults | Anything the application detects: a driver fault pin, the temperature, a hardware comparator | sstep_report_fault(), any context, also an interrupt |
Outputs off, fault latched | The flags passed, typically SSTEP_FAULT_EXTERNAL |
Two configuration options keep the trips from acting on false data or from being caused by the drive itself:
- Sampling window (
sample_window_ticks): no switching edge falls into the conversions of low-side shunts, so a single corrupted sample cannot trip the overcurrent or the undervoltage protection (Sampling window). - Current slew (
i_slew_ma_per_ms): the current rises aftersstep_enable()instead of stepping, so a current-limited supply does not collapse (Current slew).
Fault handling¶
A fault calls output_enable(false) in the detecting context, sets the flags in faults,
enters SSTEP_STATE_FAULT and calls on_fault() with the new flags, all before the function
that detected it returns. The outputs then stay off:
sstep_enable(), the motion commands andsstep_selftest()answerSSTEP_ERR_STATE;sstep_disable()keeps the fault;sstep_clear_faults()clears the flags and returns toSSTEP_STATE_DISABLED; the application decides when that is safe (after a fault of the power stage, usually only after a person has looked at it).
on_fault() may run in the fast loop interrupt: keep it short and do not call the library
from it. sstep_get_status() reports the flags, the state and the last measurements.
Overcurrent¶
The trip level i_trip_ma is converted once into ADC counts from adc_i_zero; the fast
loop compares the raw samples, before any filtering, in every period:
with \(d_x\) the sample minus adc_i_zero and \(n_\mathrm{trip}\) = i_trip_ma ·
adc_i_span / i_full_scale_ma. The common leg of the shared-leg topology carries
\(-(i_A + i_B)\), up to \(\sqrt{2}\) times the phase amplitude, so it reaches the switch rating
first.
In SSTEP_DRIVE_VOLTAGE the phase currents may not be measured at all, so the trips act
only when i_trip_voltage_drive says they are. During sstep_selftest() they always act.
The response time is one fast loop period at best. A short circuit through a switch rises in microseconds: protect the switches in hardware as well (see What the application adds).
Bus voltage¶
vbus_min_mv and vbus_max_mv trip in every fast loop period while the outputs are on.
Before the outputs are switched on, sstep_enable() and sstep_selftest() check the last
sample against the same limits and answer SSTEP_ERR_VBUS without latching a fault: a supply
that is not yet up is not a fault of the drive, and the call can be repeated once it is.
Without any sample yet sstep_enable() does not check (the first fast loop period trips),
sstep_selftest() refuses.
Self-test¶
sstep_selftest(drv, i_test_ma) tests the power stage and the wiring before the first
enable, with the outputs on and the current controller off. It is compiled in by default;
SSTEP_CFG_SELFTEST = 0 removes it (1.3 KiB of flash and 48 B per instance on Cortex-M4)
and the call returns SSTEP_ERR_UNSUPPORTED. The fast loop runs it, one step
per period:
- All legs low, 2 ms. No phase may carry more than a quarter of the test current;
otherwise a switch conducts with its gate off (
SSTEP_SELFTEST_LEAK). - Phase A. The legs of phase B and the return leg of phase A stay low; the duty cycle of
the driving leg of phase A rises over 20 ms from 0 to \(D_\mathrm{max}\) until the current
reaches
i_test_maand is held; then all legs go low until the currents have died out. - Phase B, the same.
The energised phase pulls the rotor to its nearest full step, at most one full step, and the rotor swings into it. While it moves, it induces currents in both phases: in the idle phase, which both its legs short, and on top of the test current. A wrong wiring or a short gives a current that stays; a rotor comes to rest. So each check waits for a rotor at rest:
| Check | Passes when | Fails after |
|---|---|---|
| Hold (wiring) | The other phase stayed below half the own current for 2 ms in a row | 100 ms without that: SSTEP_SELFTEST_WRONG_PHASE |
| Decay (between and after the phases) | Both currents stayed below a quarter of the test current for 5 ms in a row | 100 ms without that: SSTEP_SELFTEST_LEAK |
| Twice the test current | A swinging rotor crosses zero every half swing | Above it without a break for 100 ms: SSTEP_SELFTEST_SHORT |
With a rotor at rest the conditions hold from the start, and the hold takes 2 ms and the
decay 5 ms. The overcurrent trip (i_trip_ma) acts throughout the test, so a hard short
switches the outputs off at once, whatever the checks wait for.
The voltage is ramped and not set from the resistance, because the dead time takes a bus
fraction of \(2\, t_\mathrm{dead} f_\mathrm{PWM}\) from a driving leg (0.58 V at 12 V,
1.2 µs and 20 kHz) — as much as the 0.96 V that 0.6 A needs through 1.6 Ω. With
\(V_t = I_t R\) (i_test_ma · r_mohm), the bus voltage \(V_\mathrm{bus}\) of the last sample
and the period \(P\) in compare ticks:
dead_time_ns and pwm_freq_hz enter here; with 0 the loss term is 0.
| Result | Condition | Likely cause |
|---|---|---|
SSTEP_SELFTEST_PASS |
Both phases reached the test current with the expected sign, the other phase stayed below half of it | — |
SSTEP_SELFTEST_LEAK |
Current above a quarter of the test current with every leg low, before the first phase or for 100 ms between the phases | A high-side switch conducts |
SSTEP_SELFTEST_OPEN |
\(D_\mathrm{max}\) reached without the current | Phase wire loose, motor not connected, a leg or its gate driver dead |
SSTEP_SELFTEST_SHORT |
Current above twice the test current for 100 ms, reached below \(D_\mathrm{short}\) (resistance below a quarter of r_mohm), or an overcurrent trip |
Phases shorted together or to a supply rail |
SSTEP_SELFTEST_POLARITY |
The test current with the wrong sign | Sign of adc_i_span |
SSTEP_SELFTEST_WRONG_PHASE |
The other phase carried half the own current or more for 100 ms | A phase connected to the wrong legs |
SSTEP_SELFTEST_ABORTED |
A bus voltage trip or a callback error ended the test | Supply, see the fault flags |
SSTEP_SELFTEST_NONE |
Not run, or stopped by sstep_disable() |
— |
sstep_status also reports the tested phase (selftest_phase), its current at the end
(selftest_i_ma) and the compare value (selftest_duty). A failure raises
SSTEP_FAULT_SELFTEST; the result stays readable after sstep_clear_faults().
The test takes 42 ms on the motor model of the tests (17HS19-2004S1, 12 V, free rotor,
both topologies), and 39 to 55 ms with the rotor a full step away from phase A at 12 V and
24 V and up to 50 times the rotor inertia. A rotor that keeps moving can stretch it to about
440 ms (2 + 2 × (20 + 100 + 100) ms) before it fails. The end is reported by
sstep_slow_loop() with SSTEP_EVENT_SELFTEST_DONE.
The rotor must be free to settle
The energised phase pulls the rotor to its nearest full step (at most one full step) and back when the motor is enabled; the checks wait until it is at rest. A rotor turned by an external torque for longer, such as a joint that falls, keeps inducing currents and fails the test: support such a load for the first enable.
A typical start, in the slow loop context of a bare-metal main loop:
struct sstep_status st = {0};
if (sstep_selftest(&motor, 600U) == SSTEP_OK) /* 30 % of the 2 A rated current */
{
do
{
if (board_tick_1ms())
{
(void)sstep_slow_loop(&motor);
}
(void)sstep_get_status(&motor, &st);
} while (st.selftest == SSTEP_SELFTEST_RUNNING);
}
if (st.selftest == SSTEP_SELFTEST_PASS)
{
(void)sstep_enable(&motor);
}
What the application adds¶
The library sees one sample per fast loop period and the callbacks. Protections that need the hardware, faster reaction or information outside the samples belong to the firmware:
| Protection | Why it is outside the library |
|---|---|
| Hardware overcurrent (comparator into the break input of the PWM timer) | Acts in microseconds without software; a short through a switch rises faster than one fast loop period |
Plausibility of adc_i_zero (offset calibration with the outputs off) |
The calibration is done by the application before sstep_init() |
| Current of a third leg, if the board measures it | struct sstep_sample has two currents; the shared-leg trip uses \(i_A + i_B\) |
| Fast loop overrun | Only the timer or the ADC interrupt sees that the next sample came before the loop ended |
| Temperature of the stage and the motor | Report it with sstep_report_fault(SSTEP_FAULT_EXTERNAL) |
| Gate driver fault pins, watchdog | Board and system specific |
Bring-up¶
- With the outputs off, check
adc_i_zeroand the bus voltage reading (Bring-up checklist). - Set
sample_window_ticksfor low-side shunts and a moderatei_slew_ma_per_ms. - Run
sstep_selftest()at about 30 % of the rated current at a low bus voltage with a current-limited supply; a failure names the wiring or the switch to look at. - Lower
i_trip_maandvbus_max_mvonce to see each trip and the fault path work.