1 // Copyright 2019 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 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include "driver/touch_sensor_common.h" 22 23 /** 24 * @brief Configure touch pad interrupt threshold. 25 * 26 * @note If FSM mode is set to TOUCH_FSM_MODE_TIMER, this function will be blocked for one measurement cycle and wait for data to be valid. 27 * 28 * @param touch_num touch pad index 29 * @param threshold interrupt threshold, 30 * 31 * @return 32 * - ESP_OK Success 33 * - ESP_ERR_INVALID_ARG if argument wrong 34 * - ESP_FAIL if touch pad not initialized 35 */ 36 esp_err_t touch_pad_config(touch_pad_t touch_num, uint16_t threshold); 37 38 /** 39 * @brief get touch sensor counter value. 40 * Each touch sensor has a counter to count the number of charge/discharge cycles. 41 * When the pad is not 'touched', we can get a number of the counter. 42 * When the pad is 'touched', the value in counter will get smaller because of the larger equivalent capacitance. 43 * 44 * @note This API requests hardware measurement once. If IIR filter mode is enabled, 45 * please use 'touch_pad_read_raw_data' interface instead. 46 * 47 * @param touch_num touch pad index 48 * @param touch_value pointer to accept touch sensor value 49 * 50 * @return 51 * - ESP_OK Success 52 * - ESP_ERR_INVALID_ARG Touch pad parameter error 53 * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. 54 * - ESP_FAIL Touch pad not initialized 55 */ 56 esp_err_t touch_pad_read(touch_pad_t touch_num, uint16_t *touch_value); 57 58 /** 59 * @brief get filtered touch sensor counter value by IIR filter. 60 * 61 * @note touch_pad_filter_start has to be called before calling touch_pad_read_filtered. 62 * This function can be called from ISR 63 * 64 * @param touch_num touch pad index 65 * @param touch_value pointer to accept touch sensor value 66 * 67 * @return 68 * - ESP_OK Success 69 * - ESP_ERR_INVALID_ARG Touch pad parameter error 70 * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. 71 * - ESP_FAIL Touch pad not initialized 72 */ 73 esp_err_t touch_pad_read_filtered(touch_pad_t touch_num, uint16_t *touch_value); 74 75 /** 76 * @brief get raw data (touch sensor counter value) from IIR filter process. 77 * Need not request hardware measurements. 78 * 79 * @note touch_pad_filter_start has to be called before calling touch_pad_read_raw_data. 80 * This function can be called from ISR 81 * 82 * @param touch_num touch pad index 83 * @param touch_value pointer to accept touch sensor value 84 * 85 * @return 86 * - ESP_OK Success 87 * - ESP_ERR_INVALID_ARG Touch pad parameter error 88 * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. 89 * - ESP_FAIL Touch pad not initialized 90 */ 91 esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint16_t *touch_value); 92 93 /** 94 * @brief Callback function that is called after each IIR filter calculation. 95 * @note This callback is called in timer task in each filtering cycle. 96 * @note This callback should not be blocked. 97 * @param raw_value The latest raw data(touch sensor counter value) that 98 * points to all channels(raw_value[0..TOUCH_PAD_MAX-1]). 99 * @param filtered_value The latest IIR filtered data(calculated from raw data) that 100 * points to all channels(filtered_value[0..TOUCH_PAD_MAX-1]). 101 * 102 */ 103 typedef void (* filter_cb_t)(uint16_t *raw_value, uint16_t *filtered_value); 104 105 /** 106 * @brief Register the callback function that is called after each IIR filter calculation. 107 * @note The 'read_cb' callback is called in timer task in each filtering cycle. 108 * @param read_cb Pointer to filtered callback function. 109 * If the argument passed in is NULL, the callback will stop. 110 * @return 111 * - ESP_OK Success 112 * - ESP_ERR_INVALID_ARG set error 113 */ 114 esp_err_t touch_pad_set_filter_read_cb(filter_cb_t read_cb); 115 116 /** 117 * @brief Register touch-pad ISR. 118 * The handler will be attached to the same CPU core that this function is running on. 119 * @param fn Pointer to ISR handler 120 * @param arg Parameter for ISR 121 * @return 122 * - ESP_OK Success ; 123 * - ESP_ERR_INVALID_ARG GPIO error 124 * - ESP_ERR_NO_MEM No memory 125 */ 126 esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg); 127 128 /** 129 * @brief Set touch sensor measurement and sleep time. 130 * Excessive total time will slow down the touch response. 131 * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. 132 * 133 * @note The greater the duty cycle of the measurement time, the more system power is consumed. 134 * @param sleep_cycle The touch sensor will sleep after each measurement. 135 * sleep_cycle decide the interval between each measurement. 136 * t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). 137 * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. 138 * @param meas_cycle The duration of the touch sensor measurement. 139 * t_meas = meas_cycle / 8M, the maximum measure time is 0xffff / 8M = 8.19 ms 140 * @return 141 * - ESP_OK on success 142 */ 143 esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle); 144 145 /** 146 * @brief Get touch sensor measurement and sleep time 147 * @param sleep_cycle Pointer to accept sleep cycle number 148 * @param meas_cycle Pointer to accept measurement cycle count. 149 * @return 150 * - ESP_OK on success 151 */ 152 esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle); 153 154 /** 155 * @brief Trigger a touch sensor measurement, only support in SW mode of FSM 156 * @return 157 * - ESP_OK on success 158 */ 159 esp_err_t touch_pad_sw_start(void); 160 161 /** 162 * @brief Set touch sensor interrupt threshold 163 * @param touch_num touch pad index 164 * @param threshold threshold of touchpad count, refer to touch_pad_set_trigger_mode to see how to set trigger mode. 165 * @return 166 * - ESP_OK on success 167 * - ESP_ERR_INVALID_ARG if argument is wrong 168 */ 169 esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint16_t threshold); 170 171 /** 172 * @brief Get touch sensor interrupt threshold 173 * @param touch_num touch pad index 174 * @param threshold pointer to accept threshold 175 * @return 176 * - ESP_OK on success 177 * - ESP_ERR_INVALID_ARG if argument is wrong 178 */ 179 esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint16_t *threshold); 180 181 /** 182 * @brief Set touch sensor interrupt trigger mode. 183 * Interrupt can be triggered either when counter result is less than 184 * threshold or when counter result is more than threshold. 185 * @param mode touch sensor interrupt trigger mode 186 * @return 187 * - ESP_OK on success 188 * - ESP_ERR_INVALID_ARG if argument is wrong 189 */ 190 esp_err_t touch_pad_set_trigger_mode(touch_trigger_mode_t mode); 191 192 /** 193 * @brief Get touch sensor interrupt trigger mode 194 * @param mode pointer to accept touch sensor interrupt trigger mode 195 * @return 196 * - ESP_OK on success 197 */ 198 esp_err_t touch_pad_get_trigger_mode(touch_trigger_mode_t *mode); 199 200 /** 201 * @brief Set touch sensor interrupt trigger source. There are two sets of touch signals. 202 * Set1 and set2 can be mapped to several touch signals. Either set will be triggered 203 * if at least one of its touch signal is 'touched'. The interrupt can be configured to be generated 204 * if set1 is triggered, or only if both sets are triggered. 205 * @param src touch sensor interrupt trigger source 206 * @return 207 * - ESP_OK on success 208 * - ESP_ERR_INVALID_ARG if argument is wrong 209 */ 210 esp_err_t touch_pad_set_trigger_source(touch_trigger_src_t src); 211 212 /** 213 * @brief Get touch sensor interrupt trigger source 214 * @param src pointer to accept touch sensor interrupt trigger source 215 * @return 216 * - ESP_OK on success 217 */ 218 esp_err_t touch_pad_get_trigger_source(touch_trigger_src_t *src); 219 220 /** 221 * @brief Set touch sensor group mask. 222 * Touch pad module has two sets of signals, 'Touched' signal is triggered only if 223 * at least one of touch pad in this group is "touched". 224 * This function will set the register bits according to the given bitmask. 225 * @param set1_mask bitmask of touch sensor signal group1, it's a 10-bit value 226 * @param set2_mask bitmask of touch sensor signal group2, it's a 10-bit value 227 * @param en_mask bitmask of touch sensor work enable, it's a 10-bit value 228 * @return 229 * - ESP_OK on success 230 * - ESP_ERR_INVALID_ARG if argument is wrong 231 */ 232 esp_err_t touch_pad_set_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask); 233 234 /** 235 * @brief Get touch sensor group mask. 236 * @param set1_mask pointer to accept bitmask of touch sensor signal group1, it's a 10-bit value 237 * @param set2_mask pointer to accept bitmask of touch sensor signal group2, it's a 10-bit value 238 * @param en_mask pointer to accept bitmask of touch sensor work enable, it's a 10-bit value 239 * @return 240 * - ESP_OK on success 241 */ 242 esp_err_t touch_pad_get_group_mask(uint16_t *set1_mask, uint16_t *set2_mask, uint16_t *en_mask); 243 244 /** 245 * @brief Clear touch sensor group mask. 246 * Touch pad module has two sets of signals, Interrupt is triggered only if 247 * at least one of touch pad in this group is "touched". 248 * This function will clear the register bits according to the given bitmask. 249 * @param set1_mask bitmask touch sensor signal group1, it's a 10-bit value 250 * @param set2_mask bitmask touch sensor signal group2, it's a 10-bit value 251 * @param en_mask bitmask of touch sensor work enable, it's a 10-bit value 252 * @return 253 * - ESP_OK on success 254 * - ESP_ERR_INVALID_ARG if argument is wrong 255 */ 256 esp_err_t touch_pad_clear_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask); 257 258 /** 259 * @brief To enable touch pad interrupt 260 * @return 261 * - ESP_OK on success 262 */ 263 esp_err_t touch_pad_intr_enable(void); 264 265 /** 266 * @brief To disable touch pad interrupt 267 * @return 268 * - ESP_OK on success 269 */ 270 esp_err_t touch_pad_intr_disable(void); 271 272 /** 273 * @brief To clear touch pad interrupt 274 * @return 275 * - ESP_OK on success 276 */ 277 esp_err_t touch_pad_intr_clear(void); 278 279 /** 280 * @brief set touch pad filter calibration period, in ms. 281 * Need to call touch_pad_filter_start before all touch filter APIs 282 * @param new_period_ms filter period, in ms 283 * @return 284 * - ESP_OK Success 285 * - ESP_ERR_INVALID_STATE driver state error 286 * - ESP_ERR_INVALID_ARG parameter error 287 */ 288 esp_err_t touch_pad_set_filter_period(uint32_t new_period_ms); 289 290 /** 291 * @brief get touch pad filter calibration period, in ms 292 * Need to call touch_pad_filter_start before all touch filter APIs 293 * @param p_period_ms pointer to accept period 294 * @return 295 * - ESP_OK Success 296 * - ESP_ERR_INVALID_STATE driver state error 297 * - ESP_ERR_INVALID_ARG parameter error 298 */ 299 esp_err_t touch_pad_get_filter_period(uint32_t *p_period_ms); 300 301 /** 302 * @brief start touch pad filter function 303 * This API will start a filter to process the noise in order to prevent false triggering 304 * when detecting slight change of capacitance. 305 * Need to call touch_pad_filter_start before all touch filter APIs 306 * 307 * @note This filter uses FreeRTOS timer, which is dispatched from a task with 308 * priority 1 by default on CPU 0. So if some application task with higher priority 309 * takes a lot of CPU0 time, then the quality of data obtained from this filter will be affected. 310 * You can adjust FreeRTOS timer task priority in menuconfig. 311 * @param filter_period_ms filter calibration period, in ms 312 * @return 313 * - ESP_OK Success 314 * - ESP_ERR_INVALID_ARG parameter error 315 * - ESP_ERR_NO_MEM No memory for driver 316 * - ESP_ERR_INVALID_STATE driver state error 317 */ 318 esp_err_t touch_pad_filter_start(uint32_t filter_period_ms); 319 320 /** 321 * @brief stop touch pad filter function 322 * Need to call touch_pad_filter_start before all touch filter APIs 323 * @return 324 * - ESP_OK Success 325 * - ESP_ERR_INVALID_STATE driver state error 326 */ 327 esp_err_t touch_pad_filter_stop(void); 328 329 /** 330 * @brief delete touch pad filter driver and release the memory 331 * Need to call touch_pad_filter_start before all touch filter APIs 332 * @return 333 * - ESP_OK Success 334 * - ESP_ERR_INVALID_STATE driver state error 335 */ 336 esp_err_t touch_pad_filter_delete(void); 337 338 #ifdef __cplusplus 339 } 340 #endif 341