1 // Copyright 2016-2020 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #include "touch_element/touch_element.h" 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 /* --------------------------------- General button instance default configuration --------------------------------- */ 23 #define TOUCH_BUTTON_GLOBAL_DEFAULT_CONFIG() \ 24 { \ 25 .threshold_divider = 0.8, \ 26 .default_lp_time = 1000 \ 27 } 28 /* ------------------------------------------------------------------------------------------------------------------ */ 29 30 /** 31 * @brief Button initialization configuration passed to touch_button_install 32 */ 33 typedef struct { 34 float threshold_divider; //!< Button channel threshold divider 35 uint32_t default_lp_time; //!< Button default LongPress event time (ms) 36 } touch_button_global_config_t; 37 38 /** 39 * @brief Button configuration (for new instance) passed to touch_button_create() 40 */ 41 typedef struct { 42 touch_pad_t channel_num; //!< Button channel number (index) 43 float channel_sens; //!< Button channel sensitivity 44 } touch_button_config_t; 45 46 /** 47 * @brief Button event type 48 */ 49 typedef enum { 50 TOUCH_BUTTON_EVT_ON_PRESS, //!< Button Press event 51 TOUCH_BUTTON_EVT_ON_RELEASE, //!< Button Release event 52 TOUCH_BUTTON_EVT_ON_LONGPRESS, //!< Button LongPress event 53 TOUCH_BUTTON_EVT_MAX 54 } touch_button_event_t; 55 56 /** 57 * @brief Button message type 58 */ 59 typedef struct { 60 touch_button_event_t event; //!< Button event 61 } touch_button_message_t; 62 63 typedef touch_elem_handle_t touch_button_handle_t; //!< Button handle 64 typedef void(*touch_button_callback_t)(touch_button_handle_t, touch_button_message_t *, void *); //!< Button callback type 65 66 /** 67 * @brief Touch Button initialize 68 * 69 * This function initializes touch button global and acts on all 70 * touch button instances. 71 * 72 * @param[in] global_config Button object initialization configuration 73 * 74 * @return 75 * - ESP_OK: Successfully initialized touch button 76 * - ESP_ERR_INVALID_STATE: Touch element library was not initialized 77 * - ESP_ERR_INVALID_ARG: button_init is NULL 78 * - ESP_ERR_NO_MEM: Insufficient memory 79 */ 80 esp_err_t touch_button_install(const touch_button_global_config_t *global_config); 81 82 /** 83 * @brief Release resources allocated using touch_button_install() 84 */ 85 void touch_button_uninstall(void); 86 87 /** 88 * @brief Create a new touch button instance 89 * 90 * @param[in] button_config Button configuration 91 * @param[out] button_handle Button handle 92 * 93 * @note The sensitivity has to be explored in experiments, 94 * Sensitivity = (Raw(touch) - Raw(release)) / Raw(release) * 100% 95 * 96 * @return 97 * - ESP_OK: Successfully create touch button 98 * - ESP_ERR_INVALID_STATE: Touch button driver was not initialized 99 * - ESP_ERR_NO_MEM: Insufficient memory 100 * - ESP_ERR_INVALID_ARG: Invalid configuration struct or arguments is NULL 101 */ 102 esp_err_t touch_button_create(const touch_button_config_t *button_config, touch_button_handle_t *button_handle); 103 104 /** 105 * @brief Release resources allocated using touch_button_create() 106 * 107 * @param[in] button_handle Button handle 108 * @return 109 * - ESP_OK: Successfully released resources 110 * - ESP_ERR_INVALID_STATE: Touch button driver was not initialized 111 * - ESP_ERR_INVALID_ARG: button_handle is null 112 * - ESP_ERR_NOT_FOUND: Input handle is not a button handle 113 */ 114 esp_err_t touch_button_delete(touch_button_handle_t button_handle); 115 116 /** 117 * @brief Touch button subscribes event 118 * 119 * This function uses event mask to subscribe to touch button events, once one of 120 * the subscribed events occurs, the event message could be retrieved by calling 121 * touch_element_message_receive() or input callback routine. 122 * 123 * @param[in] button_handle Button handle 124 * @param[in] event_mask Button subscription event mask 125 * @param[in] arg User input argument 126 * 127 * @note Touch button only support three kind of event masks, they are 128 * TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE, TOUCH_ELEM_EVENT_ON_LONGPRESS. 129 * You can use those event masks in any combination to achieve the desired effect. 130 * 131 * @return 132 * - ESP_OK: Successfully subscribed touch button event 133 * - ESP_ERR_INVALID_STATE: Touch button driver was not initialized 134 * - ESP_ERR_INVALID_ARG: button_handle is null or event is not supported 135 */ 136 esp_err_t touch_button_subscribe_event(touch_button_handle_t button_handle, uint32_t event_mask, void *arg); 137 138 /** 139 * @brief Touch button set dispatch method 140 * 141 * This function sets a dispatch method that the driver core will use 142 * this method as the event notification method. 143 * 144 * @param[in] button_handle Button handle 145 * @param[in] dispatch_method Dispatch method (By callback/event) 146 * 147 * @return 148 * - ESP_OK: Successfully set dispatch method 149 * - ESP_ERR_INVALID_STATE: Touch button driver was not initialized 150 * - ESP_ERR_INVALID_ARG: button_handle is null or dispatch_method is invalid 151 */ 152 esp_err_t touch_button_set_dispatch_method(touch_button_handle_t button_handle, touch_elem_dispatch_t dispatch_method); 153 154 /** 155 * @brief Touch button set callback 156 * 157 * This function sets a callback routine into touch element driver core, 158 * when the subscribed events occur, the callback routine will be called. 159 * 160 * @param[in] button_handle Button handle 161 * @param[in] button_callback User input callback 162 * 163 * @note Button message will be passed from the callback function and it will be destroyed when the callback function return. 164 * 165 * @warning Since this input callback routine runs on driver core (esp-timer callback routine), 166 * it should not do something that attempts to Block, such as calling vTaskDelay(). 167 * 168 * @return 169 * - ESP_OK: Successfully set callback 170 * - ESP_ERR_INVALID_STATE: Touch button driver was not initialized 171 * - ESP_ERR_INVALID_ARG: button_handle or button_callback is null 172 */ 173 esp_err_t touch_button_set_callback(touch_button_handle_t button_handle, touch_button_callback_t button_callback); 174 175 /** 176 * @brief Touch button set long press trigger time 177 * 178 * This function sets the threshold time (ms) for a long press event. If a button is pressed 179 * and held for a period of time that exceeds the threshold time, a long press event is triggered. 180 * 181 * @param[in] button_handle Button handle 182 * @param[in] threshold_time Threshold time (ms) of long press event occur 183 * 184 * @return 185 * - ESP_OK: Successfully set the threshold time of long press event 186 * - ESP_ERR_INVALID_STATE: Touch button driver was not initialized 187 * - ESP_ERR_INVALID_ARG: button_handle is null or time (ms) is not lager than 0 188 */ 189 esp_err_t touch_button_set_longpress(touch_button_handle_t button_handle, uint32_t threshold_time); 190 191 /** 192 * @brief Touch button get message 193 * 194 * This function decodes the element message from touch_element_message_receive() and return 195 * a button message pointer. 196 * 197 * @param[in] element_message element message 198 * 199 * @return Touch button message pointer 200 */ 201 const touch_button_message_t* touch_button_get_message(const touch_elem_message_t* element_message); 202 203 #ifdef __cplusplus 204 } 205 #endif 206
