drivers: stepper: introduce stepper_drv api to facilitate implementing motion controllers as device drivers #91979

jilaypandya · 2025-06-21T22:30:40Z

Update 06.07.25

Commit 1: Introduces stepper_drv api for stepper driver drivers
Commit 2: Split stepper_drv related functions from stepper_api and introduces stepper_idx in all motion_control functions
commit 3: Add stepper index selection functionality in shell
commit 4: add documentation about stepper_drv api

This PR aims to facilitate implementation of stepper motion controllers as device drivers. Hence the low-level step-dir drivers now shall implement a stepper_drv api, effectively also signifying what the IC actually supports i.e enable, step/dir and in some cases fault detection

Stepper API as all of us know it, implements motion control functions
Stepper Drv API is responsible for the configuration of stepper_drv drivers.

Drivers	Stepper Driver (stepper_drv API)	Stepper Motion Control Driver ( stepper API)
adi,tmc22xx	x
allegro,a4979	x
ti,drv84xx	x
zephyr,gpio-stepper(h-bridge based driver)	x
adi,tmc50xx	x	x
adi,tmc51xx	x	x
zephyr,stepper-motion-controller (CPU Based)		x

Stepper Driver Subsystem shall now have two APIs

	stepper driver api (stepper_drv)	stepper motion control api (stepper)
enable / disable	impl
microstep_resolution	impl
step/dir	impl
move_to/move_by/run/stop		impl
set_reference_position		impl
*is_moving		impl
get_actual_position		impl
set_reference_position		impl

Code Snippet:
Before

/ {
     aliases {
        x_axis_stepper = &tmc50xx_stepper_x_axis@0;
        y_axis_stepper =  &tmc50xx_stepper_y_axis@1;
     };
};

spi {
    
     tmc50xx_motion_controller {
        compatible = "adi,tmc50xx"

        /* device_api: stepper api */
        tmc50xx_stepper_x_axis@0 {
        };

        /* device_api: stepper api */
        tmc50xx_stepper_y_axis@1 {
        };
    };
};

------------------------------------------------------------------------


stepper_move_to(x_axis_stepper, 200);
stepper_stop(y_axis_stepper);
stepper_disable(x_axis_stepper);
stepper_disable(y_axis_stepper);

After

/ {
     aliases {
        x_y_stepper_motion_controller = &tmc50xx_motion_controller;
        x_axis_stepper_driver = &tmc50xx_stepper_driver_x_axis@0;
        y_axis_stepper_driver =  &tmc50xx_stepper_driver_y_axis@1;
     };
};

spi {
    
      /* device_api: stepper api */
     tmc50xx_motion_controller {
        compatible = "adi,tmc50xx"

        /* device_api: stepper_drv api */
        tmc50xx_stepper_driver_x_axis@0 {
        };

        /* device_api: stepper_drv api */
        tmc50xx_stepper_driver_y_axis@1 {
        };
    };
};

------------------------------------------------------------------------

CONFIG_X_AXIS  0
CONFIG_Y_AXIS  1

stepper_move_to(x_y_stepper_motion_controller, CONFIG_X_AXIS, 200);
stepper_stop(x_y_stepper_motion_controller, CONFIG_Y_AXIS);
stepper_drv_disable(x_axis_stepper_driver);
stepper_drv_disable(y_axis_stepper_driver);

Stepper Implementation Comparison

Aspect	Before Implementation	After Implementation with stepper_drv API
Alias Structure	Direct references to individual steppers: - `x_axis_stepper` - `y_axis_stepper`	Hierarchical approach: - Motion controller: `x_y_stepper_motion_controller` - Driver references: `x_axis_stepper_driver`, `y_axis_stepper_driver`
Device Tree	Individual stepper motors as direct API devices: `tmc50xx_stepper_x_axis@0 {/* device_api: stepper api /}` `tmc50xx_stepper_y_axis@1 {/ device_api: stepper api */}`	Separation of concerns: - Motion controller with stepper API: `tmc50xx_motion_controller {/* device_api: stepper api /}` - Driver components with stepper_drv API: `tmc50xx_stepper_driver_x_axis@0 {/ device_api: stepper_drv api */}`
API Usage	Direct stepper control: `stepper_move_to(x_axis_stepper, 200);` `stepper_stop(y_axis_stepper);` `stepper_disable(x_axis_stepper);` `stepper_disable(y_axis_stepper);`	Split responsibility: - Motion control through controller with axis param: `stepper_move_to(x_y_stepper_motion_controller, CONFIG_X_AXIS, 200);` `stepper_stop(x_y_stepper_motion_controller, CONFIG_Y_AXIS);` - Direct driver control remains: `stepper_drv_disable(x_axis_stepper_driver);` `stepper_drv_disable(y_axis_stepper_driver);`
Axis Identification	Implicit through device reference	Explicit using constants or Kconfigs: `CONFIG_X_AXIS 0` `CONFIG_Y_AXIS 1`
Architecture	Flat architecture with each stepper as independent device	Hierarchical with clear separation between controller and drivers

Side effects:

A lot of common code is refactored out and the stepper step-dir or h-bridge based drivers only do what the ic supports. i.e. enable/disable, set/get ustep resolution, step/dir.
Drv84xx handles fault events as of now, which is good. However, handling of fault event has to be refactored out of stepper_api, as mentioned in the RFC Split Stepper Motion Controller <-> Stepper Driver #89786 .
Introduce set_fault_event_callback, remove fault_event from the current stepper_event enum and rename stepper_event_callback to stepper_motion_control_event_callback.

This PR should effectively resolve the PR drvers: stepper: Modular Step-Dir Implementations #91584, which aims to be an intermediate step.
This PR is inspired by the presentation of the complexity of implementing a motion-controller behind an all-knowing stepper api in PR drivers: stepper: Stepper driver architectural refactoring #90748. Thanks @andre-stefanov.
PR drivers: stepper: ADI TMC2130 Stepper Driver #90677 will have rebase and implement stepper_drv api, since it's a stepper_drv driver instead of stepper api, if this PR gets merged before

faxe1008

Small little pass, will do some in depth review later on :^)

faxe1008 · 2025-06-22T12:59:59Z

drivers/stepper/adi_tmc/tmc22xx.c


 static int tmc22xx_stepper_enable(const struct device *dev)
 {
 	const struct tmc22xx_config *config = dev->config;

 	LOG_DBG("Enabling Stepper motor controller %s", dev->name);
-	return gpio_pin_set_dt(&config->enable_pin, 1);
+	return gpio_pin_set_dt(&config->enable_pin, 0);


Generally you would set this to 1 and change the actual output to be active low via devicetree

Yeah that makes sense :) Thanks :^)

Ping @andre-stefanov

yes this is exactly what i came up with in my implementation in the end. It is a bit inconvenient because the user of e.g. tmc2209 has to know this inverted EN logic during DTS definition instead of just saying "i define the pins, the driver knows which level has to be used for enable/disable". But unfortunately i could not provide gpio port/pin references without output level flag in DTS so i left it as faxe is proposing.

What if you do #define STEPPER_GPIO_ENABLE_LEVEL DT_PROP(instance_nr, enable_level)
Then enable_level may be defined in .yaml as an integer or boolean as a required entry.
Then one can do: return gpio_pin_set_dt(&config->enable_pin, STEPPER_GPIO_ENABLE_LEVEL);.
I may be wrong - just my 2 cents here.

drivers/stepper/adi_tmc/tmc22xx.c

drivers/stepper/allegro/a4979.c

drivers/stepper/gpio_stepper_driver.c

dipakgmx · 2025-06-22T14:22:06Z

drivers/stepper/gpio_stepper_driver.c

+#include <zephyr/sys/__assert.h>
+
+#include <zephyr/logging/log.h>
+LOG_MODULE_REGISTER(gpio_stepper_motor_controller, CONFIG_STEPPER_LOG_LEVEL);


Nit: gpio_stepper_motor_controller, just a bit too long :)

dts/bindings/stepper/stepper.yaml

drivers/stepper/stepper_motion_controllers/zephyr_stepper_motion_controller.c

dts/bindings/stepper/adi/adi,tmc50xx.yaml

include/zephyr/drivers/stepper.h

samples/drivers/stepper/generic/boards/nucleo_g071rb.overlay

faxe1008 · 2025-07-21T09:20:42Z

If i go for stepper_driver_* then the current stepper_drv_driver_api would be stepper_driver_driver_api, to me it sounds a bit funny :). We can for sure think of another name :)

True, have not thought about that. Fine with drv then :^)

jilaypandya · 2025-07-21T09:47:21Z

True, have not thought about that. Fine with drv then :^)

Thx :).

jbehrensnx

Fine for me

jilaypandya · 2025-07-23T18:20:54Z

Hey Everyone, i have added a table Stepper Implementation Comparison alongwith some Code Snippets to show how this PR will affect the devicetree and the API usage :)

jbehrensnx

Missed a wrong assert message in the drv84xx/api tests in my last reviews.

tests/drivers/stepper/drv84xx/api/src/main.c

introducing stepper_drv api which is to be implemented by the stepper drivers Add fault handling in drv84xx using a fault cb mechanism With the introduction of the stepper_drv api, the goal is to achieve better separation of concerns where motion controllers are responsible for generating step pulses whereaas stepper drivers do are responsible for stepping, enabling, setting microstep resolution Signed-off-by: Jilay Pandya <[email protected]>

tests/drivers/stepper/drv84xx/api/src/main.c

faxe1008 · 2025-07-24T13:20:02Z

doc/hardware/peripherals/stepper.rst

@@ -3,22 +3,26 @@
 Steppers
 ########

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



Maybe an explanation which driver is responsible for the step function?

And an explanation that the stepper driver API makes use of the steper_drv API internally? Some sort of diagram maybe with a driver which implements both vs one where you have to use zephyr,stepper-motion-control

+1 for some diagrams

jilaypandya · 2025-07-25T17:09:38Z

Hi Everyone, I have introduced one more commit. I think we should bring it in this PR, so that we don't have to introduce breaking changes on the API level in the stepper driver subsystem in the very vicinity of this PR being merged. Sorry for extending the scope of the PR again, but I think it's better that we bring this change in this PR. The most affected drivers are the trinamic ones for now :)

drivers: stepper: introduce event cb mechanism for stepper_drv

stall detection is a stepper_drv functionality and hence stepper_drv
api needs an event callback mechanism

- introduce stepper_index - Drop stepper_drv functions from stepper_api - Refactor Stepper Motion Controller - Refactor Shell Signed-off-by: Jilay Pandya <[email protected]>

Add stepper index selection functionality in stepper shell to select different steppers for the same stepper motion controller Signed-off-by: Jilay Pandya <[email protected]>

add information about stepper_drv api and relevant functions in stepper documentation. rename zephyr,gpio-stepper to zephyr,h-bridge-stepper Signed-off-by: Jilay Pandya <[email protected]>

stall detection is a stepper_drv functionality and hence stepper_drv api needs an event callback mechanism to notify about the stepper driver related events such as fault, stall and so on. Signed-off-by: Jilay Pandya <[email protected]>

sonarqubecloud · 2025-07-26T08:29:22Z

Quality Gate passed

Issues
7 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.5% Duplication on New Code

See analysis details on SonarQube Cloud

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from 0429ffb to 5c9c369 Compare June 21, 2025 22:35

jilaypandya assigned faxe1008 Jun 21, 2025

jilaypandya changed the title ~~wip~~ drivers: stepper: introduce step-dir functions in stepper api to facilitate implementing motion controllers as device drivers Jun 21, 2025

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 9 times, most recently from 676d5fd to 1d51595 Compare June 22, 2025 12:25

faxe1008 reviewed Jun 22, 2025

View reviewed changes

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 2 times, most recently from 9ebf11f to d3c27b5 Compare June 22, 2025 13:17

jilaypandya added this to the v4.3.0 milestone Jun 22, 2025

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 2 times, most recently from 3b94e61 to 703d030 Compare June 22, 2025 14:16

dipakgmx reviewed Jun 22, 2025

View reviewed changes

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 4 times, most recently from 4a60ace to e4b6c2d Compare June 22, 2025 15:31

jilaypandya mentioned this pull request Jun 22, 2025

Split Stepper Motion Controller <-> Stepper Driver #89786

Open

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 4 times, most recently from 84392f5 to 060b707 Compare June 22, 2025 17:35

andre-stefanov suggested changes Jun 22, 2025

View reviewed changes

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from 060b707 to e2dd143 Compare June 22, 2025 19:16

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from 2983743 to 09ef29a Compare July 21, 2025 10:58

jilaypandya requested review from dipakgmx and jbehrensnx July 21, 2025 11:00

jbehrensnx approved these changes Jul 23, 2025

View reviewed changes

dipakgmx previously approved these changes Jul 23, 2025

View reviewed changes

jbehrensnx requested changes Jul 24, 2025

View reviewed changes

tests/drivers/stepper/drv84xx/api/src/main.c Outdated Show resolved Hide resolved

jilaypandya dismissed dipakgmx’s stale review via 15c4138 July 24, 2025 09:32

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from 09ef29a to 15c4138 Compare July 24, 2025 09:32

dipakgmx reviewed Jul 24, 2025

View reviewed changes

tests/drivers/stepper/drv84xx/api/src/main.c Show resolved Hide resolved

jbehrensnx previously approved these changes Jul 24, 2025

View reviewed changes

faxe1008 reviewed Jul 24, 2025

View reviewed changes

jilaypandya dismissed jbehrensnx’s stale review via 30464db July 25, 2025 16:59

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 2 times, most recently from 30464db to b1e061c Compare July 25, 2025 17:05

jilaypandya added 2 commits July 25, 2025 19:37

drivers: stepper: deprecate stepper_drv functions from stepper_api

e5a04e9

- introduce stepper_index - Drop stepper_drv functions from stepper_api - Refactor Stepper Motion Controller - Refactor Shell Signed-off-by: Jilay Pandya <[email protected]>

drivers: stepper: shell: add stepper index selection functionality

7fb6aa2

Add stepper index selection functionality in stepper shell to select different steppers for the same stepper motion controller Signed-off-by: Jilay Pandya <[email protected]>

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from b1e061c to eefa614 Compare July 25, 2025 17:55

zephyrproject-rtos deleted a comment from sonarqubecloud bot Jul 25, 2025

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 2 times, most recently from adae983 to d96828c Compare July 25, 2025 18:59

doc: stepper: introduce stepper_drv api in documentation

9922f96

add information about stepper_drv api and relevant functions in stepper documentation. rename zephyr,gpio-stepper to zephyr,h-bridge-stepper Signed-off-by: Jilay Pandya <[email protected]>

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from d96828c to aa79d02 Compare July 25, 2025 19:33

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from aa79d02 to 75bd6f3 Compare July 26, 2025 08:03

drivers: stepper: introduce stepper_drv api to facilitate implementing motion controllers as device drivers #91979

Are you sure you want to change the base?

drivers: stepper: introduce stepper_drv api to facilitate implementing motion controllers as device drivers #91979

Conversation

jilaypandya commented Jun 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Update 06.07.25

Stepper Implementation Comparison

Uh oh!

faxe1008 left a comment

Choose a reason for hiding this comment

Uh oh!

faxe1008 Jun 22, 2025

Choose a reason for hiding this comment

Uh oh!

jilaypandya Jun 22, 2025

Choose a reason for hiding this comment

Uh oh!

andre-stefanov Jun 22, 2025

Choose a reason for hiding this comment

Uh oh!

KozhinovAlexander Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dipakgmx Jun 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

faxe1008 commented Jul 21, 2025

Uh oh!

jilaypandya commented Jul 21, 2025

Uh oh!

jbehrensnx left a comment

Choose a reason for hiding this comment

Uh oh!

jilaypandya commented Jul 23, 2025

Uh oh!

jbehrensnx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

faxe1008 Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

dipakgmx Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

jilaypandya commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sonarqubecloud bot commented Jul 26, 2025

Quality Gate passed

Uh oh!

Uh oh!

jilaypandya commented Jun 21, 2025 •

edited

Loading

jilaypandya commented Jul 25, 2025 •

edited

Loading