1 /*
2  * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: CC0-1.0
5  */
6 
7 #pragma once
8 
9 #include <stdbool.h>
10 #include "driver/rmt.h"
11 #include "hal/rmt_types.h"
12 #include "esp_err.h"
13 #include "step_motor_driver_io.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 /**
20  * @brief Type of step motor interface
21  */
22 typedef struct step_motor_s step_motor_t;
23 
24 typedef step_motor_t *step_motor_handle_t;
25 
26 /**
27  * @brief Declaration of step motor interface
28  *
29  */
30 struct step_motor_s {
31     esp_err_t (*init)(step_motor_t *handle);
32     esp_err_t (*deinit)(step_motor_t *handle);
33     esp_err_t (*step)(step_motor_t *handle, uint32_t n, uint32_t speed);
34     esp_err_t (*smooth_step)(step_motor_t *handle, uint32_t n, uint32_t speed_steps, uint32_t speed_min, uint32_t speed_max);
35     esp_err_t (*set_step)(step_motor_t *handle, uint16_t microstep, bool direction);
36 
37     // TODO: other API like sleep, enable_output, reset
38 };
39 
40 /**
41  * @brief Initialize step motor driver
42  *
43  * @param handle driver handle
44  * @return
45  *      - ESP_OK: successfully initialized
46  *      - ESP_ERR_INVALID_ARG: wrong parameter
47  */
48 esp_err_t step_motor_init(step_motor_t *handle);
49 
50 /**
51  * @brief Deinitialize driver
52  *
53  * @param handle driver handle
54  * @return
55  *      - ESP_OK: Stop playing successfully
56  */
57 esp_err_t step_motor_deinit(step_motor_t *handle);
58 
59 /**
60  * @brief Move n small steps.
61  *
62  * @note Will block until finish if n is finite steps. But will immediately return if n is UINT32_MAX.
63  *
64  * @param handle driver handle
65  * @param n step count, UINT32_MAX for unlimited, 0 to stop
66  * @param speed steps per second
67  * @return
68  *      - ESP_OK: Recycle memory successfully
69  */
70 esp_err_t step_motor_step(step_motor_t *handle, uint32_t n, uint32_t speed);
71 
72 /**
73  * @brief Move n small steps. Always blocking and take smooth arguments
74  *
75  *  ^ speed (steps/s)
76  *  |                         *********************                       <---- speed_max
77  *  |                   *     |                   |     *
78  *  |               *         |                   |         *
79  *  |             *           |                   |           *
80  *  |            *            |                   |            *
81  *  |          *     speed    |  n-speed_steps*2  |    speed     *
82  *  |      *         steps    |                   |    steps         *    <---- speed_min
83  *  |                         |                   |
84  *  +-------------------------------------------------------------------> timestamp (s)
85  *
86  * @param handle driver handle
87  * @param n steps
88  * @param speed_steps number of sample points during speed smoothing
89  * @param speed_min minimal speed, steps per seconds
90  * @param speed_max maximum speed, steps per seconds
91  * @note may consume lots of ram depending on speed_steps with current implementation (1000 will lead to 8kb of ram usage)
92  * @return
93  *      - ESP_OK: Recycle memory successfully
94  */
95 esp_err_t step_motor_smooth_step(step_motor_t *handle, uint32_t n, uint32_t speed_steps, uint32_t speed_min, uint32_t speed_max);
96 
97 /**
98  * @brief Set microstep resolution
99  *
100  * @param handle driver handle
101  * @param step_config microstep resolution
102  * @param direction rotating direction
103  * @return
104  *      - ESP_OK: Recycle memory successfully
105  */
106 esp_err_t step_motor_set_step(step_motor_t *handle, uint16_t microstep, bool direction);
107 
108 
109 // TODO: move out of this header to rmt one (like step_motor_rmt.h)
110 /**
111  * @brief Create step motor instance based on RMT driver
112  *
113  * @param[in] io_driver step motor low part driver
114  * @param[out] ret_handle returned handle of step motor instance
115  * @return
116  *      - ESP_OK: create step motor instance successfully
117  *      - ESP_ERR_INVALID_ARG: wrong parameter
118  *      - ESP_ERR_NO_MEM: no memory to allocate instance
119  */
120 esp_err_t step_motor_create_rmt(step_motor_driver_io_t *io_driver, const rmt_config_t *rmt_conf, step_motor_handle_t *ret_handle);
121 
122 /**
123  * @brief Delete step motor instance that previously created
124  *
125  * @param[in] handle step motor instance to be deleted
126  * @return
127  *      - ESP_OK: create step motor instance successfully
128  *      - ESP_ERR_INVALID_ARG: wrong parameter
129  */
130 esp_err_t step_motor_delete_rmt(step_motor_handle_t handle);
131 
132 #ifdef __cplusplus
133 }
134 #endif
135