Group sstep_api¶

Initialise a driver, run its loops and command motion. More...

Public Functions¶

Type	Name
int	sstep_clear_faults (struct sstep * drv) Clear all faults; the driver goes to SSTEP_STATE_DISABLED .
int	sstep_disable (struct sstep * drv) Stop immediately and switch the outputs off (motor coasts, no holding torque).
int	sstep_enable (struct sstep * drv) Enable the outputs and hold the current position with the hold current.
int	sstep_fast_loop (struct sstep * drv, const struct sstep_sample * sample) Fast loop: convert the measurements, run the current controllers, limit the voltage, map it to the legs of the topology and write the PWM.
int	sstep_get_status (const struct sstep * drv, struct sstep_status * status) Read a status snapshot in engineering units.
int	sstep_init (struct sstep * drv, const struct sstep_config * cfg) Validate a configuration and initialise a driver.
int	sstep_move_by (struct sstep * drv, int32_t delta) Start a move relative to the current target.
int	sstep_move_to (struct sstep * drv, int32_t position) Start a move to an absolute position with the trapezoidal profile.
int	sstep_report_fault (struct sstep * drv, uint16_t faults) Report a fault detected by the application (driver fault pin, temperature).
int	sstep_run (struct sstep * drv, int32_t velocity) Run at a constant velocity (accelerating with the configured limits) until another command.
int	sstep_set_current (struct sstep * drv, uint32_t run_ma, uint32_t hold_ma) Change the run and hold currents.
int	sstep_set_motion_limits (struct sstep * drv, uint32_t v_max, uint32_t accel, uint32_t decel) Change the motion limits; they apply from the next sstep_slow_loop() , also to a running command.
int	sstep_set_position (struct sstep * drv, int32_t position) Redefine the current position (homing).
int	sstep_slow_loop (struct sstep * drv) Slow loop: advance the trajectory, update the angle and current references, handle the hold current and report events.
int	sstep_stop (struct sstep * drv) Decelerate to standstill with the configured deceleration and hold.

Detailed Description¶

Execution model. One driver instance (struct sstep) controls one motor. The application calls two functions periodically:

Function	Rate	Context	Work
sstep_fast_loop()	`fast_loop_hz` (PWM rate or an integer fraction of it)	PWM / ADC interrupt	current control, voltage limit, topology mapping, PWM write
sstep_slow_loop()	`slow_loop_hz` (typically 1 kHz)	main loop or a timer task	trajectory, microstep angle, hold current, fault handling

All other functions are called from the same context as sstep_slow_loop(). The library never reads a clock, never blocks, allocates no memory and has no global state: time is given by the configured loop rates.

Hardware access is done only through the callbacks in sstep_callbacks, given once to sstep_init(). Measurements are passed to sstep_fast_loop() as raw ADC counts.

Initialization. Every function except sstep_init() returns SSTEP_ERR_STATE for an instance without a successful sstep_init() (a zeroed instance, or one whose last sstep_init() failed in the derivation of the constants), and touches no hardware. sstep_fast_loop() checks this only when SSTEP_CFG_ARG_CHECKS is 1.

Public Functions Documentation¶

function sstep_clear_faults¶

Clear all faults; the driver goes to SSTEP_STATE_DISABLED .

int sstep_clear_faults (
    struct sstep * drv
)

Parameters:

drv Driver instance.

Return value:

SSTEP_OK

function sstep_disable¶

Stop immediately and switch the outputs off (motor coasts, no holding torque).

int sstep_disable (
    struct sstep * drv
)

Parameters:

drv Driver instance.

Return value:

SSTEP_OK

function sstep_enable¶

Enable the outputs and hold the current position with the hold current.

int sstep_enable (
    struct sstep * drv
)

Parameters:

drv Driver instance.

Return value:

SSTEP_OK (faulted).

function sstep_fast_loop¶

Fast loop: convert the measurements, run the current controllers, limit the voltage, map it to the legs of the topology and write the PWM.

int sstep_fast_loop (
    struct sstep * drv,
    const struct sstep_sample * sample
)

Call from the PWM/ADC interrupt at fast_loop_hz. Bounded execution time, no loops over data.

Parameters:

drv Driver instance.
sample Measurements of this period.

Return value:

SSTEP_OK (only when SSTEP_CFG_ARG_CHECKS is 1).

function sstep_get_status¶

Read a status snapshot in engineering units.

int sstep_get_status (
    const struct sstep * drv,
    struct sstep_status * status
)

Parameters:

drv Driver instance.
status Filled on success.

Return value:

SSTEP_OK

function sstep_init¶

Validate a configuration and initialise a driver.

int sstep_init (
    struct sstep * drv,
    const struct sstep_config * cfg
)

Outputs stay disabled. Derives the per-unit bases, the PI gains (Kp = L * wc, Ki = R * wc) and the trajectory constants; no floating point is used with the fixed point backend.

Parameters:

drv Driver instance.
cfg Configuration; copied.

Return value:

SSTEP_OK Success, state SSTEP_STATE_DISABLED.
SSTEP_ERR_PARAM NULL pointer, missing required callback or a field out of range.
SSTEP_ERR_CONFIG Inconsistent fields (for example i_run_ma > i_trip_ma).
SSTEP_ERR_UNSUPPORTED Topology not compiled in.

function sstep_move_by¶

Start a move relative to the current target.

int sstep_move_by (
    struct sstep * drv,
    int32_t delta
)

Parameters:

drv Driver instance.
delta Distance [microsteps].

Return value:

SSTEP_OK (also when the target overflows), SSTEP_ERR_STATE.

function sstep_move_to¶

Start a move to an absolute position with the trapezoidal profile.

int sstep_move_to (
    struct sstep * drv,
    int32_t position
)

Replaces the current move; the change is smooth (no velocity step).

Parameters:

drv Driver instance.
position Target [microsteps].

Return value:

SSTEP_OK (disabled or faulted).

function sstep_report_fault¶

Report a fault detected by the application (driver fault pin, temperature).

int sstep_report_fault (
    struct sstep * drv,
    uint16_t faults
)

Switches the outputs off. May be called from an interrupt.

Parameters:

drv Driver instance.
faults Flags to raise, typically SSTEP_FAULT_EXTERNAL.

Return value:

SSTEP_OK

function sstep_run¶

Run at a constant velocity (accelerating with the configured limits) until another command.

int sstep_run (
    struct sstep * drv,
    int32_t velocity
)

Parameters:

drv Driver instance.
velocity Signed velocity [microsteps/s], |velocity| <= v_max.

Return value:

SSTEP_OK

function sstep_set_current¶

Change the run and hold currents.

int sstep_set_current (
    struct sstep * drv,
    uint32_t run_ma,
    uint32_t hold_ma
)

Parameters:

drv Driver instance.
run_ma Peak phase current while moving [mA].
hold_ma Peak phase current at standstill [mA], <= run_ma.

Return value:

SSTEP_OK (above the trip level).

function sstep_set_motion_limits¶

Change the motion limits; they apply from the next sstep_slow_loop() , also to a running command.

int sstep_set_motion_limits (
    struct sstep * drv,
    uint32_t v_max,
    uint32_t accel,
    uint32_t decel
)

Parameters:

drv Driver instance.
v_max Maximum velocity [microsteps/s].
accel Acceleration [microsteps/s^2].
decel Deceleration [microsteps/s^2]; 0 = same as accel.

Return value:

SSTEP_OK

function sstep_set_position¶

Redefine the current position (homing).

int sstep_set_position (
    struct sstep * drv,
    int32_t position
)

Only at standstill.

Parameters:

drv Driver instance.
position New value of the current position [microsteps].

Return value:

SSTEP_OK (moving).

function sstep_slow_loop¶

Slow loop: advance the trajectory, update the angle and current references, handle the hold current and report events.

int sstep_slow_loop (
    struct sstep * drv
)

Call at slow_loop_hz.

Parameters:

drv Driver instance.

Return value:

SSTEP_OK

function sstep_stop¶

Decelerate to standstill with the configured deceleration and hold.

int sstep_stop (
    struct sstep * drv
)

Parameters:

drv Driver instance.

Return value:

SSTEP_OK