Skip to content

Commit 8395626

Browse files
jilaypandyanashif
jilaypandya
authored and
nashif
committed
drivers: stepper: split stepper api
- split stepper api into stepper and stepper_drv api - stepper api now comprises only of motion control apis - stepper_drv api comprises of apis for configuring stepper drivers - add documentation about stepper and stepper_drv api - move stepper.rst in a dedicated stepper folder - add information about stepper_drv api and relevant functions in stepper documentation. - drop motion control functions from all the stepper_drv drivers - create a common a library for controlling stepper motors by toggling gpios via h-bridge or step-dir stepper_drivers - tmc5xxx devices are a combination of motion controller and stepper driver devices. tmc5xxx devices need to be modelled as mfds in order to address the split in stepper driver subsystem Signed-off-by: Jilay Pandya <[email protected]>
1 parent c4a4d8a commit 8395626

File tree

101 files changed

+4144
-3302
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

101 files changed

+4144
-3302
lines changed

‎MAINTAINERS.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2450,7 +2450,7 @@ Documentation Infrastructure:
24502450
- include/zephyr/drivers/stepper/
24512451
- include/zephyr/drivers/stepper.h
24522452
- dts/bindings/stepper/
2453-
- doc/hardware/peripherals/stepper.rst
2453+
- doc/hardware/peripherals/stepper/
24542454
- samples/drivers/stepper/
24552455
- tests/drivers/build_all/stepper/
24562456
- tests/drivers/stepper/

‎doc/hardware/peripherals/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ Peripherals
5858
sensor/index.rst
5959
sent.rst
6060
spi.rst
61-
stepper.rst
61+
stepper/index.rst
6262
smbus.rst
6363
uart.rst
6464
usbc_vbus.rst

doc/hardware/peripherals/stepper.rst renamed to doc/hardware/peripherals/stepper/index.rst

Lines changed: 35 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,27 @@
33
Steppers
44
########
55

6-
The stepper driver API provides a set of functions for controlling and configuring stepper drivers.
6+
The stepper driver subsystem consists of two device driver APIs:
77

8-
Configure Stepper Driver
9-
========================
8+
Stepper-DRV API
9+
***************
10+
11+
The stepper driver API provides a common interface for stepper drivers.
12+
13+
- Configure **micro-stepping resolution** using :c:func:`stepper_drv_set_micro_step_res`
14+
and :c:func:`stepper_drv_get_micro_step_res`.
15+
- **Enable** the stepper driver using :c:func:`stepper_drv_enable`.
16+
- **Disable** the stepper driver using :c:func:`stepper_drv_disable`.
17+
- Register an **event callback** using :c:func:`stepper_drv_set_event_cb`.
18+
19+
Stepper API
20+
***********
21+
22+
The stepper API provides a common interface for stepper controllers.
1023

11-
- Configure **micro-stepping resolution** using :c:func:`stepper_set_micro_step_res`
12-
and :c:func:`stepper_get_micro_step_res`.
1324
- Configure **reference position** in microsteps using :c:func:`stepper_set_reference_position`
1425
and :c:func:`stepper_get_actual_position`.
1526
- 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-
19-
Control Stepper
20-
===============
21-
2227
- **Move by** +/- micro-steps also known as **relative movement** using :c:func:`stepper_move_by`.
2328
- **Move to** a specific position also known as **absolute movement** using :c:func:`stepper_move_to`.
2429
- Run continuously with a **constant step interval** in a specific direction until
@@ -27,30 +32,30 @@ Control Stepper
2732
- Check if the stepper is **moving** using :c:func:`stepper_is_moving`.
2833
- Register an **event callback** using :c:func:`stepper_set_event_callback`.
2934

35+
.. _stepper-device-tree:
36+
3037
Device Tree
31-
===========
38+
***********
3239

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

39-
See examples in:
46+
Driver Composition Scenarios
47+
============================
4048

41-
- :dtcompatible:`zephyr,h-bridge-stepper`
42-
- :dtcompatible:`adi,tmc50xx`
49+
Below are two typical scenarios:
4350

44-
Discord
45-
=======
51+
.. toctree::
52+
:maxdepth: 1
4653

47-
Zephyr has a `stepper discord`_ channel for stepper related discussions, which
48-
is open to all.
49-
50-
.. _stepper-api-reference:
54+
integrated_controller_driver.rst
55+
individual_controller_driver.rst
5156

5257
Stepper API Test Suite
53-
======================
58+
**********************
5459

5560
The stepper API test suite provides a set of tests that can be used to verify the functionality of
5661
stepper drivers.
@@ -91,8 +96,16 @@ have been skipped.
9196
API Reference
9297
*************
9398

99+
.. _stepper-drv-api-reference:
100+
94101
A common set of functions which should be implemented by all stepper drivers.
95102

103+
.. doxygengroup:: stepper_drv_interface
104+
105+
.. _stepper-api-reference:
106+
107+
A common set of functions which should be implemented by all stepper controllers.
108+
96109
.. doxygengroup:: stepper_interface
97110

98111
Stepper controller specific APIs

‎doc/hardware/peripherals/stepper/individual_controller_driver.rst‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. _stepper-individual-controller-driver:
2+
3+
Individual Stepper Motion Controller and Driver
4+
###############################################
5+
6+
A motion control driver implements :c:group:`stepper_interface` API, for instance,
7+
:dtcompatible:`zephyr,gpio-step-dir-stepper` and a hardware driver implements :c:group:`stepper_drv_interface`
8+
API, for instance, :dtcompatible:`adi,tmc2209`.
9+
10+
Following is an example of a device tree configuration for a stepper driver with a dedicated stepper motion
11+
controller:
12+
13+
.. code-block:: dts
14+
15+
/ {
16+
aliases {
17+
stepper_drv = &tmc2209
18+
stepper = &step_dir_motion_control;
19+
};
20+
21+
/* DEVICE_API: stepper_drv api */
22+
tmc2209: tmc2209 {
23+
compatible = "adi,tmc2209";
24+
enable-gpios = <&gpioa 6 GPIO_ACTIVE_HIGH>;
25+
m0-gpios = <&gpiob 0 GPIO_ACTIVE_HIGH>;
26+
m1-gpios = <&gpioa 7 GPIO_ACTIVE_HIGH>;
27+
};
28+
29+
/* DEVICE_API: stepper api */
30+
step_dir_motion_control: step_dir_motion_control {
31+
compatible = "zephyr,gpio-step-dir-stepper";
32+
step-gpios = <&gpioa 9 GPIO_ACTIVE_HIGH>;
33+
dir-gpios = <&gpioc 7 GPIO_ACTIVE_HIGH>;
34+
invert-direction;
35+
stepper-drv = <&tmc2209>;
36+
};
37+
};
38+
39+
Following the aforementioned configurations, the stepper driver subsystem can be used in the application code
40+
as follows:
41+
42+
.. code-block:: c
43+
44+
static const struct device *stepper = DEVICE_DT_GET(DT_ALIAS(stepper));
45+
static const struct device *stepper_drv = DEVICE_DT_GET(DT_ALIAS(stepper_drv));
46+
...
47+
stepper_move_to(stepper, 200);
48+
stepper_stop(stepper);
49+
stepper_drv_disable(stepper_drv);

‎doc/hardware/peripherals/stepper/integrated_controller_driver.rst‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
.. _stepper-integrated-controller-driver:
2+
3+
Integrated Stepper Motion Control and Driver
4+
############################################
5+
6+
Devices which comprise of both motion controller and a stepper driver in a single IC. These devices
7+
have to be modelled as multi-functional-device in device tree, implementing both :c:group:`stepper_interface`
8+
and :c:group:`stepper_drv_interface` APIs. An example of such a device is :dtcompatible:`adi,tmc50xx`.
9+
:c:group:`stepper_interface` API is implemented by :dtcompatible:`adi,tmc50xx-stepper` and
10+
:c:group:`stepper_drv_interface` API is implemented by :dtcompatible:`adi,tmc50xx-stepper-drv`.
11+
12+
.. code-block:: dts
13+
14+
/ {
15+
aliases {
16+
x_axis_stepper_motor = &tmc50xx_0_motion_controller;
17+
y_axis_stepper_motor = &tmc50xx_1_motion_controller;
18+
x_axis_stepper_driver = &tmc50xx_0_stepper_driver;
19+
y_axis_stepper_driver = &tmc50xx_1_stepper_driver;
20+
};
21+
};
22+
23+
&spi0 {
24+
/* SPI bus options here, not shown */
25+
26+
/* Dual controller/driver for up to two 2-phase bipolar stepper motors */
27+
tmc50xx: tmc50xx@0 {
28+
compatible = "adi,tmc50xx";
29+
reg = <0>;
30+
spi-max-frequency = <DT_FREQ_M(8)>; /* Maximum SPI bus frequency */
31+
32+
poscmp-enable; test-mode; lock-gconf; /* ADI TMC Global configuration flags */
33+
clock-frequency = <DT_FREQ_M(16)>; /* Internal/External Clock frequency */
34+
35+
/* DEVICE_API: stepper_drv api */
36+
tmc50xx_0_stepper_driver: tmc50xx_0_stepper_driver {
37+
idx = <0>;
38+
compatible = "adi,tmc50xx-stepper-drv";
39+
micro-step-res = <256>;
40+
/* ADI TMC stallguard settings specific to TMC50XX */
41+
stallguard2-threshold=<30>;
42+
};
43+
44+
/* DEVICE_API: stepper api */
45+
tmc50xx_0_motion_controller: tmc50xx_0_motion_controller {
46+
idx = <0>;
47+
compatible = "adi,tmc50xx-stepper";
48+
...
49+
vmax = <900000>;
50+
amax = <50000>;
51+
...
52+
activate-stallguard2;
53+
...
54+
};
55+
56+
/* DEVICE_API: stepper_drv api */
57+
tmc50xx_1_stepper_driver: tmc50xx_1_stepper_driver {
58+
idx = <1>;
59+
compatible = "adi,tmc50xx-stepper-drv";
60+
micro-step-res = <256>;
61+
/* ADI TMC stallguard settings specific to TMC50XX */
62+
stallguard2-threshold=<30>;
63+
};
64+
65+
/* DEVICE_API: stepper api */
66+
tmc50xx_1_motion_controller: tmc50xx_1_motion_controller {
67+
idx = <1>;
68+
compatible = "adi,tmc50xx-stepper";
69+
...
70+
vstart = <1000>;
71+
...
72+
stallguard-threshold-velocity=<200000>;
73+
};
74+
};
75+
};
76+
77+
Following the aforementioned configurations, the stepper driver subsystem can be used in the application code
78+
as follows:
79+
80+
.. code-block:: c
81+
82+
static const struct device *x_stepper = DEVICE_DT_GET(DT_ALIAS(x_axis_stepper_motor));
83+
static const struct device *x_stepper_drv = DEVICE_DT_GET(DT_ALIAS(x_axis_stepper_driver));
84+
static const struct device *y_stepper = DEVICE_DT_GET(DT_ALIAS(y_axis_stepper_motor));
85+
static const struct device *y_stepper_drv = DEVICE_DT_GET(DT_ALIAS(y_axis_stepper_driver));
86+
...
87+
stepper_move_to(x_stepper, 200);
88+
stepper_stop(x_stepper);
89+
stepper_drv_disable(x_stepper_drv);
90+
stepper_drv_disable(y_stepper_drv);

‎drivers/stepper/CMakeLists.txt‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,12 @@ zephyr_syscall_header(${ZEPHYR_BASE}/include/zephyr/drivers/stepper.h)
77
add_subdirectory(adi_tmc)
88
add_subdirectory(allegro)
99
add_subdirectory(gpio_stepper)
10+
add_subdirectory(step_dir)
1011
add_subdirectory(ti)
1112
# zephyr-keep-sorted-stop
1213

1314
zephyr_library()
1415
zephyr_library_property(ALLOW_EMPTY TRUE)
1516

16-
# zephyr-keep-sorted-start
1717
zephyr_library_sources_ifdef(CONFIG_FAKE_STEPPER fake_stepper_controller.c)
1818
zephyr_library_sources_ifdef(CONFIG_STEPPER_SHELL stepper_shell.c)
19-
# zephyr-keep-sorted-stop

‎drivers/stepper/Kconfig‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ rsource "Kconfig.fake"
3131
rsource "adi_tmc/Kconfig"
3232
rsource "allegro/Kconfig"
3333
rsource "gpio_stepper/Kconfig"
34+
rsource "step_dir/Kconfig"
3435
rsource "ti/Kconfig"
3536
# zephyr-keep-sorted-stop
3637

‎drivers/stepper/Kconfig.fake‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
# SPDX-License-Identifier: Apache-2.0
55

66
config FAKE_STEPPER
7-
bool "Fake stepper driver"
7+
bool "Fake stepper and stepper_drv driver"
88
default y
9-
depends on DT_HAS_ZEPHYR_FAKE_STEPPER_ENABLED
9+
depends on DT_HAS_ZEPHYR_FAKE_STEPPER_DRV_ENABLED || DT_HAS_ZEPHYR_FAKE_STEPPER_ENABLED
1010
help
11-
Enable support for the FFF-based fake stepper driver.
11+
Enable support for the FFF-based fake stepper controller & driver.

‎drivers/stepper/adi_tmc/Kconfig.tmc_rampgen_template‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33

44
config STEPPER_ADI_$(module)_RAMPSTAT_POLL_INTERVAL_IN_MSEC
55
int "$(module-str) poll ramp status interval in ms"
6-
depends on !$(dt_compat_any_has_prop,$(DT_COMPAT_ADI_$(module)),diag0-gpios)
76
default 100
87
help
98
When DIAG0 pin is not available, the driver automatically falls back to

0 commit comments

Comments
 (0)