drivers: stepper: Stepper driver architectural refactoring #90748

andre-stefanov · 2025-05-28T14:11:42Z

Introduction

Problem description

The current stepper motor driver implementation lacks a standardized and flexible API architecture that can accommodate different stepper motor types, control methods, and motion profiles. This makes it difficult to implement advanced features like ramping (acceleration/deceleration profiles) and to cleanly separate the hardware abstraction from the motion control logic.

Proposed change

Refactor the stepper driver API to create a modular, extensible architecture that separates core functionality from implementation details. This includes creating a clear hierarchy of components: generic stepper interface, timing source, motion controller, and ramp profile abstractions. The architecture will allow for plug-and-play ramp profiles and consistent interfaces across different stepper driver implementations.

Detailed RFC

Proposed change (Detailed)

The refactored stepper API architecture introduces a layered design with three key architectural elements:

Timing Source Layer
- Provides precise timing for step generation
- Abstracts hardware-specific timing mechanisms (counters, timers, PWM)
- Enables consistent timing control across different hardware platforms
Motion Controller Layer
- Acts as a bridge between the high-level stepper API and low-level hardware control
- Manages motion profiles and coordinates with the timing source
- Handles positioning, direction control, and step generation
- Provides event handling and notification for motion completion and errors
- Implements common motion control functions like move_by, move_to, and run
Ramp Profile Layer
- Defines acceleration and deceleration profiles (linear, s-curve, etc.)
- Pluggable design allows different ramp implementations to be used with any stepper driver
- Calculates step intervals based on current position and target position
- Enables smooth motion with controlled acceleration and deceleration
Hardware access Layer
- Provides common hardware access utilities for common stepper interfaces (e.g. step/dir, h-bridge, SPI, UART or even a composition of those depending on device driver needs and configuration)
- Acts as an abstraction to be used by device driver, stepper_common or other internal components
- Reduces boilerplate for device drivers having similar interfaces

graph LR

    subgraph Zephyr
    
    subgraph API
        StepperAPI[Stepper API]
    end
    
    subgraph Device drivers
        TMC22xx[TMC22xx]
        
        StepperAPI --> TMC22xx
    end
    
    subgraph Motion Controller
        MotionController[Motion Controller]
        
        TMC22xx --> MotionController
    end
    
    subgraph Ramp
        RampBase[Ramp Base]
        ConstantRamp[Constant Velocity Ramp]
        TrapezoidalRamp[Trapezoidal Ramp]
        
        TrapezoidalRamp -->|Implements| RampBase
        MotionController --> RampBase
        ConstantRamp -->|Implements| RampBase
    end
    
    subgraph Timing Source
        TimingSourceAPI[Timing Source API]
        Counter[Counter]

        MotionController --> TimingSourceAPI
        Counter -->|Implements| TimingSourceAPI
    end
    
    subgraph Hardware Access
        interface[Stepper interface]

        stepdir[Step/Dir/En]
        gpio[GPIO]

        TMC22xx --> stepdir
        stepdir -->|Implements| interface
        gpio -->|Implements| interface
        MotionController --> interface
    end

    end
    subgraph Application
        CustomRamp
    
        CustomRamp -->|Implements| RampBase
    end

    Application --> StepperAPI
    Application --> TMC22xx

This architecture separates concerns clearly:

Hardware-specific implementations only need to handle device-specific features
Motion control logic is reusable across different stepper motor types
Timing mechanisms can be optimized for different platforms, MCU features or available hardware components
Ramp profiles can be developed and improved independently (e.g. defined in application code for special requirements)

Dependencies

This change affects:

Stepper motor driver implementations that need to adapt to the new API
Applications that utilize stepper motors and need to migrate to the new interface

The core Zephyr kernel and other subsystems are not affected as this is contained within the driver layer.

Concerns and Unresolved Questions

Performance impact of the abstraction layers, especially for time-critical operations
Ensuring efficient resource usage when multiple stepper motors share hardware resources
Synchronization with vendor specific features provided in hardware (ramp generator, position etc)

The chosen layered approach provides a good balance of flexibility, code reuse, and standardization. By separating the timing source, motion control, and ramp profile concerns, we enable future extensions without major API changes, while providing a consistent experience for application developers across different stepper motor implementations.

Currentl PoC was tested with samples/drivers/stepper/generic by using TMC2209 and a nucleo_f446re.

jilaypandya

Cool :)

jilaypandya · 2025-05-28T17:25:35Z

drivers/stepper/motion_controller/stepper_motion_controller.c

+				LOG_ERR("Failed to start timing source: %d", ret);
+			}
+		}
+	} else {


Reduce the nesting with early return :)

dipakgmx · 2025-05-28T18:27:30Z

drivers/stepper/motion_controller/ramp/stepper_ramp_trapezoidal.c

+	return (uint32_t)x;
+}
+
+static uint64_t avr446_start_interval(const uint32_t acceleration)


Any reason for these functions to have the avr446 prefix?

https://ww1.microchip.com/downloads/en/Appnotes/doc8017.pdf

It's an internal function which is implementing part of the AVR446 algorithm.

jilaypandya · 2025-05-28T18:19:39Z

drivers/stepper/CMakeLists.txt

+
+# zephyr-keep-sorted-start
+add_subdirectory(motion_controller)
+add_subdirectory(interface)


Suggested change

add_subdirectory(interface)

add_subdirectory(step_dir_interface)

Actually i thought this folder could later include multiple different stepper interfaces (like e.g. h-bridge etc). Do we want to have each one in its own folder?

jilaypandya · 2025-05-28T18:33:28Z

include/zephyr/drivers/stepper.h

 */
-typedef int (*stepper_set_microstep_interval_t)(const struct device *dev,
-						const uint64_t microstep_interval_ns);
+typedef int (*stepper_set_ramp_t)(const struct device *dev, struct stepper_ramp_base *ramp);


Could this scale up for setting ramp for tmc drivers?

it could yes but i am not sure if we really want to handle hardware ramp of trinamic under stepper.h API or deal with it like with any other vendor specific API over e.g. stepper_trinamic.h. this is definitely something to be discussed

jilaypandya · 2025-05-28T18:54:05Z

drivers/stepper/stepper_common.h

+	 */
+	stepper_enable_t enable;
+	/**
+	 * @brief Represents a point in a 2D Cartesian coordinate system.


Documentation is off

will rewrite it. thx

jilaypandya · 2025-05-28T18:57:17Z

drivers/stepper/adi_tmc/tmc22xx.c

+	STEPPER_MOTION_CONTROLLER_DT_INST_DEFINE(inst, &motion_controller_callbacks)                 \
+	STEPPER_INTERFACE_STEP_DIR_DT_INST_DEFINE(inst)                                              \
+	static const struct stepper_common_config common_cfg_##inst = {                              \
+		.motion_controller = STEPPER_MOTION_CONTROLLER_DT_INST_GET(inst),                    \


could you have a look at the compliance checks over here, Lot of noise is being created from the GitHub actions

yeah compliance checks are my next goal

jilaypandya · 2025-05-29T06:45:20Z

drivers/stepper/adi_tmc/tmc22xx.c

-	static const struct gpio_dt_spec tmc22xx_stepper_msx_pins_##inst[] = {                     \
-		DT_INST_FOREACH_PROP_ELEM_SEP(                                                     \
-			inst, msx_gpios, GPIO_DT_SPEC_GET_BY_IDX, (,)                              \
-		),                                                                                 \


Just to reduce some noise in this File, could we revert the changes related to msx_gpios, so that it's directly visible that motion_controller and interface are getting added. I see the IF_ENABLED and BUILD_ASSERT macros in relation to msx_gpios have been shifted around, but keeping them where they where would make the git diff a bit more pleasant :)

jilaypandya · 2025-05-29T06:50:49Z

drivers/stepper/motion_controller/ramp/stepper_ramp_constant.c

ramp_constant is a bit ambiguous i think. Alternative name might be stepper_constant_speed.c .

jilaypandya · 2025-05-29T06:52:20Z

drivers/stepper/motion_controller/ramp/stepper_ramp_trapezoidal.c

I like personally like how the various phases of a ramp are based on the steps in a particular ramp phase.

jilaypandya · 2025-05-29T06:54:11Z

drivers/stepper/motion_controller/stepper_motion_controller.h

+ */
+int stepper_motion_controller_is_moving(const struct device *dev, bool *is_moving);
+
+int stepper_motion_controller_set_ramp(const struct device *dev, struct stepper_ramp_base *ramp);


missing documentation

jilaypandya · 2025-05-29T06:54:49Z

drivers/stepper/motion_controller/timing_source/stepper_timing_source.h

@@ -0,0 +1,129 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2024 Fabian Blatz <fabianblatz@gmail.com>
+ *			   Copyright (c) 2025 Andre Stefanov <mail@andrestefanov.de>


Suggested change

* Copyright (c) 2025 Andre Stefanov <mail@andrestefanov.de>

* SPDX-FileCopyrightText: Copyright (c) 2025 Andre Stefanov <mail@andrestefanov.de>

jilaypandya · 2025-05-29T06:55:15Z

drivers/stepper/motion_controller/timing_source/stepper_timing_source_counter.c

@@ -0,0 +1,104 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2024 Fabian Blatz <fabianblatz@gmail.com>
+ *					 2025 Andre Stefanov <mail@andrestefanov.de>


Suggested change

* 2025 Andre Stefanov <mail@andrestefanov.de>

* SPDX-FileCopyrightText: 2025 Andre Stefanov <mail@andrestefanov.de>

Introduced modular architecture to the stepper driver to allow usage of different software and hardware components during stepper motion. Signed-off-by: Andre Stefanov <mail@andrestefanov.de>

sonarqubecloud · 2025-05-29T22:46:34Z

Quality Gate passed

Issues
0 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

github-actions bot added area: Stepper area: Samples Samples platform: ADI Analog Devices, Inc. labels May 28, 2025

github-actions bot requested review from bjarki-andreasen, dipakgmx, fabiobaltieri, faxe1008, galak, jbehrensnx, jilaypandya, kartben, MaureenHelm, microbuilder, nashif, ozersa, ttmut and yasinustunerg May 28, 2025 14:12

github-actions bot assigned jilaypandya May 28, 2025

jilaypandya reviewed May 28, 2025

View reviewed changes

dipakgmx reviewed May 28, 2025

View reviewed changes

jilaypandya reviewed May 28, 2025

View reviewed changes

andre-stefanov force-pushed the feature/stepper-refactoring branch 4 times, most recently from cd2e18e to fba3e91 Compare May 28, 2025 22:11

jilaypandya reviewed May 29, 2025

View reviewed changes

andre-stefanov force-pushed the feature/stepper-refactoring branch 6 times, most recently from 23dbd4a to 9b4aebc Compare May 29, 2025 22:03

drivers: stepper: Stepper driver architectural refactoring

b1e1959

Introduced modular architecture to the stepper driver to allow usage of different software and hardware components during stepper motion. Signed-off-by: Andre Stefanov <mail@andrestefanov.de>

andre-stefanov force-pushed the feature/stepper-refactoring branch from 9b4aebc to b1e1959 Compare May 29, 2025 22:28

	add_subdirectory(interface)
	add_subdirectory(step_dir_interface)

	* Copyright (c) 2025 Andre Stefanov <mail@andrestefanov.de>
	* SPDX-FileCopyrightText: Copyright (c) 2025 Andre Stefanov <mail@andrestefanov.de>

	* 2025 Andre Stefanov <mail@andrestefanov.de>
	* SPDX-FileCopyrightText: 2025 Andre Stefanov <mail@andrestefanov.de>

drivers: stepper: Stepper driver architectural refactoring #90748

Are you sure you want to change the base?

drivers: stepper: Stepper driver architectural refactoring #90748

Conversation

andre-stefanov commented May 28, 2025

Introduction

Problem description

Proposed change

Detailed RFC

Proposed change (Detailed)

Dependencies

Concerns and Unresolved Questions

Uh oh!

jilaypandya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented May 29, 2025

Quality Gate passed

Uh oh!

Uh oh!

jilaypandya May 29, 2025 •

edited

Loading

jilaypandya May 29, 2025 •

edited

Loading