iot_button.h 8.8 KB

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