1 /* 2 * Copyright 2024 Fabian Blatz <fabianblatz@gmail.com> 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_DRIVER_STEPPER_STEP_DIR_STEPPER_COMMON_H_ 8 #define ZEPHYR_DRIVER_STEPPER_STEP_DIR_STEPPER_COMMON_H_ 9 10 /** 11 * @brief Stepper Driver APIs 12 * @defgroup step_dir_stepper Stepper Driver APIs 13 * @ingroup io_interfaces 14 * @{ 15 */ 16 17 #include <zephyr/device.h> 18 #include <zephyr/drivers/gpio.h> 19 #include <zephyr/drivers/stepper.h> 20 #include <zephyr/drivers/counter.h> 21 22 #include "step_dir_stepper_timing_source.h" 23 24 /** 25 * @brief Common step direction stepper config. 26 * 27 * This structure **must** be placed first in the driver's config structure. 28 */ 29 struct step_dir_stepper_common_config { 30 const struct gpio_dt_spec step_pin; 31 const struct gpio_dt_spec dir_pin; 32 bool dual_edge; 33 const struct stepper_timing_source_api *timing_source; 34 const struct device *counter; 35 }; 36 37 /** 38 * @brief Initialize common step direction stepper config from devicetree instance. 39 * If the counter property is set, the timing source will be set to the counter timing 40 * source. 41 * 42 * @param node_id The devicetree node identifier. 43 */ 44 #define STEP_DIR_STEPPER_DT_COMMON_CONFIG_INIT(node_id) \ 45 { \ 46 .step_pin = GPIO_DT_SPEC_GET(node_id, step_gpios), \ 47 .dir_pin = GPIO_DT_SPEC_GET(node_id, dir_gpios), \ 48 .dual_edge = DT_PROP_OR(node_id, dual_edge_step, false), \ 49 .counter = DEVICE_DT_GET_OR_NULL(DT_PHANDLE(node_id, counter)), \ 50 .timing_source = COND_CODE_1(DT_NODE_HAS_PROP(node_id, counter), \ 51 (&step_counter_timing_source_api), \ 52 (&step_work_timing_source_api)), \ 53 } 54 55 /** 56 * @brief Initialize common step direction stepper config from devicetree instance. 57 * @param inst Instance. 58 */ 59 #define STEP_DIR_STEPPER_DT_INST_COMMON_CONFIG_INIT(inst) \ 60 STEP_DIR_STEPPER_DT_COMMON_CONFIG_INIT(DT_DRV_INST(inst)) 61 62 /** 63 * @brief Common step direction stepper data. 64 * 65 * This structure **must** be placed first in the driver's data structure. 66 */ 67 struct step_dir_stepper_common_data { 68 const struct device *dev; 69 struct k_spinlock lock; 70 enum stepper_direction direction; 71 enum stepper_run_mode run_mode; 72 int32_t actual_position; 73 uint64_t microstep_interval_ns; 74 int32_t step_count; 75 stepper_event_callback_t callback; 76 void *event_cb_user_data; 77 78 struct k_work_delayable stepper_dwork; 79 80 #ifdef CONFIG_STEP_DIR_STEPPER_COUNTER_TIMING 81 struct counter_top_cfg counter_top_cfg; 82 bool counter_running; 83 #endif /* CONFIG_STEP_DIR_STEPPER_COUNTER_TIMING */ 84 85 #ifdef CONFIG_STEPPER_STEP_DIR_GENERATE_ISR_SAFE_EVENTS 86 struct k_work event_callback_work; 87 struct k_msgq event_msgq; 88 uint8_t event_msgq_buffer[CONFIG_STEPPER_STEP_DIR_EVENT_QUEUE_LEN * 89 sizeof(enum stepper_event)]; 90 #endif /* CONFIG_STEPPER_STEP_DIR_GENERATE_ISR_SAFE_EVENTS */ 91 }; 92 93 /** 94 * @brief Initialize common step direction stepper data from devicetree instance. 95 * 96 * @param node_id The devicetree node identifier. 97 */ 98 #define STEP_DIR_STEPPER_DT_COMMON_DATA_INIT(node_id) \ 99 { \ 100 .dev = DEVICE_DT_GET(node_id), \ 101 } 102 103 /** 104 * @brief Initialize common step direction stepper data from devicetree instance. 105 * @param inst Instance. 106 */ 107 #define STEP_DIR_STEPPER_DT_INST_COMMON_DATA_INIT(inst) \ 108 STEP_DIR_STEPPER_DT_COMMON_DATA_INIT(DT_DRV_INST(inst)) 109 110 /** 111 * @brief Validate the offset of the common data structures. 112 * 113 * @param config Name of the config structure. 114 * @param data Name of the data structure. 115 */ 116 #define STEP_DIR_STEPPER_STRUCT_CHECK(config, data) \ 117 BUILD_ASSERT(offsetof(config, common) == 0, \ 118 "struct step_dir_stepper_common_config must be placed first"); \ 119 BUILD_ASSERT(offsetof(data, common) == 0, \ 120 "struct step_dir_stepper_common_data must be placed first"); 121 122 /** 123 * @brief Common function to initialize a step direction stepper device at init time. 124 * 125 * This function must be called at the end of the device init function. 126 * 127 * @param dev Step direction stepper device instance. 128 * 129 * @retval 0 If initialized successfully. 130 * @retval -errno Negative errno in case of failure. 131 */ 132 int step_dir_stepper_common_init(const struct device *dev); 133 134 /** 135 * @brief Move the stepper motor by a given number of micro_steps. 136 * 137 * @param dev Pointer to the device structure. 138 * @param micro_steps Number of micro_steps to move. Can be positive or negative. 139 * @return 0 on success, or a negative error code on failure. 140 */ 141 int step_dir_stepper_common_move_by(const struct device *dev, const int32_t micro_steps); 142 143 /** 144 * @brief Set the step interval of the stepper motor. 145 * 146 * @param dev Pointer to the device structure. 147 * @param microstep_interval_ns The step interval in nanoseconds. 148 * @return 0 on success, or a negative error code on failure. 149 */ 150 int step_dir_stepper_common_set_microstep_interval(const struct device *dev, 151 const uint64_t microstep_interval_ns); 152 153 /** 154 * @brief Set the reference position of the stepper motor. 155 * 156 * @param dev Pointer to the device structure. 157 * @param value The reference position value to set. 158 * @return 0 on success, or a negative error code on failure. 159 */ 160 int step_dir_stepper_common_set_reference_position(const struct device *dev, const int32_t value); 161 162 /** 163 * @brief Get the actual (reference) position of the stepper motor. 164 * 165 * @param dev Pointer to the device structure. 166 * @param value Pointer to a variable where the position value will be stored. 167 * @return 0 on success, or a negative error code on failure. 168 */ 169 int step_dir_stepper_common_get_actual_position(const struct device *dev, int32_t *value); 170 171 /** 172 * @brief Set the absolute target position of the stepper motor. 173 * 174 * @param dev Pointer to the device structure. 175 * @param value The target position to set. 176 * @return 0 on success, or a negative error code on failure. 177 */ 178 int step_dir_stepper_common_move_to(const struct device *dev, const int32_t value); 179 180 /** 181 * @brief Check if the stepper motor is still moving. 182 * 183 * @param dev Pointer to the device structure. 184 * @param is_moving Pointer to a boolean where the movement status will be stored. 185 * @return 0 on success, or a negative error code on failure. 186 */ 187 int step_dir_stepper_common_is_moving(const struct device *dev, bool *is_moving); 188 189 /** 190 * @brief Run the stepper with a given direction and step interval. 191 * 192 * @param dev Pointer to the device structure. 193 * @param direction The direction of movement (positive or negative). 194 * @return 0 on success, or a negative error code on failure. 195 */ 196 int step_dir_stepper_common_run(const struct device *dev, const enum stepper_direction direction); 197 198 /** 199 * @brief Stop the stepper motor. 200 * 201 * @param dev Pointer to the device structure. 202 * @return 0 on success, or a negative error code on failure. 203 */ 204 int step_dir_stepper_common_stop(const struct device *dev); 205 206 /** 207 * @brief Set a callback function for stepper motor events. 208 * 209 * This function sets a user-defined callback that will be invoked when a stepper motor event 210 * occurs. 211 * 212 * @param dev Pointer to the device structure. 213 * @param callback The callback function to set. 214 * @param user_data Pointer to user-defined data that will be passed to the callback. 215 * @return 0 on success, or a negative error code on failure. 216 */ 217 int step_dir_stepper_common_set_event_callback(const struct device *dev, 218 stepper_event_callback_t callback, void *user_data); 219 220 /** 221 * @brief Handle a timing signal and update the stepper position. 222 * @param dev Pointer to the device structure. 223 */ 224 void stepper_handle_timing_signal(const struct device *dev); 225 226 /** @} */ 227 228 #endif /* ZEPHYR_DRIVER_STEPPER_STEP_DIR_STEPPER_COMMON_H_ */ 229
