.. _stepper_api:

Steppers ########

The stepper driver subsystem consists of two device driver APIs:

Stepper API

The stepper driver API provides a common interface for stepper drivers.

Configure micro-stepping resolution using :c:func:stepper_set_micro_step_res and :c:func:stepper_get_micro_step_res.
Enable the stepper driver using :c:func:stepper_enable.
Disable the stepper driver using :c:func:stepper_disable.
Register an event callback using :c:func:stepper_set_event_cb.

Stepper Motion Controller API

The stepper motion controller API provides a common interface for stepper motion controllers.

Configure reference position in microsteps using :c:func:stepper_ctrl_set_reference_position and :c:func:stepper_ctrl_get_actual_position.
Set step interval in nanoseconds between steps using :c:func:stepper_ctrl_set_microstep_interval
Move by +/- micro-steps also known as relative movement using :c:func:stepper_ctrl_move_by.
Move to a specific position also known as absolute movement using :c:func:stepper_ctrl_move_to.
Run continuously with a constant step interval in a specific direction until a stop is detected using :c:func:stepper_ctrl_run.
Stop the stepper using :c:func:stepper_ctrl_stop.
Check if the stepper is moving using :c:func:stepper_ctrl_is_moving.
Register an event callback using :c:func:stepper_ctrl_set_event_cb.

.. _stepper-device-tree:

Device Tree

In the context of stepper motion controllers, devicetree provides the initial hardware configuration for stepper drivers on a per device level. Each device must specify a device tree binding in Zephyr, and ideally, a set of hardware configuration options for things such as current settings, ramp parameters and furthermore. These can then be used in a boards devicetree to configure a stepper driver to its initial state.

Driver Composition Scenarios

Below are two typical scenarios:

.. toctree:: :maxdepth: 1

integrated_controller_driver.rst individual_controller_driver.rst

Stepper Motion Controller API Test Suite

The stepper motion controller API test suite provides a set of tests that can be used to verify the functionality of stepper motion controllers.

.. zephyr-app-commands:: :zephyr-app: tests/drivers/stepper/stepper_ctrl :board: <board> :west-args: --extra-dtc-overlay <path/to/board.overlay> :goals: build flash

Sample Output

Below is a snippet of the test output for the h-bridge-stepper-ctrl.

.. code-block:: console

=================================================================== TESTSUITE stepper succeeded

------ TESTSUITE SUMMARY START ------

SUITE PASS - 100.00% [stepper_ctrl]: pass = 10, fail = 0, skip = 0, total = 10 duration = 6.869 seconds - PASS - [stepper_ctrl.test_actual_position] duration = 0.001 seconds - PASS - [stepper_ctrl.test_move_by_negative_step_count] duration = 2.207 seconds - PASS - [stepper_ctrl.test_move_by_positive_step_count] duration = 2.202 seconds - PASS - [stepper_ctrl.test_move_to_negative_step_count] duration = 1.106 seconds - PASS - [stepper_ctrl.test_move_to_positive_step_count] duration = 1.102 seconds - PASS - [stepper_ctrl.test_move_zero_steps] duration = 0.006 seconds - PASS - [stepper_ctrl.test_run_negative_direction] duration = 0.115 seconds - PASS - [stepper_ctrl.test_run_positive_direction] duration = 0.124 seconds - PASS - [stepper_ctrl.test_set_micro_step_interval_invalid_zero] duration = 0.002 seconds - PASS - [stepper_ctrl.test_stop] duration = 0.004 seconds

------ TESTSUITE SUMMARY END ------

=================================================================== PROJECT EXECUTION SUCCESSFUL

API Reference

.. _stepper-driver-api-reference:

A common set of functions which should be implemented by all stepper drivers.

.. doxygengroup:: stepper_hw_driver

.. _stepper-ctrl-api-reference:

A common set of functions which should be implemented by all stepper motion controllers.

.. doxygengroup:: stepper_ctrl

Stepper motion controller specific APIs

Trinamic

.. doxygengroup:: trinamic_stepper_ctrl

.. _stepper discord: https://discord.com/channels/720317445772017664/1278263869982375946