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 23 /* ----------------------------- General matrix button instance default configuration ------------------------------ */ 24 #define TOUCH_MATRIX_GLOBAL_DEFAULT_CONFIG() \ 25 { \ 26 .threshold_divider = 0.8, \ 27 .default_lp_time = 1000 \ 28 } 29 /* ------------------------------------------------------------------------------------------------------------------ */ 30 /** 31 * @brief Matrix button initialization configuration passed to touch_matrix_install 32 */ 33 typedef struct { 34 float threshold_divider; //!< Matrix button channel threshold divider 35 uint32_t default_lp_time; //!< Matrix button default LongPress event time (ms) 36 } touch_matrix_global_config_t; 37 38 /** 39 * @brief Matrix button configuration (for new instance) passed to touch_matrix_create() 40 */ 41 typedef struct { 42 const touch_pad_t *x_channel_array; //!< Matrix button x-axis channels array 43 const touch_pad_t *y_channel_array; //!< Matrix button y-axis channels array 44 const float *x_sensitivity_array; //!< Matrix button x-axis channels sensitivity array 45 const float *y_sensitivity_array; //!< Matrix button y-axis channels sensitivity array 46 uint8_t x_channel_num; //!< The number of channels in x-axis 47 uint8_t y_channel_num; //!< The number of channels in y-axis 48 } touch_matrix_config_t; 49 50 /** 51 * @brief Matrix button event type 52 */ 53 typedef enum { 54 TOUCH_MATRIX_EVT_ON_PRESS, //!< Matrix button Press event 55 TOUCH_MATRIX_EVT_ON_RELEASE, //!< Matrix button Press event 56 TOUCH_MATRIX_EVT_ON_LONGPRESS, //!< Matrix button LongPress event 57 TOUCH_MATRIX_EVT_MAX 58 } touch_matrix_event_t; 59 60 /** 61 * @brief Matrix button position data type 62 */ 63 typedef struct { 64 uint8_t x_axis; //!< Matrix button x axis position 65 uint8_t y_axis; //!< Matrix button y axis position 66 uint8_t index; //!< Matrix button position index 67 } touch_matrix_position_t; 68 69 /** 70 * @brief Matrix message type 71 */ 72 typedef struct { 73 touch_matrix_event_t event; //!< Matrix event 74 touch_matrix_position_t position; //!< Matrix position 75 } touch_matrix_message_t; 76 77 typedef touch_elem_handle_t touch_matrix_handle_t; //!< Matrix button instance handle 78 typedef void(*touch_matrix_callback_t)(touch_matrix_handle_t, touch_matrix_message_t *, void *); //!< Matrix button callback type 79 80 /** 81 * @brief Touch matrix button initialize 82 * 83 * This function initializes touch matrix button object and acts on all 84 * touch matrix button instances. 85 * 86 * @param[in] global_config Touch matrix global initialization configuration 87 * 88 * @return 89 * - ESP_OK: Successfully initialized touch matrix button 90 * - ESP_ERR_INVALID_STATE: Touch element library was not initialized 91 * - ESP_ERR_INVALID_ARG: matrix_init is NULL 92 * - ESP_ERR_NO_MEM: Insufficient memory 93 */ 94 esp_err_t touch_matrix_install(const touch_matrix_global_config_t *global_config); 95 96 /** 97 * @brief Release resources allocated using touch_matrix_install() 98 * 99 * @return 100 * - ESP_OK: Successfully released resources 101 */ 102 void touch_matrix_uninstall(void); 103 104 /** 105 * @brief Create a new touch matrix button instance 106 * 107 * @param[in] matrix_config Matrix button configuration 108 * @param[out] matrix_handle Matrix button handle 109 * 110 * @note Channel array and sensitivity array must be one-one correspondence in those array 111 * 112 * @note Touch matrix button does not support Multi-Touch now 113 * 114 * @return 115 * - ESP_OK: Successfully create touch matrix button 116 * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized 117 * - ESP_ERR_INVALID_ARG: Invalid configuration struct or arguments is NULL 118 * - ESP_ERR_NO_MEM: Insufficient memory 119 */ 120 esp_err_t touch_matrix_create(const touch_matrix_config_t *matrix_config, touch_matrix_handle_t *matrix_handle); 121 122 /** 123 * @brief Release resources allocated using touch_matrix_create() 124 * 125 * @param[in] matrix_handle Matrix handle 126 * @return 127 * - ESP_OK: Successfully released resources 128 * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized 129 * - ESP_ERR_INVALID_ARG: matrix_handle is null 130 * - ESP_ERR_NOT_FOUND: Input handle is not a matrix handle 131 */ 132 esp_err_t touch_matrix_delete(touch_matrix_handle_t matrix_handle); 133 134 /** 135 * @brief Touch matrix button subscribes event 136 * 137 * This function uses event mask to subscribe to touch matrix events, once one of 138 * the subscribed events occurs, the event message could be retrieved by calling 139 * touch_element_message_receive() or input callback routine. 140 * 141 * @param[in] matrix_handle Matrix handle 142 * @param[in] event_mask Matrix subscription event mask 143 * @param[in] arg User input argument 144 * 145 * @note Touch matrix button only support three kind of event masks, they are 146 * TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE, TOUCH_ELEM_EVENT_ON_LONGPRESS. You can use those event 147 * masks in any combination to achieve the desired effect. 148 * 149 * @return 150 * - ESP_OK: Successfully subscribed touch matrix event 151 * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized 152 * - ESP_ERR_INVALID_ARG: matrix_handle is null or event is not supported 153 */ 154 esp_err_t touch_matrix_subscribe_event(touch_matrix_handle_t matrix_handle, uint32_t event_mask, void *arg); 155 156 /** 157 * @brief Touch matrix button set dispatch method 158 * 159 * This function sets a dispatch method that the driver core will use 160 * this method as the event notification method. 161 * 162 * @param[in] matrix_handle Matrix button handle 163 * @param[in] dispatch_method Dispatch method (By callback/event) 164 * 165 * @return 166 * - ESP_OK: Successfully set dispatch method 167 * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized 168 * - ESP_ERR_INVALID_ARG: matrix_handle is null or dispatch_method is invalid 169 */ 170 esp_err_t touch_matrix_set_dispatch_method(touch_matrix_handle_t matrix_handle, touch_elem_dispatch_t dispatch_method); 171 172 /** 173 * @brief Touch matrix button set callback 174 * 175 * This function sets a callback routine into touch element driver core, 176 * when the subscribed events occur, the callback routine will be called. 177 * 178 * @param[in] matrix_handle Matrix button handle 179 * @param[in] matrix_callback User input callback 180 * 181 * @note Matrix message will be passed from the callback function and it will be destroyed when the callback function return. 182 * 183 * @warning Since this input callback routine runs on driver core (esp-timer callback routine), 184 * it should not do something that attempts to Block, such as calling vTaskDelay(). 185 * 186 * @return 187 * - ESP_OK: Successfully set callback 188 * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized 189 * - ESP_ERR_INVALID_ARG: matrix_handle or matrix_callback is null 190 */ 191 esp_err_t touch_matrix_set_callback(touch_matrix_handle_t matrix_handle, touch_matrix_callback_t matrix_callback); 192 193 /** 194 * @brief Touch matrix button set long press trigger time 195 * 196 * This function sets the threshold time (ms) for a long press event. If a matrix button is pressed 197 * and held for a period of time that exceeds the threshold time, a long press event is triggered. 198 * 199 * @param[in] matrix_handle Matrix button handle 200 * @param[in] threshold_time Threshold time (ms) of long press event occur 201 * 202 * @return 203 * - ESP_OK: Successfully set the time of long press event 204 * - ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized 205 * - ESP_ERR_INVALID_ARG: matrix_handle is null or time (ms) is 0 206 */ 207 esp_err_t touch_matrix_set_longpress(touch_matrix_handle_t matrix_handle, uint32_t threshold_time); 208 209 /** 210 * @brief Touch matrix get message 211 * 212 * This function decodes the element message from touch_element_message_receive() and return 213 * a matrix message pointer. 214 * 215 * @param[in] element_message element message 216 * 217 * @return Touch matrix message pointer 218 */ 219 const touch_matrix_message_t* touch_matrix_get_message(const touch_elem_message_t* element_message); 220 221 #ifdef __cplusplus 222 } 223 #endif 224
