diff --git a/include/zephyr/drivers/stepper.h b/include/zephyr/drivers/stepper.h index 00c67f08df5..306862ed09e 100644 --- a/include/zephyr/drivers/stepper.h +++ b/include/zephyr/drivers/stepper.h @@ -36,26 +36,26 @@ extern "C" { #define MICRO_STEP_RES_INDEX(res) LOG2(res) /** - * @brief Stepper Motor microstep resolution options + * @brief Stepper Motor micro-step resolution options */ enum stepper_micro_step_resolution { /** Full step resolution */ STEPPER_MICRO_STEP_1 = 1, - /** 2 microsteps per full step */ + /** 2 micro-steps per full step */ STEPPER_MICRO_STEP_2 = 2, - /** 4 microsteps per full step */ + /** 4 micro-steps per full step */ STEPPER_MICRO_STEP_4 = 4, - /** 8 microsteps per full step */ + /** 8 micro-steps per full step */ STEPPER_MICRO_STEP_8 = 8, - /** 16 microsteps per full step */ + /** 16 micro-steps per full step */ STEPPER_MICRO_STEP_16 = 16, - /** 32 microsteps per full step */ + /** 32 micro-steps per full step */ STEPPER_MICRO_STEP_32 = 32, - /** 64 microsteps per full step */ + /** 64 micro-steps per full step */ STEPPER_MICRO_STEP_64 = 64, - /** 128 microsteps per full step */ + /** 128 micro-steps per full step */ STEPPER_MICRO_STEP_128 = 128, - /** 256 microsteps per full step */ + /** 256 micro-steps per full step */ STEPPER_MICRO_STEP_256 = 256, }; @@ -98,32 +98,17 @@ enum stepper_event { /** * @cond INTERNAL_HIDDEN * - * Stepper motor controller driver API definition and system call entry points. + * Stepper driver API definition and system call entry points. * */ /** - * @brief enable or disable the stepper motor controller. + * @brief enable or disable the stepper driver. * * @see stepper_enable() for details. */ typedef int (*stepper_enable_t)(const struct device *dev, const bool enable); -/** - * @brief Move the stepper motor relatively by a given number of microsteps. - * - * @see stepper_move_by() for details. - */ -typedef int (*stepper_move_by_t)(const struct device *dev, const int32_t micro_steps); - -/** - * @brief Set the time interval between steps in nanoseconds. - * - * @see stepper_set_microstep_interval() for details. - */ -typedef int (*stepper_set_microstep_interval_t)(const struct device *dev, - const uint64_t microstep_interval_ns); - /** * @brief Set the micro-step resolution * @@ -154,18 +139,38 @@ typedef int (*stepper_set_reference_position_t)(const struct device *dev, const typedef int (*stepper_get_actual_position_t)(const struct device *dev, int32_t *value); /** - * @brief Move the stepper motor to an absolute position in microsteps. + * @brief Callback function for stepper events + */ +typedef void (*stepper_event_callback_t)(const struct device *dev, const enum stepper_event event, + void *user_data); + +/** + * @brief Set the callback function to be called when a stepper event occurs * - * @see stepper_move_to() for details. + * @see stepper_set_event_callback() for details. */ -typedef int (*stepper_move_to_t)(const struct device *dev, const int32_t micro_steps); +typedef int (*stepper_set_event_callback_t)(const struct device *dev, + stepper_event_callback_t callback, void *user_data); +/** + * @brief Set the time interval between steps in nanoseconds. + * + * @see stepper_set_microstep_interval() for details. + */ +typedef int (*stepper_set_microstep_interval_t)(const struct device *dev, + const uint64_t microstep_interval_ns); +/** + * @brief Move the stepper relatively by a given number of micro-steps. + * + * @see stepper_move_by() for details. + */ +typedef int (*stepper_move_by_t)(const struct device *dev, const int32_t micro_steps); /** - * @brief Is the target position fo the stepper reached + * @brief Move the stepper to an absolute position in micro-steps. * - * @see stepper_is_moving() for details. + * @see stepper_move_to() for details. */ -typedef int (*stepper_is_moving_t)(const struct device *dev, bool *is_moving); +typedef int (*stepper_move_to_t)(const struct device *dev, const int32_t micro_steps); /** * @brief Run the stepper with a given step interval in a given direction @@ -175,34 +180,27 @@ typedef int (*stepper_is_moving_t)(const struct device *dev, bool *is_moving); typedef int (*stepper_run_t)(const struct device *dev, const enum stepper_direction direction); /** - * @brief Callback function for stepper events - */ -typedef void (*stepper_event_callback_t)(const struct device *dev, const enum stepper_event event, - void *user_data); - -/** - * @brief Set the callback function to be called when a stepper event occurs + * @brief Is the target position fo the stepper reached * - * @see stepper_set_event_callback() for details. + * @see stepper_is_moving() for details. */ -typedef int (*stepper_set_event_callback_t)(const struct device *dev, - stepper_event_callback_t callback, void *user_data); +typedef int (*stepper_is_moving_t)(const struct device *dev, bool *is_moving); /** - * @brief Stepper Motor Controller API + * @brief Stepper Driver API */ __subsystem struct stepper_driver_api { stepper_enable_t enable; - stepper_move_by_t move_by; - stepper_set_microstep_interval_t set_microstep_interval; stepper_set_micro_step_res_t set_micro_step_res; stepper_get_micro_step_res_t get_micro_step_res; stepper_set_reference_position_t set_reference_position; stepper_get_actual_position_t get_actual_position; + stepper_set_event_callback_t set_event_callback; + stepper_set_microstep_interval_t set_microstep_interval; + stepper_move_by_t move_by; stepper_move_to_t move_to; - stepper_is_moving_t is_moving; stepper_run_t run; - stepper_set_event_callback_t set_event_callback; + stepper_is_moving_t is_moving; }; /** @@ -210,10 +208,13 @@ __subsystem struct stepper_driver_api { */ /** - * @brief Enable or disable motor controller + * @brief Enable or disable stepper driver + * + * @details Enabling the driver will energize the coils, however not set the stepper in motion. + * Disabling the driver will de-energize the coils. * - * @param dev pointer to the stepper motor controller instance - * @param enable Input enable or disable motor controller + * @param dev pointer to the stepper driver instance + * @param enable Input enable or disable stepper driver * * @retval -EIO Error during Enabling * @retval 0 Success @@ -228,62 +229,10 @@ static inline int z_impl_stepper_enable(const struct device *dev, const bool ena } /** - * @brief Set the microsteps to be moved from the current position i.e. relative movement - * - * @details The motor will move by the given number of microsteps from the current position. - * This function is non-blocking. + * @brief Set the micro-step resolution in stepper driver * - * @param dev pointer to the stepper motor controller instance - * @param micro_steps target microsteps to be moved from the current position - * - * @retval -ECANCELED If the stepper is disabled - * @retval -EIO General input / output error - * @retval 0 Success - */ -__syscall int stepper_move_by(const struct device *dev, 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_by(dev, micro_steps); -} - -/** - * @brief Set the time interval between steps in microseconds - * - * @details For controllers such as DRV8825 where you - * toggle the STEP Pin, the pulse_length would have to be calculated based on this parameter in the - * driver. - * @note Setting step interval does not set the motor into motion, a combination of - * set_microstep_interval and move is required to set the motor into motion. - * - * @param dev pointer to the stepper motor controller instance - * @param microstep_interval_ns time interval between steps in microseconds - * - * @retval -EIO General input / output error - * @retval -EINVAL If the requested step interval is not supported - * @retval 0 Success - */ -__syscall int stepper_set_microstep_interval(const struct device *dev, - uint64_t microstep_interval_ns); - -static inline int z_impl_stepper_set_microstep_interval(const struct device *dev, - const uint64_t microstep_interval_ns) -{ - const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api; - - if (api->set_microstep_interval == NULL) { - return -ENOSYS; - } - return api->set_microstep_interval(dev, microstep_interval_ns); -} - -/** - * @brief Set the microstep resolution in stepper motor controller - * - * @param dev pointer to the stepper motor controller instance - * @param resolution microstep resolution + * @param dev pointer to the stepper driver instance + * @param resolution micro-step resolution * * @retval -EIO General input / output error * @retval -ENOSYS If not implemented by device driver @@ -305,10 +254,10 @@ static inline int z_impl_stepper_set_micro_step_res(const struct device *dev, } /** - * @brief Get the microstep resolution in stepper motor controller + * @brief Get the micro-step resolution in stepper driver * - * @param dev pointer to the stepper motor controller instance - * @param resolution microstep resolution + * @param dev pointer to the stepper driver instance + * @param resolution micro-step resolution * * @retval -EIO General input / output error * @retval -ENOSYS If not implemented by device driver @@ -331,7 +280,7 @@ static inline int z_impl_stepper_get_micro_step_res(const struct device *dev, /** * @brief Set the reference position of the stepper * - * @param dev Pointer to the stepper motor controller instance. + * @param dev Pointer to the stepper driver instance. * @param value The reference position to set in micro-steps. * * @retval -EIO General input / output error @@ -354,8 +303,8 @@ static inline int z_impl_stepper_set_reference_position(const struct device *dev /** * @brief Get the actual a.k.a reference position of the stepper * - * @param dev pointer to the stepper motor controller instance - * @param value The actual position to get in microsteps + * @param dev pointer to the stepper driver instance + * @param value The actual position to get in micro-steps * * @retval -EIO General input / output error * @retval -ENOSYS If not implemented by device driver @@ -374,61 +323,115 @@ static inline int z_impl_stepper_get_actual_position(const struct device *dev, i } /** - * @brief Set the absolute target position of the stepper + * @brief Set the callback function to be called when a stepper event occurs * - * @details The motor will move to the given microsteps position from the reference position. - * This function is non-blocking. + * @param dev pointer to the stepper driver instance + * @param callback Callback function to be called when a stepper event occurs + * passing NULL will disable the callback + * @param user_data User data to be passed to the callback function * - * @param dev pointer to the stepper motor controller instance - * @param micro_steps target position to set in microsteps + * @retval -ENOSYS If not implemented by device driver + * @retval 0 Success + */ +__syscall int stepper_set_event_callback(const struct device *dev, + stepper_event_callback_t callback, void *user_data); + +static inline int z_impl_stepper_set_event_callback(const struct device *dev, + stepper_event_callback_t callback, + void *user_data) +{ + const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api; + + if (api->set_event_callback == NULL) { + return -ENOSYS; + } + return api->set_event_callback(dev, callback, user_data); +} + +/** + * @brief Set the time interval between steps in nanoseconds + * + * @note Setting step interval does not set the stepper into motion, a combination of + * set_microstep_interval and move is required to set the stepper into motion. + * + * @param dev pointer to the stepper driver instance + * @param microstep_interval_ns time interval between steps in nanoseconds * - * @retval -ECANCELED If the stepper is disabled * @retval -EIO General input / output error + * @retval -EINVAL If the requested step interval is not supported * @retval -ENOSYS If not implemented by device driver * @retval 0 Success */ -__syscall int stepper_move_to(const struct device *dev, int32_t micro_steps); +__syscall int stepper_set_microstep_interval(const struct device *dev, + uint64_t microstep_interval_ns); -static inline int z_impl_stepper_move_to(const struct device *dev, const int32_t micro_steps) +static inline int z_impl_stepper_set_microstep_interval(const struct device *dev, + const uint64_t microstep_interval_ns) { const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api; - if (api->move_to == NULL) { + if (api->set_microstep_interval == NULL) { return -ENOSYS; } - return api->move_to(dev, micro_steps); + return api->set_microstep_interval(dev, microstep_interval_ns); +} + +/** + * @brief Set the micro-steps to be moved from the current position i.e. relative movement + * + * @details The stepper will move by the given number of micro-steps from the current position. + * This function is non-blocking. + * + * @param dev pointer to the stepper driver instance + * @param micro_steps target micro-steps to be moved from the current position + * + * @retval -ECANCELED If the stepper is disabled + * @retval -EIO General input / output error + * @retval 0 Success + */ +__syscall int stepper_move_by(const struct device *dev, 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_by(dev, micro_steps); } /** - * @brief Check if the stepper motor is currently moving + * @brief Set the absolute target position of the stepper + * + * @details The stepper will move to the given micro-steps position from the reference position. + * This function is non-blocking. * - * @param dev pointer to the stepper motor controller instance - * @param is_moving Pointer to a boolean to store the moving status of the stepper motor + * @param dev pointer to the stepper driver instance + * @param micro_steps target position to set in micro-steps * + * @retval -ECANCELED If the stepper is disabled * @retval -EIO General input / output error * @retval -ENOSYS If not implemented by device driver * @retval 0 Success */ -__syscall int stepper_is_moving(const struct device *dev, bool *is_moving); +__syscall int stepper_move_to(const struct device *dev, int32_t micro_steps); -static inline int z_impl_stepper_is_moving(const struct device *dev, bool *is_moving) +static inline int z_impl_stepper_move_to(const struct device *dev, const int32_t micro_steps) { const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api; - if (api->is_moving == NULL) { + if (api->move_to == NULL) { return -ENOSYS; } - return api->is_moving(dev, is_moving); + return api->move_to(dev, micro_steps); } /** * @brief Run the stepper with a given step interval in a given direction * - * @details The motor shall be set into motion and run continuously until - * stalled or stopped using some other command, for instance, motor_enable(false). This + * @details The stepper shall be set into motion and run continuously until + * stalled or stopped using some other command, for instance, stepper_enable(false). This * function is non-blocking. * - * @param dev pointer to the stepper motor controller instance + * @param dev pointer to the stepper driver instance * @param direction The direction to set * * @retval -ECANCELED If the stepper is disabled @@ -450,29 +453,25 @@ static inline int z_impl_stepper_run(const struct device *dev, } /** - * @brief Set the callback function to be called when a stepper event occurs + * @brief Check if the stepper is currently moving * - * @param dev pointer to the stepper motor controller instance - * @param callback Callback function to be called when a stepper event occurs - * passing NULL will disable the callback - * @param user_data User data to be passed to the callback function + * @param dev pointer to the stepper driver instance + * @param is_moving Pointer to a boolean to store the moving status of the stepper * + * @retval -EIO General input / output error * @retval -ENOSYS If not implemented by device driver * @retval 0 Success */ -__syscall int stepper_set_event_callback(const struct device *dev, - stepper_event_callback_t callback, void *user_data); +__syscall int stepper_is_moving(const struct device *dev, bool *is_moving); -static inline int z_impl_stepper_set_event_callback(const struct device *dev, - stepper_event_callback_t callback, - void *user_data) +static inline int z_impl_stepper_is_moving(const struct device *dev, bool *is_moving) { const struct stepper_driver_api *api = (const struct stepper_driver_api *)dev->api; - if (api->set_event_callback == NULL) { + if (api->is_moving == NULL) { return -ENOSYS; } - return api->set_event_callback(dev, callback, user_data); + return api->is_moving(dev, is_moving); } /**