diff --git a/doc/hardware/peripherals/stepper.rst b/doc/hardware/peripherals/stepper.rst index 8dce76c5d55..e089b18ffa7 100644 --- a/doc/hardware/peripherals/stepper.rst +++ b/doc/hardware/peripherals/stepper.rst @@ -18,7 +18,7 @@ Configure Stepper Driver Control Stepper =============== -- **Move by** +/- micro-steps also known as **relative movement** using :c:func:`stepper_move`. +- **Move by** +/- micro-steps also known as **relative movement** using :c:func:`stepper_move_by`. - **Move to** a specific position also known as **absolute movement** using :c:func:`stepper_set_target_position`. - Run continuously with a **constant velocity** in a specific direction until diff --git a/doc/releases/migration-guide-4.1.rst b/doc/releases/migration-guide-4.1.rst index 7ef6964bc9b..8c2f17b4f87 100644 --- a/doc/releases/migration-guide-4.1.rst +++ b/doc/releases/migration-guide-4.1.rst @@ -180,6 +180,7 @@ Stepper * Renamed the ``compatible`` from ``zephyr,gpio-steppers`` to :dtcompatible:`zephyr,gpio-stepper`. * Renamed the ``stepper_set_actual_position`` function to :c:func:`stepper_set_reference_position`. * Renamed the ``stepper_enable_constant_velocity_mode`` function to :c:func:`stepper_run`. + * Renamed the ``stepper_move`` function to :c:func:`stepper_move_by`. SPI === diff --git a/drivers/stepper/adi_tmc/adi_tmc5041_stepper_controller.c b/drivers/stepper/adi_tmc/adi_tmc5041_stepper_controller.c index d8bdd4e2bd0..b8be1d8846b 100644 --- a/drivers/stepper/adi_tmc/adi_tmc5041_stepper_controller.c +++ b/drivers/stepper/adi_tmc/adi_tmc5041_stepper_controller.c @@ -301,7 +301,7 @@ static int tmc5041_stepper_is_moving(const struct device *dev, bool *is_moving) return 0; } -static int tmc5041_stepper_move(const struct device *dev, const int32_t steps) +static int tmc5041_stepper_move_by(const struct device *dev, const int32_t micro_steps) { const struct tmc5041_stepper_config *config = dev->config; struct tmc5041_stepper_data *data = dev->data; @@ -320,7 +320,7 @@ static int tmc5041_stepper_move(const struct device *dev, const int32_t steps) if (err != 0) { return -EIO; } - int32_t target_position = position + steps; + int32_t target_position = position + micro_steps; err = tmc5041_write(config->controller, TMC5041_RAMPMODE(config->index), TMC5XXX_RAMPMODE_POSITIONING_MODE); @@ -328,7 +328,7 @@ static int tmc5041_stepper_move(const struct device *dev, const int32_t steps) return -EIO; } LOG_DBG("Stepper motor controller %s moved to %d by steps: %d", dev->name, target_position, - steps); + micro_steps); err = tmc5041_write(config->controller, TMC5041_XTARGET(config->index), target_position); if (err != 0) { return -EIO; @@ -723,7 +723,7 @@ static int tmc5041_stepper_init(const struct device *dev) static DEVICE_API(stepper, tmc5041_stepper_api_##child) = { \ .enable = tmc5041_stepper_enable, \ .is_moving = tmc5041_stepper_is_moving, \ - .move = tmc5041_stepper_move, \ + .move_by = tmc5041_stepper_move_by, \ .set_max_velocity = tmc5041_stepper_set_max_velocity, \ .set_micro_step_res = tmc5041_stepper_set_micro_step_res, \ .get_micro_step_res = tmc5041_stepper_get_micro_step_res, \ diff --git a/drivers/stepper/fake_stepper_controller.c b/drivers/stepper/fake_stepper_controller.c index 9520272ad5a..ae369639459 100644 --- a/drivers/stepper/fake_stepper_controller.c +++ b/drivers/stepper/fake_stepper_controller.c @@ -23,7 +23,7 @@ DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_enable, const struct device *, bool); DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_is_moving, const struct device *, bool *); -DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_move, const struct device *, int32_t); +DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_move_by, const struct device *, int32_t); DEFINE_FAKE_VALUE_FUNC(int, fake_stepper_set_max_velocity, const struct device *, uint32_t); @@ -90,7 +90,7 @@ static void fake_stepper_reset_rule_before(const struct ztest_unit_test *test, v ARG_UNUSED(fixture); RESET_FAKE(fake_stepper_enable); - RESET_FAKE(fake_stepper_move); + RESET_FAKE(fake_stepper_move_by); RESET_FAKE(fake_stepper_is_moving); RESET_FAKE(fake_stepper_set_max_velocity); RESET_FAKE(fake_stepper_set_micro_step_res); @@ -126,7 +126,7 @@ static int fake_stepper_init(const struct device *dev) static DEVICE_API(stepper, fake_stepper_driver_api) = { .enable = fake_stepper_enable, - .move = fake_stepper_move, + .move_by = fake_stepper_move_by, .is_moving = fake_stepper_is_moving, .set_max_velocity = fake_stepper_set_max_velocity, .set_micro_step_res = fake_stepper_set_micro_step_res, diff --git a/drivers/stepper/gpio_stepper_controller.c b/drivers/stepper/gpio_stepper_controller.c index ce7eb9ed74a..8224f2170e7 100644 --- a/drivers/stepper/gpio_stepper_controller.c +++ b/drivers/stepper/gpio_stepper_controller.c @@ -177,7 +177,7 @@ static void stepper_work_step_handler(struct k_work *work) } } -static int gpio_stepper_move(const struct device *dev, int32_t micro_steps) +static int gpio_stepper_move_by(const struct device *dev, int32_t micro_steps) { struct gpio_stepper_data *data = dev->data; @@ -353,7 +353,7 @@ static int gpio_stepper_init(const struct device *dev) static DEVICE_API(stepper, gpio_stepper_api) = { .enable = gpio_stepper_enable, - .move = gpio_stepper_move, + .move_by = gpio_stepper_move_by, .is_moving = gpio_stepper_is_moving, .set_reference_position = gpio_stepper_set_reference_position, .get_actual_position = gpio_stepper_get_actual_position, diff --git a/drivers/stepper/stepper_shell.c b/drivers/stepper/stepper_shell.c index 76217cba9da..8aabc523a5f 100644 --- a/drivers/stepper/stepper_shell.c +++ b/drivers/stepper/stepper_shell.c @@ -190,7 +190,7 @@ static int cmd_stepper_enable(const struct shell *sh, size_t argc, char **argv) return err; } -static int cmd_stepper_move(const struct shell *sh, size_t argc, char **argv) +static int cmd_stepper_move_by(const struct shell *sh, size_t argc, char **argv) { const struct device *dev; int err = 0; @@ -211,7 +211,7 @@ static int cmd_stepper_move(const struct shell *sh, size_t argc, char **argv) shell_error(sh, "Failed to set callback: %d", err); } - err = stepper_move(dev, micro_steps); + err = stepper_move_by(dev, micro_steps); if (err) { shell_error(sh, "Error: %d", err); } @@ -453,8 +453,8 @@ SHELL_STATIC_SUBCMD_SET_CREATE( stepper_cmds, SHELL_CMD_ARG(enable, &dsub_pos_stepper_motor_name, " ", cmd_stepper_enable, 3, 0), - SHELL_CMD_ARG(move, &dsub_pos_stepper_motor_name, " ", - cmd_stepper_move, 3, 0), + SHELL_CMD_ARG(move_by, &dsub_pos_stepper_motor_name, " ", + cmd_stepper_move_by, 3, 0), SHELL_CMD_ARG(set_max_velocity, &dsub_pos_stepper_motor_name, " ", cmd_stepper_set_max_velocity, 3, 0), SHELL_CMD_ARG(set_micro_step_res, &dsub_pos_stepper_motor_name_microstep, diff --git a/include/zephyr/drivers/stepper.h b/include/zephyr/drivers/stepper.h index d7013b642ce..d2b27d633bf 100644 --- a/include/zephyr/drivers/stepper.h +++ b/include/zephyr/drivers/stepper.h @@ -106,11 +106,11 @@ enum stepper_event { typedef int (*stepper_enable_t)(const struct device *dev, const bool enable); /** - * @brief Move the stepper motor by a given number of micro_steps. + * @brief Move the stepper motor relatively by a given number of micro_steps. * - * @see stepper_move() for details. + * @see stepper_move_by() for details. */ -typedef int (*stepper_move_t)(const struct device *dev, const int32_t micro_steps); +typedef int (*stepper_move_by_t)(const struct device *dev, const int32_t micro_steps); /** * @brief Set the max velocity in micro_steps per seconds. @@ -190,7 +190,7 @@ typedef int (*stepper_set_event_callback_t)(const struct device *dev, */ __subsystem struct stepper_driver_api { stepper_enable_t enable; - stepper_move_t move; + stepper_move_by_t move_by; stepper_set_max_velocity_t set_max_velocity; stepper_set_micro_step_res_t set_micro_step_res; stepper_get_micro_step_res_t get_micro_step_res; @@ -227,19 +227,22 @@ static inline int z_impl_stepper_enable(const struct device *dev, const bool ena /** * @brief Set the micro_steps to be moved from the current position i.e. relative movement * + * @details The motor will move by the given number of micro_steps from the current position. + * This function is non-blocking. + * * @param dev pointer to the stepper motor controller instance * @param micro_steps target micro_steps to be moved from the current position * * @retval -EIO General input / output error * @retval 0 Success */ -__syscall int stepper_move(const struct device *dev, int32_t micro_steps); +__syscall int stepper_move_by(const struct device *dev, int32_t micro_steps); -static inline int z_impl_stepper_move(const struct device *dev, const int32_t micro_steps) +static inline int z_impl_stepper_move_by(const struct device *dev, const int32_t micro_steps) { const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api; - return api->move(dev, micro_steps); + return api->move_by(dev, micro_steps); } /** @@ -411,6 +414,7 @@ static inline int z_impl_stepper_is_moving(const struct device *dev, bool *is_mo * * @details If velocity > 0, motor shall be set into motion and run incessantly until and unless * stalled or stopped using some other command, for instance, motor_enable(false). + * This function is non-blocking. * * @param dev pointer to the stepper motor controller instance * @param direction The direction to set diff --git a/include/zephyr/drivers/stepper/stepper_fake.h b/include/zephyr/drivers/stepper/stepper_fake.h index 33b19edd99c..f182504d08e 100644 --- a/include/zephyr/drivers/stepper/stepper_fake.h +++ b/include/zephyr/drivers/stepper/stepper_fake.h @@ -16,7 +16,7 @@ extern "C" { DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_enable, const struct device *, bool); -DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_move, const struct device *, int32_t); +DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_move_by, const struct device *, int32_t); DECLARE_FAKE_VALUE_FUNC(int, fake_stepper_set_max_velocity, const struct device *, uint32_t); diff --git a/tests/drivers/stepper/shell/src/main.c b/tests/drivers/stepper/shell/src/main.c index be8671239fe..ec17ae01297 100644 --- a/tests/drivers/stepper/shell/src/main.c +++ b/tests/drivers/stepper/shell/src/main.c @@ -55,13 +55,13 @@ ZTEST(stepper_shell, test_stepper_enable) zassert_equal(fake_stepper_enable_fake.arg1_val, false, "wrong enable value"); } -ZTEST(stepper_shell, test_stepper_move) +ZTEST(stepper_shell, test_stepper_move_by) { const struct shell *sh = shell_backend_dummy_get_ptr(); - int err = shell_execute_cmd(sh, "stepper move " FAKE_STEPPER_NAME " 1000"); + int err = shell_execute_cmd(sh, "stepper move_by " FAKE_STEPPER_NAME " 1000"); - ASSERT_STEPPER_FUNC_CALLED(fake_stepper_move_fake, err); - zassert_equal(fake_stepper_move_fake.arg1_val, 1000, "wrong microsteps value"); + ASSERT_STEPPER_FUNC_CALLED(fake_stepper_move_by_fake, err); + zassert_equal(fake_stepper_move_by_fake.arg1_val, 1000, "wrong microsteps value"); } ZTEST(stepper_shell, test_stepper_set_max_velocity)