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 slider instance default configuration --------------------------------- */ 24 #define TOUCH_SLIDER_GLOBAL_DEFAULT_CONFIG() \ 25 { \ 26 .quantify_lower_threshold = 0.3, \ 27 .threshold_divider = 0.8, \ 28 .filter_reset_time = 50, \ 29 .benchmark_update_time = 500, \ 30 .position_filter_size = 10, \ 31 .position_filter_factor = 2, \ 32 .calculate_channel_count = 3 \ 33 } 34 /* ------------------------------------------------------------------------------------------------------------------ */ 35 36 /** 37 * @brief Slider initialization configuration passed to touch_slider_install 38 */ 39 typedef struct { 40 float quantify_lower_threshold; //!< Slider signal quantification threshold 41 float threshold_divider; //!< Slider channel threshold divider 42 uint16_t filter_reset_time; //!< Slider position filter reset time (Unit is esp_timer callback tick) 43 uint16_t benchmark_update_time; //!< Slider benchmark update time (Unit is esp_timer callback tick) 44 uint8_t position_filter_size; //!< Moving window filter buffer size 45 uint8_t position_filter_factor; //!< One-order IIR filter factor 46 uint8_t calculate_channel_count; //!< The number of channels which will take part in calculation 47 } touch_slider_global_config_t; 48 49 /** 50 * @brief Slider configuration (for new instance) passed to touch_slider_create() 51 */ 52 typedef struct { 53 const touch_pad_t *channel_array; //!< Slider channel array 54 const float *sensitivity_array; //!< Slider channel sensitivity array 55 uint8_t channel_num; //!< The number of slider channels 56 uint8_t position_range; //!< The right region of touch slider position range, [0, position_range (less than or equal to 255)] 57 } touch_slider_config_t; 58 59 /** 60 * @brief Slider event type 61 */ 62 typedef enum { 63 TOUCH_SLIDER_EVT_ON_PRESS, //!< Slider on Press event 64 TOUCH_SLIDER_EVT_ON_RELEASE, //!< Slider on Release event 65 TOUCH_SLIDER_EVT_ON_CALCULATION, //!< Slider on Calculation event 66 TOUCH_SLIDER_EVT_MAX 67 } touch_slider_event_t; 68 69 typedef uint32_t touch_slider_position_t; //!< Slider position data type 70 71 /** 72 * @brief Slider message type 73 */ 74 typedef struct { 75 touch_slider_event_t event; //!< Slider event 76 touch_slider_position_t position; //!< Slider position 77 } touch_slider_message_t; 78 79 typedef touch_elem_handle_t touch_slider_handle_t; //!< Slider instance handle 80 typedef void(*touch_slider_callback_t)(touch_slider_handle_t, touch_slider_message_t *, void *); //!< Slider callback type 81 82 /** 83 * @brief Touch slider initialize 84 * 85 * This function initializes touch slider object and acts on all 86 * touch slider instances. 87 * 88 * @param[in] global_config Touch slider global initialization configuration 89 * 90 * @return 91 * - ESP_OK: Successfully initialized touch slider 92 * - ESP_ERR_INVALID_STATE: Touch element library was not initialized 93 * - ESP_ERR_INVALID_ARG: slider_init is NULL 94 * - ESP_ERR_NO_MEM: Insufficient memory 95 */ 96 esp_err_t touch_slider_install(const touch_slider_global_config_t *global_config); 97 98 /** 99 * @brief Release resources allocated using touch_slider_install() 100 * 101 * @return 102 * - ESP_OK: Successfully released resources 103 */ 104 void touch_slider_uninstall(void); 105 106 /** 107 * @brief Create a new touch slider instance 108 * 109 * @param[in] slider_config Slider configuration 110 * @param[out] slider_handle Slider handle 111 * 112 * @note The index of Channel array and sensitivity array must be one-one correspondence 113 * 114 * @return 115 * - ESP_OK: Successfully create touch slider 116 * - ESP_ERR_INVALID_STATE: Touch slider 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_slider_create(const touch_slider_config_t *slider_config, touch_slider_handle_t *slider_handle); 121 122 /** 123 * @brief Release resources allocated using touch_slider_create 124 * 125 * @param[in] slider_handle Slider handle 126 * @return 127 * - ESP_OK: Successfully released resources 128 * - ESP_ERR_INVALID_STATE: Touch slider driver was not initialized 129 * - ESP_ERR_INVALID_ARG: slider_handle is null 130 * - ESP_ERR_NOT_FOUND: Input handle is not a slider handle 131 */ 132 esp_err_t touch_slider_delete(touch_slider_handle_t slider_handle); 133 134 /** 135 * @brief Touch slider subscribes event 136 * 137 * This function uses event mask to subscribe to touch slider 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] slider_handle Slider handle 142 * @param[in] event_mask Slider subscription event mask 143 * @param[in] arg User input argument 144 * 145 * @note Touch slider only support three kind of event masks, they are 146 * TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE. You can use those event masks in any 147 * combination to achieve the desired effect. 148 * 149 * @return 150 * - ESP_OK: Successfully subscribed touch slider event 151 * - ESP_ERR_INVALID_STATE: Touch slider driver was not initialized 152 * - ESP_ERR_INVALID_ARG: slider_handle is null or event is not supported 153 */ 154 esp_err_t touch_slider_subscribe_event(touch_slider_handle_t slider_handle, uint32_t event_mask, void *arg); 155 156 /** 157 * @brief Touch slider 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] slider_handle Slider 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 slider driver was not initialized 168 * - ESP_ERR_INVALID_ARG: slider_handle is null or dispatch_method is invalid 169 */ 170 esp_err_t touch_slider_set_dispatch_method(touch_slider_handle_t slider_handle, touch_elem_dispatch_t dispatch_method); 171 172 /** 173 * @brief Touch slider 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] slider_handle Slider handle 179 * @param[in] slider_callback User input callback 180 * 181 * @note Slider 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 slider driver was not initialized 189 * - ESP_ERR_INVALID_ARG: slider_handle or slider_callback is null 190 */ 191 esp_err_t touch_slider_set_callback(touch_slider_handle_t slider_handle, touch_slider_callback_t slider_callback); 192 193 /** 194 * @brief Touch slider get message 195 * 196 * This function decodes the element message from touch_element_message_receive() and return 197 * a slider message pointer. 198 * 199 * @param[in] element_message element message 200 * 201 * @return Touch slider message pointer 202 */ 203 const touch_slider_message_t* touch_slider_get_message(const touch_elem_message_t* element_message); 204 205 #ifdef __cplusplus 206 } 207 #endif 208
