drivers: stepper: introduce rudimentary ramp control

Introduce rudimentary control using following paper:
https://www.boost.org/doc/libs/1_81_0/libs/safe_numerics/example/stepper-motor.pdf

Signed-off-by: Jilay Pandya <[email protected]>

Author: jilaypandya

drivers/stepper/CMakeLists.txt

@@ -7,6 +7,10 @@ zephyr_syscall_header(${ZEPHYR_BASE}/include/zephyr/drivers/stepper.h)
 add_subdirectory_ifdef(CONFIG_STEPPER_ADI_TMC adi_tmc)
 add_subdirectory_ifdef(CONFIG_STEPPER_ALLEGRO allegro)
 add_subdirectory_ifdef(CONFIG_STEPPER_TI ti)
+# zephyr-keep-sorted-stop
+
+# zephyr-keep-sorted-start
+add_subdirectory_ifdef(CONFIG_STEPPER_RAMP ramp)
 add_subdirectory_ifdef(CONFIG_STEP_DIR_STEPPER step_dir)
 # zephyr-keep-sorted-stop
 

drivers/stepper/Kconfig

@@ -26,6 +26,7 @@ config STEPPER_SHELL
 
 comment "Stepper Driver Common"
 
+rsource "ramp/Kconfig"
 rsource "step_dir/Kconfig"
 
 comment "Stepper Drivers"

drivers/stepper/gpio_stepper_controller.c

@@ -12,6 +12,10 @@
 #include <zephyr/drivers/stepper.h>
 #include <zephyr/sys/__assert.h>
 
+#ifdef CONFIG_STEPPER_RAMP
+#include "ramp/ramp.h"
+#endif
+
 #include <zephyr/logging/log.h>
 LOG_MODULE_REGISTER(gpio_stepper_motor_controller, CONFIG_STEPPER_LOG_LEVEL);
 
@@ -26,6 +30,9 @@ static const uint8_t
 struct gpio_stepper_config {
 	const struct gpio_dt_spec *control_pins;
 	bool invert_direction;
+#ifdef CONFIG_STEPPER_RAMP
+	const struct stepper_ramp_config ramp_config;
+#endif
 };
 
 struct gpio_stepper_data {
@@ -42,6 +49,9 @@ struct gpio_stepper_data {
 	bool is_enabled;
 	stepper_event_callback_t callback;
 	void *event_cb_user_data;
+#ifdef CONFIG_STEPPER_RAMP
+	struct stepper_ramp_common ramp_common;
+#endif
 };
 
 static int stepper_motor_set_coil_charge(const struct device *dev)
@@ -98,6 +108,24 @@ static void update_coil_charge(const struct device *dev)
 	const struct gpio_stepper_config *config = dev->config;
 	struct gpio_stepper_data *data = dev->data;
 
+#ifdef CONFIG_STEPPER_RAMP
+	if (data->ramp_common.ramp_data.current_ramp_state ==
+	    STEPPER_RAMP_STATE_FORCED_DECELERATION) {
+		if (data->direction == STEPPER_DIRECTION_NEGATIVE) {
+			config->invert_direction ? decrement_coil_charge(dev)
+						 : increment_coil_charge(dev);
+			data->actual_position++;
+			return;
+		}
+		if (data->direction == STEPPER_DIRECTION_POSITIVE) {
+			config->invert_direction ? increment_coil_charge(dev)
+						 : decrement_coil_charge(dev);
+			data->actual_position--;
+			return;
+		}
+	}
+#endif
+
 	if (data->direction == STEPPER_DIRECTION_POSITIVE) {
 		config->invert_direction ? decrement_coil_charge(dev) : increment_coil_charge(dev);
 		data->actual_position++;
@@ -109,6 +137,24 @@ static void update_coil_charge(const struct device *dev)
 
 static void update_remaining_steps(struct gpio_stepper_data *data)
 {
+#ifdef CONFIG_STEPPER_RAMP
+	if (data->step_count != 0) {
+		data->delay_in_ns = trapezoidal_ramp_api.get_next_step_interval(&data->ramp_common,
+										data->delay_in_ns);
+
+		if (data->ramp_common.ramp_data.current_ramp_state ==
+		    STEPPER_RAMP_STATE_FORCED_DECELERATION) {
+			if (data->step_count > 0) {
+				data->step_count++;
+			} else {
+				data->step_count--;
+			}
+			(void)k_work_reschedule(&data->stepper_dwork, K_NSEC(data->delay_in_ns));
+		}
+	} else {
+		data->ramp_common.ramp_data.current_ramp_state = STEPPER_RAMP_STATE_NOT_MOVING;
+	}
+#endif
 	if (data->step_count > 0) {
 		data->step_count--;
 		(void)k_work_reschedule(&data->stepper_dwork, K_NSEC(data->delay_in_ns));
@@ -124,9 +170,10 @@ static void update_remaining_steps(struct gpio_stepper_data *data)
 	}
 }
 
-static void update_direction_from_step_count(const struct device *dev)
+static bool update_direction_from_step_count(const struct device *dev)
 {
 	struct gpio_stepper_data *data = dev->data;
+	enum stepper_direction direction = data->direction;
 
 	if (data->step_count > 0) {
 		data->direction = STEPPER_DIRECTION_POSITIVE;
@@ -135,6 +182,10 @@ static void update_direction_from_step_count(const struct device *dev)
 	} else {
 		LOG_ERR("Step count is zero");
 	}
+	if (data->direction != direction) {
+		return true;
+	}
+	return false;
 }
 
 static void position_mode_task(const struct device *dev)
@@ -178,6 +229,23 @@ static void stepper_work_step_handler(struct k_work *work)
 	}
 }
 
+static bool is_step_timing_valid(const struct device *dev)
+{
+	struct gpio_stepper_data *data = dev->data;
+#ifdef CONFIG_STEPPER_RAMP
+
+	if (data->ramp_common.ramp_profile.max_velocity > 0) {
+		return true;
+	}
+	return false;
+#else
+	if (data->delay_in_ns > 0) {
+		return true;
+	}
+	return false;
+#endif
+}
+
 static int gpio_stepper_move_by(const struct device *dev, int32_t micro_steps)
 {
 	struct gpio_stepper_data *data = dev->data;
@@ -187,14 +255,29 @@ static int gpio_stepper_move_by(const struct device *dev, int32_t micro_steps)
 		return -ECANCELED;
 	}
 
-	if (data->delay_in_ns == 0) {
-		LOG_ERR("Step interval not set or invalid step interval set");
+	if (!is_step_timing_valid(dev)) {
 		return -EINVAL;
 	}
+
+	if (micro_steps == 0) {
+		LOG_WRN("Step count is zero");
+		return 0;
+	}
+
 	K_SPINLOCK(&data->lock) {
 		data->run_mode = STEPPER_RUN_MODE_POSITION;
 		data->step_count = micro_steps;
-		update_direction_from_step_count(dev);
+		bool is_dir_changed = update_direction_from_step_count(dev);
+#ifdef CONFIG_STEPPER_RAMP
+		const struct gpio_stepper_config *config = dev->config;
+		uint32_t steps_to_move = abs(micro_steps);
+
+		trapezoidal_ramp_api.reset_ramp_data(&config->ramp_config, &data->ramp_common,
+						     &data->delay_in_ns, is_dir_changed,
+						     steps_to_move);
+#else
+		ARG_UNUSED(is_dir_changed);
+#endif
 		(void)k_work_reschedule(&data->stepper_dwork, K_NO_WAIT);
 	}
 	return 0;
@@ -229,14 +312,24 @@ static int gpio_stepper_move_to(const struct device *dev, int32_t micro_steps)
 		return -ECANCELED;
 	}
 
-	if (data->delay_in_ns == 0) {
-		LOG_ERR("Step interval not set or invalid step interval set");
+	if (!is_step_timing_valid(dev)) {
 		return -EINVAL;
 	}
+
 	K_SPINLOCK(&data->lock) {
 		data->run_mode = STEPPER_RUN_MODE_POSITION;
 		data->step_count = micro_steps - data->actual_position;
-		update_direction_from_step_count(dev);
+		bool is_dir_changed = update_direction_from_step_count(dev);
+#ifdef CONFIG_STEPPER_RAMP
+		const struct gpio_stepper_config *config = dev->config;
+		uint32_t steps_to_move = abs(micro_steps - data->actual_position);
+
+		trapezoidal_ramp_api.reset_ramp_data(&config->ramp_config, &data->ramp_common,
+						     &data->delay_in_ns, is_dir_changed,
+						     steps_to_move);
+#else
+		ARG_UNUSED(is_dir_changed);
+#endif
 		(void)k_work_reschedule(&data->stepper_dwork, K_NO_WAIT);
 	}
 	return 0;
@@ -268,6 +361,23 @@ static int gpio_stepper_set_microstep_interval(const struct device *dev,
 	return 0;
 }
 
+#ifdef CONFIG_STEPPER_RAMP
+
+static int gpio_stepper_set_ramp_profile(const struct device *dev,
+					 const struct stepper_ramp_profile *const ramp_profile)
+{
+	struct gpio_stepper_data *data = dev->data;
+
+	K_SPINLOCK(&data->lock) {
+		data->ramp_common.ramp_profile.acceleration = ramp_profile->acceleration;
+		data->ramp_common.ramp_profile.max_velocity = ramp_profile->max_velocity;
+		data->ramp_common.ramp_profile.deceleration = ramp_profile->deceleration;
+	}
+	return 0;
+}
+
+#endif
+
 static int gpio_stepper_run(const struct device *dev, const enum stepper_direction direction)
 {
 	struct gpio_stepper_data *data = dev->data;
@@ -350,6 +460,9 @@ static int gpio_stepper_disable(const struct device *dev)
 	int err;
 
 	K_SPINLOCK(&data->lock) {
+#ifdef CONFIG_STEPPER_RAMP
+		data->ramp_common.ramp_data.current_ramp_state = STEPPER_RAMP_STATE_NOT_MOVING;
+#endif
 		(void)k_work_cancel_delayable(&data->stepper_dwork);
 		err = energize_coils(dev, false);
 		if (err == 0) {
@@ -385,6 +498,7 @@ static int gpio_stepper_init(const struct device *dev)
 	for (uint8_t n_pin = 0; n_pin < NUM_CONTROL_PINS; n_pin++) {
 		(void)gpio_pin_configure_dt(&config->control_pins[n_pin], GPIO_OUTPUT_INACTIVE);
 	}
+
 	k_work_init_delayable(&data->stepper_dwork, stepper_work_step_handler);
 	return 0;
 }
@@ -403,20 +517,29 @@ static DEVICE_API(stepper, gpio_stepper_api) = {
 	.run = gpio_stepper_run,
 	.stop = gpio_stepper_stop,
 	.is_moving = gpio_stepper_is_moving,
+	IF_ENABLED(CONFIG_STEPPER_RAMP, (.set_ramp_profile = gpio_stepper_set_ramp_profile,))
+
 };
 
 #define GPIO_STEPPER_DEFINE(inst)								\
 	static const struct gpio_dt_spec gpio_stepper_motor_control_pins_##inst[] = {		\
 		DT_INST_FOREACH_PROP_ELEM_SEP(inst, gpios, GPIO_DT_SPEC_GET_BY_IDX, (,)),	\
 	};											\
 	BUILD_ASSERT(ARRAY_SIZE(gpio_stepper_motor_control_pins_##inst) == 4,			\
-		"gpio_stepper_controller driver currently supports only 4 wire configuration");	\
+		"gpio_stepper_controller driver currently supports only 4 wire configuration"); \
 	static const struct gpio_stepper_config gpio_stepper_config_##inst = {			\
 		.invert_direction = DT_INST_PROP(inst, invert_direction),			\
-		.control_pins = gpio_stepper_motor_control_pins_##inst};			\
+		.control_pins = gpio_stepper_motor_control_pins_##inst,				\
+		IF_ENABLED(CONFIG_STEPPER_RAMP,							\
+	(.ramp_config.forced_deceleration_steps = DT_INST_PROP(inst, forced_decel_steps))) };	\
 	static struct gpio_stepper_data gpio_stepper_data_##inst = {				\
 		.step_gap = MAX_MICRO_STEP_RES >> (DT_INST_PROP(inst, micro_step_res) - 1),	\
-	};											\
+		IF_ENABLED(CONFIG_STEPPER_RAMP,							\
+	(.ramp_common.ramp_data.ramp_stop_step_interval_threshold_in_ns =			\
+		DT_INST_PROP(inst, ramp_stop_step_interval),					\
+	.ramp_common.ramp_profile.acceleration = DT_INST_PROP(inst, acceleration),		\
+	.ramp_common.ramp_profile.deceleration = DT_INST_PROP(inst, deceleration),		\
+	.ramp_common.ramp_profile.max_velocity = DT_INST_PROP(inst, max_speed),)) };		\
 	BUILD_ASSERT(DT_INST_PROP(inst, micro_step_res) <= STEPPER_MICRO_STEP_2,		\
 		     "gpio_stepper_controller driver supports up to 2 micro steps");		\
 	DEVICE_DT_INST_DEFINE(inst, gpio_stepper_init, NULL, &gpio_stepper_data_##inst,		\

drivers/stepper/ramp/CMakeLists.txt

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Jilay Sandeep Pandya
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library()
+
+zephyr_library_sources_ifdef(CONFIG_STEPPER_RAMP ramp_trapezoidal.c)

drivers/stepper/ramp/Kconfig

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Jilay Sandeep Pandya
+# SPDX-License-Identifier: Apache-2.0
+
+menuconfig STEPPER_RAMP
+	bool "Ramp control"
+	help
+	  Enable ramp control for stepper drivers.
+
+if STEPPER_RAMP
+
+config STEPPER_TRAPEZOIDAL_RAMP
+	bool "Trapezoidal ramp control"
+	help
+	  Enable trapezoidal ramp control for stepper drivers.
+	  The trapezoidal ramp control is implemented as a state machine
+	  and can be used with any stepper driver.
+
+endif

drivers/stepper/ramp/ramp.h

@@ -0,0 +1,73 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2025 Jilay Sandeep Pandya
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_DRIVERS_STEPPER_RAMP_H_
+#define ZEPHYR_DRIVERS_STEPPER_RAMP_H_
+
+#include <stdlib.h>
+#include <zephyr/drivers/stepper.h>
+
+struct stepper_ramp_distance_profile {
+	/* Distance to accelerate in µsteps */
+	uint32_t acceleration;
+	/* Distance to travel at constant velocity in µsteps */
+	uint32_t const_speed;
+	/* Distance to decelerate in µsteps */
+	uint32_t deceleration;
+};
+
+enum stepper_ramp_state {
+	/* Ramp state for not moving */
+	STEPPER_RAMP_STATE_NOT_MOVING,
+	/* Ramp state for acceleration */
+	STEPPER_RAMP_STATE_ACCELERATION,
+	/* Ramp state for constant speed */
+	STEPPER_RAMP_STATE_CONSTANT_SPEED,
+	/* Ramp state for deceleration */
+	STEPPER_RAMP_STATE_DECELERATION,
+	/* Ramp state for forced deceleration while switching direction */
+	STEPPER_RAMP_STATE_FORCED_DECELERATION,
+};
+
+struct stepper_ramp_data {
+	/* Actual position in µsteps */
+	uint32_t ramp_actual_position;
+	/* Target position in µsteps */
+	uint32_t ramp_target_position;
+	/* Steps to be used while forced deceleration */
+	int32_t forced_deceleration_steps;
+	/* Ramping is allowed once this velocity threshold is crossed */
+	const uint64_t ramp_stop_step_interval_threshold_in_ns;
+	/* Ramp state */
+	enum stepper_ramp_state current_ramp_state;
+};
+
+struct stepper_ramp_config {
+	const uint32_t forced_deceleration_steps;
+};
+
+struct stepper_ramp_common {
+	struct stepper_ramp_data ramp_data;
+	struct stepper_ramp_distance_profile ramp_distance_profile;
+	struct stepper_ramp_profile ramp_profile;
+};
+
+typedef void (*stepper_ramp_reset_ramp_data)(const struct stepper_ramp_config *config,
+					     struct stepper_ramp_common *ramp_common,
+					     uint64_t *step_interval_in_ns,
+					     bool is_stepper_dir_changed,
+					     const uint32_t steps_to_move);
+
+typedef uint64_t (*stepper_ramp_get_next_step_interval)(struct stepper_ramp_common *ramp_common,
+							const uint64_t current_step_interval_in_ns);
+
+struct stepper_ramp_api {
+	stepper_ramp_reset_ramp_data reset_ramp_data;
+	stepper_ramp_get_next_step_interval get_next_step_interval;
+};
+
+extern const struct stepper_ramp_api trapezoidal_ramp_api;
+
+#endif