/
iot_button.h
301 lines (272 loc) · 8.76 KB
/
iot_button.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
/* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include "button_adc.h"
#include "button_gpio.h"
#include "button_matrix.h"
#include "esp_err.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef void (* button_cb_t)(void *button_handle, void *usr_data);
typedef void *button_handle_t;
/**
* @brief Button events
*
*/
typedef enum {
BUTTON_PRESS_DOWN = 0,
BUTTON_PRESS_UP,
BUTTON_PRESS_REPEAT,
BUTTON_PRESS_REPEAT_DONE,
BUTTON_SINGLE_CLICK,
BUTTON_DOUBLE_CLICK,
BUTTON_MULTIPLE_CLICK,
BUTTON_LONG_PRESS_START,
BUTTON_LONG_PRESS_HOLD,
BUTTON_LONG_PRESS_UP,
BUTTON_EVENT_MAX,
BUTTON_NONE_PRESS,
} button_event_t;
/**
* @brief Button events data
*
*/
typedef union {
/**
* @brief Long press time event data
*
*/
struct long_press_t {
uint16_t press_time; /**< press time(ms) for the corresponding callback to trigger */
} long_press; /**< long press struct, for event BUTTON_LONG_PRESS_START and BUTTON_LONG_PRESS_UP */
/**
* @brief Multiple clicks event data
*
*/
struct multiple_clicks_t {
uint16_t clicks; /**< number of clicks, to trigger the callback */
} multiple_clicks; /**< multiple clicks struct, for event BUTTON_MULTIPLE_CLICK */
} button_event_data_t;
/**
* @brief Button events configuration
*
*/
typedef struct {
button_event_t event; /**< button event type */
button_event_data_t event_data; /**< event data corresponding to the event */
} button_event_config_t;
/**
* @brief Supported button type
*
*/
typedef enum {
BUTTON_TYPE_GPIO,
BUTTON_TYPE_ADC,
BUTTON_TYPE_MATRIX,
BUTTON_TYPE_CUSTOM
} button_type_t;
/**
* @brief Button parameter
*
*/
typedef enum {
BUTTON_LONG_PRESS_TIME_MS = 0,
BUTTON_SHORT_PRESS_TIME_MS,
BUTTON_PARAM_MAX,
} button_param_t;
/**
* @brief custom button configuration
*
*/
typedef struct {
uint8_t active_level; /**< active level when press down */
esp_err_t (*button_custom_init)(void *param); /**< user defined button init */
uint8_t (*button_custom_get_key_value)(void *param); /**< user defined button get key value */
esp_err_t (*button_custom_deinit)(void *param); /**< user defined button deinit */
void *priv; /**< private data used for custom button, MUST be allocated dynamically and will be auto freed in iot_button_delete*/
} button_custom_config_t;
/**
* @brief Button configuration
*
*/
typedef struct {
button_type_t type; /**< button type, The corresponding button configuration must be filled */
uint16_t long_press_time; /**< Trigger time(ms) for long press, if 0 default to BUTTON_LONG_PRESS_TIME_MS */
uint16_t short_press_time; /**< Trigger time(ms) for short press, if 0 default to BUTTON_SHORT_PRESS_TIME_MS */
union {
button_gpio_config_t gpio_button_config; /**< gpio button configuration */
button_adc_config_t adc_button_config; /**< adc button configuration */
button_matrix_config_t matrix_button_config; /**< matrix key button configuration */
button_custom_config_t custom_button_config; /**< custom button configuration */
}; /**< button configuration */
} button_config_t;
/**
* @brief Create a button
*
* @param config pointer of button configuration, must corresponding the button type
*
* @return A handle to the created button, or NULL in case of error.
*/
button_handle_t iot_button_create(const button_config_t *config);
/**
* @brief Delete a button
*
* @param btn_handle A button handle to delete
*
* @return
* - ESP_OK Success
* - ESP_FAIL Failure
*/
esp_err_t iot_button_delete(button_handle_t btn_handle);
/**
* @brief Register the button event callback function.
*
* @param btn_handle A button handle to register
* @param event Button event
* @param cb Callback function.
* @param usr_data user data
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG Arguments is invalid.
* - ESP_ERR_INVALID_STATE The Callback is already registered. No free Space for another Callback.
* - ESP_ERR_NO_MEM No more memory allocation for the event
*/
esp_err_t iot_button_register_cb(button_handle_t btn_handle, button_event_t event, button_cb_t cb, void *usr_data);
/**
* @brief Register the button event callback function.
*
* @param btn_handle A button handle to register
* @param event_cfg Button event configuration
* @param cb Callback function.
* @param usr_data user data
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG Arguments is invalid.
* - ESP_ERR_INVALID_STATE The Callback is already registered. No free Space for another Callback.
* - ESP_ERR_NO_MEM No more memory allocation for the event
*/
esp_err_t iot_button_register_event_cb(button_handle_t btn_handle, button_event_config_t event_cfg, button_cb_t cb, void *usr_data);
/**
* @brief Unregister the button event callback function.
* In case event_data is also passed it will unregister function for that particular event_data only.
*
* @param btn_handle A button handle to unregister
* @param event_cfg Button event
* @param cb callback to unregister
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG Arguments is invalid.
* - ESP_ERR_INVALID_STATE The Callback was never registered with the event
*/
esp_err_t iot_button_unregister_event(button_handle_t btn_handle, button_event_config_t event_cfg, button_cb_t cb);
/**
* @brief Unregister all the callbacks associated with the event.
*
* @param btn_handle A button handle to unregister
* @param event Button event
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG Arguments is invalid.
* - ESP_ERR_INVALID_STATE No callbacks registered for the event
*/
esp_err_t iot_button_unregister_cb(button_handle_t btn_handle, button_event_t event);
/**
* @brief counts total callbacks registered
*
* @param btn_handle A button handle to the button
*
* @return
* - 0 if no callbacks registered, or 1 .. (BUTTON_EVENT_MAX-1) for the number of Registered Buttons.
* - ESP_ERR_INVALID_ARG if btn_handle is invalid
*/
size_t iot_button_count_cb(button_handle_t btn_handle);
/**
* @brief how many callbacks are registered for the event
*
* @param btn_handle A button handle to the button
*
* @param event Button event
*
* @return
* - 0 if no callbacks registered, or 1 .. (BUTTON_EVENT_MAX-1) for the number of Registered Buttons.
* - ESP_ERR_INVALID_ARG if btn_handle is invalid
*/
size_t iot_button_count_event(button_handle_t btn_handle, button_event_t event);
/**
* @brief Get button event
*
* @param btn_handle Button handle
*
* @return Current button event. See button_event_t
*/
button_event_t iot_button_get_event(button_handle_t btn_handle);
/**
* @brief Get button repeat times
*
* @param btn_handle Button handle
*
* @return button pressed times. For example, double-click return 2, triple-click return 3, etc.
*/
uint8_t iot_button_get_repeat(button_handle_t btn_handle);
/**
* @brief Get button ticks time
*
* @param btn_handle Button handle
*
* @return Actual time from press down to up (ms).
*/
uint16_t iot_button_get_ticks_time(button_handle_t btn_handle);
/**
* @brief Get button long press hold count
*
* @param btn_handle Button handle
*
* @return Count of trigger cb(BUTTON_LONG_PRESS_HOLD)
*/
uint16_t iot_button_get_long_press_hold_cnt(button_handle_t btn_handle);
/**
* @brief Dynamically change the parameters of the iot button
*
* @param btn_handle Button handle
* @param param Button parameter
* @param value new value
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG Arguments is invalid.
*/
esp_err_t iot_button_set_param(button_handle_t btn_handle, button_param_t param, void *value);
/**
* @brief Get button key level
*
* @param btn_handle Button handle
* @return
* - 1 if key is pressed
* - 0 if key is released or invalid button handle
*/
uint8_t iot_button_get_key_level(button_handle_t btn_handle);
/**
* @brief resume button timer, if button timer is stopped. Make sure iot_button_create() is called before calling this API.
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE timer state is invalid.
*/
esp_err_t iot_button_resume(void);
/**
* @brief stop button timer, if button timer is running. Make sure iot_button_create() is called before calling this API.
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE timer state is invalid
*/
esp_err_t iot_button_stop(void);
#ifdef __cplusplus
}
#endif