1.. _stepper_api:
2
3Steppers
4########
5
6The stepper driver API provides a set of functions for controlling and configuring stepper drivers.
7
8Configure Stepper Driver
9========================
10
11- Configure **micro-stepping resolution** using :c:func:`stepper_set_micro_step_res`
12  and :c:func:`stepper_get_micro_step_res`.
13- Configure **reference position** in microsteps using :c:func:`stepper_set_reference_position`
14  and :c:func:`stepper_get_actual_position`.
15- Set **step interval** in nanoseconds between steps using :c:func:`stepper_set_microstep_interval`
16- **Enable** the stepper driver using :c:func:`stepper_enable`.
17- **Disable** the stepper driver using :c:func:`stepper_disable`.
18
19Control Stepper
20===============
21
22- **Move by** +/- micro-steps also known as **relative movement** using :c:func:`stepper_move_by`.
23- **Move to** a specific position also known as **absolute movement** using :c:func:`stepper_move_to`.
24- Run continuously with a **constant step interval** in a specific direction until
25  a stop is detected using :c:func:`stepper_run`.
26- **Stop** the stepper using :c:func:`stepper_stop`.
27- Check if the stepper is **moving** using :c:func:`stepper_is_moving`.
28- Register an **event callback** using :c:func:`stepper_set_event_callback`.
29
30Device Tree
31===========
32
33In the context of stepper controllers  device tree provides the initial hardware
34configuration for stepper drivers on a per device level. Each device must specify
35a device tree binding in Zephyr, and ideally, a set of hardware configuration options
36for things such as current settings, ramp parameters and furthermore. These can then
37be used in a boards devicetree to configure a stepper driver to its initial state.
38
39See examples in:
40
41- :dtcompatible:`zephyr,h-bridge-stepper`
42- :dtcompatible:`adi,tmc50xx`
43
44Discord
45=======
46
47Zephyr has a `stepper discord`_ channel for stepper related discussions, which
48is open to all.
49
50.. _stepper-api-reference:
51
52Stepper API Test Suite
53======================
54
55The stepper API test suite provides a set of tests that can be used to verify the functionality of
56stepper drivers.
57
58.. zephyr-app-commands::
59   :zephyr-app: tests/drivers/stepper/stepper_api
60   :board: <board>
61   :west-args: --extra-dtc-overlay <path/to/board.overlay>
62   :goals: build flash
63
64Sample Output
65=============
66
67Below is a snippet of the test output for the tmc50xx stepper driver. Since
68:c:func:`stepper_set_microstep_interval` is not implemented by the driver the corresponding tests
69have been skipped.
70
71.. code-block:: console
72
73   ===================================================================
74   TESTSUITE stepper succeeded
75
76   ------ TESTSUITE SUMMARY START ------
77
78   SUITE PASS - 100.00% [stepper]: pass = 4, fail = 0, skip = 2, total = 6 duration = 0.069 seconds
79    - PASS - [stepper.test_actual_position] duration = 0.016 seconds
80    - PASS - [stepper.test_get_micro_step_res] duration = 0.013 seconds
81    - SKIP - [stepper.test_set_micro_step_interval_invalid_zero] duration = 0.007 seconds
82    - PASS - [stepper.test_set_micro_step_res_incorrect] duration = 0.010 seconds
83    - PASS - [stepper.test_stop] duration = 0.016 seconds
84    - SKIP - [stepper.test_target_position_w_fixed_step_interval] duration = 0.007 seconds
85
86   ------ TESTSUITE SUMMARY END ------
87
88   ===================================================================
89   PROJECT EXECUTION SUCCESSFUL
90
91API Reference
92*************
93
94A common set of functions which should be implemented by all stepper drivers.
95
96.. doxygengroup:: stepper_interface
97
98Stepper controller specific APIs
99********************************
100
101Trinamic
102========
103
104.. doxygengroup:: trinamic_stepper_interface
105
106.. _stepper discord:
107   https://discord.com/channels/720317445772017664/1278263869982375946
108