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

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

Update 17.10.25

split the stepper_drv_api out of stepper_api.
model tmc5xxx drivers like mfds.

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/disable, setting/getting microstep resolution 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
adi,tmc50xx-stepper-driver	x
adi,tmc50xx-motion-controller		x
adi,tmc51xx-stepper-driver	x
adi,tmc51xx-motion-controller		x
zephyr,gpio-step-dir-controller		x
zephyr,h-bridge-stepper		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
move_to/move_by/run/stop		impl
set_reference_position		impl
*is_moving		impl
get_actual_position		impl
set_reference_position		impl

Side effects:

A lot of common code is refactored out and the stepper drivers only do what the ic supports. i.e. enable/disable, set/get ustep resolution.

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


 	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

jilaypandya · 2025-09-13T18:36:03Z

Hey Everyone,

I am working towards dropping the stepper_idx from the stepper_api.
Devices like the TMC5XXX would need to be modeled as a MFD, I have pushed the changes for TMC50XX. I will be working on the TMC51XX in the coming days. Thanks :)

sonarqubecloud · 2025-09-13T18:56:58Z

Quality Gate passed

Issues
4 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

faxe1008 · 2025-09-23T12:18:10Z

@jilaypandya props to you for continuing to tackle this :^)

jilaypandya · 2025-10-17T19:13:21Z

Hi Everyone,

I have dropped the step/dir functions from stepper_drv api. With the revised approach, there have been no additions of the apis. Only the stepper driver specific apis have been refactored out to stepper_drv API.
The existing gpio_step_dir_controller which was ingrained in step_dir_stepper_common is now a standalone zephyr,gpio-step-dir-controller device driver. There was some code duplication between h-bridge and step-dir stepper controllers, this has been now refactored out to gpio_stepper_common layer.
tmc50xx and tmc51xx have been now modeled as mfds. These devices also have a physical s/d interface, hence if some application just wants to use the stepper driver, its now possible. The new model of these drivers avoids using the child-binding approach, as was the case earlier with tmc50xx.

 &spi0 {
        /* DEVICE_API: none */
       tmc50xx: tmc50xx@0 {
           compatible = "adi,tmc50xx";
           reg = <0>;
           spi-max-frequency = <DT_FREQ_M(8)>; /* Maximum SPI bus frequency */
           clock-frequency = <DT_FREQ_M(16)>; /* Internal/External Clock frequency */

           /* DEVICE_API: stepper_drv api */
           tmc50xx_0_stepper_driver: tmc50xx_0_stepper_driver {
               idx = <0>;
                compatible = "adi,tmc50xx-stepper-driver";
                micro-step-res = <256>;
                ...
            };

           /* DEVICE_API: stepper api */
           tmc50xx_0_motion_controller: tmc50xx_0_motion_controller {
               idx = <0>;
               compatible = "adi,tmc50xx-motion-controller";
               ...
            };
      };
};

Copilot

Pull Request Overview

This PR refactors the stepper subsystem by splitting driver responsibilities into two distinct APIs: stepper_drv for low-level stepper driver operations (enable/disable, microstep resolution) and stepper for motion controller operations (move, position, velocity control). This separation models TMC5xxx devices as MFD-like controllers with separate driver and motion controller components.

Key Changes:

Introduced stepper_drv API for driver-level operations (enable/disable, microstep configuration, fault detection)
Separated TMC51xx/TMC50xx into stepper driver and motion controller components
Refactored GPIO-based controllers (h_bridge, step_dir) to use common code library
Removed step-dir common code in favor of gpio_stepper common library
Updated tests to reflect new API split

Reviewed Changes

Copilot reviewed 102 out of 104 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
include/zephyr/drivers/stepper.h	Split API into stepper and stepper_drv interfaces
drivers/stepper/ti/drv84xx.c	Converted to stepper_drv API
drivers/stepper/allegro/a4979.c	Converted to stepper_drv API
drivers/stepper/adi_tmc/tmc51xx/*	Split into separate driver and controller files
drivers/stepper/gpio_stepper/*	New common library for GPIO-based controllers
tests/*	Updated tests for new API structure

Comments suppressed due to low confidence (1)

include/zephyr/drivers/stepper.h:1

Missing closing brace in the ternary expression. The macro has an extra opening parenthesis before &step_work_timing_source_api that should be removed, or a closing parenthesis is missing at the end of line 49.

/*

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

drivers/stepper/gpio_stepper/gpio_step_dir.c

drivers/stepper/gpio_stepper/common/include/gpio_stepper_common.h

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. Signed-off-by: Jilay Pandya <[email protected]>

- 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 Signed-off-by: Jilay Pandya <[email protected]>

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 Signed-off-by: Jilay Pandya <[email protected]>

stepper_api does not comprise of apis for configuring stepper drivers. Hence the stepper drivers and corresponding api tests have now been removed from stepper_api test suite. gpio_step_dir and h_bridge_stepper controllers are added to the stepper_api test-suite Signed-off-by: Jilay Pandya <[email protected]>

stepper_api split needs to be addressed in stepper_shell as well Signed-off-by: Jilay Pandya <[email protected]>

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]>

sonarqubecloud · 2025-10-23T06:20:28Z

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% 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 3 times, most recently from 6028fc9 to 49f5c47 Compare September 13, 2025 18:31

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 5 times, most recently from 2a8478c to da93fe7 Compare October 17, 2025 09:17

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from da93fe7 to eeeece2 Compare October 17, 2025 19:24

jilaypandya marked this pull request as ready for review October 17, 2025 19:25

zephyrbot added area: Boards/SoCs area: Devicetree Bindings area: Tests Issues related to a particular existing or missing test labels Oct 17, 2025

jilaypandya force-pushed the feature/introduce-step-dir-functions branch 3 times, most recently from df91e36 to 25a3253 Compare October 22, 2025 19:15

jilaypandya requested a review from Copilot October 23, 2025 05:52

Copilot AI reviewed Oct 23, 2025

View reviewed changes

drivers/stepper/gpio_stepper/gpio_step_dir.c Outdated Show resolved Hide resolved

drivers/stepper/gpio_stepper/common/include/gpio_stepper_common.h Outdated Show resolved Hide resolved

drivers/stepper/gpio_stepper/common/include/gpio_stepper_common.h Outdated Show resolved Hide resolved

jilaypandya added 6 commits October 23, 2025 07:53

drivers: stepper: split stepper api

5dbbdd7

- 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 Signed-off-by: Jilay Pandya <[email protected]>

drivers: stepper: refactor gpio based stepper drivers

a02f4d9

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 Signed-off-by: Jilay Pandya <[email protected]>

drivers: stepper: shell: refactor to address the split

59d9a8e

stepper_api split needs to be addressed in stepper_shell as well Signed-off-by: Jilay Pandya <[email protected]>

drivers: stepper: tmc5xxx: use mfd approach

961a67b

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]>

jilaypandya force-pushed the feature/introduce-step-dir-functions branch from 25a3253 to 961a67b Compare October 23, 2025 06:02

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 17.10.25

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!

jilaypandya commented Sep 13, 2025

Uh oh!

sonarqubecloud bot commented Sep 13, 2025

Quality Gate passed

Uh oh!

faxe1008 commented Sep 23, 2025

Uh oh!

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

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Oct 23, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

jilaypandya commented Jun 21, 2025 •

edited

Loading

jilaypandya commented Oct 17, 2025 •

edited

Loading