1 // Copyright 2015-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 <stdbool.h> 18 #include "esp_attr.h" 19 #include "soc/soc.h" 20 #include "soc/soc_caps.h" 21 #include "sdkconfig.h" 22 23 /** Touch pad channel */ 24 typedef enum { 25 TOUCH_PAD_NUM0 = 0, /*!< Touch pad channel 0 is GPIO4(ESP32) */ 26 TOUCH_PAD_NUM1, /*!< Touch pad channel 1 is GPIO0(ESP32) / GPIO1(ESP32-S2) */ 27 TOUCH_PAD_NUM2, /*!< Touch pad channel 2 is GPIO2(ESP32) / GPIO2(ESP32-S2) */ 28 TOUCH_PAD_NUM3, /*!< Touch pad channel 3 is GPIO15(ESP32) / GPIO3(ESP32-S2) */ 29 TOUCH_PAD_NUM4, /*!< Touch pad channel 4 is GPIO13(ESP32) / GPIO4(ESP32-S2) */ 30 TOUCH_PAD_NUM5, /*!< Touch pad channel 5 is GPIO12(ESP32) / GPIO5(ESP32-S2) */ 31 TOUCH_PAD_NUM6, /*!< Touch pad channel 6 is GPIO14(ESP32) / GPIO6(ESP32-S2) */ 32 TOUCH_PAD_NUM7, /*!< Touch pad channel 7 is GPIO27(ESP32) / GPIO7(ESP32-S2) */ 33 TOUCH_PAD_NUM8, /*!< Touch pad channel 8 is GPIO33(ESP32) / GPIO8(ESP32-S2) */ 34 TOUCH_PAD_NUM9, /*!< Touch pad channel 9 is GPIO32(ESP32) / GPIO9(ESP32-S2) */ 35 #if SOC_TOUCH_SENSOR_NUM > 10 36 TOUCH_PAD_NUM10, /*!< Touch channel 10 is GPIO10(ESP32-S2) */ 37 TOUCH_PAD_NUM11, /*!< Touch channel 11 is GPIO11(ESP32-S2) */ 38 TOUCH_PAD_NUM12, /*!< Touch channel 12 is GPIO12(ESP32-S2) */ 39 TOUCH_PAD_NUM13, /*!< Touch channel 13 is GPIO13(ESP32-S2) */ 40 TOUCH_PAD_NUM14, /*!< Touch channel 14 is GPIO14(ESP32-S2) */ 41 #endif 42 TOUCH_PAD_MAX, 43 } touch_pad_t; 44 45 /** Touch sensor high reference voltage */ 46 typedef enum { 47 TOUCH_HVOLT_KEEP = -1, /*!<Touch sensor high reference voltage, no change */ 48 TOUCH_HVOLT_2V4 = 0, /*!<Touch sensor high reference voltage, 2.4V */ 49 TOUCH_HVOLT_2V5, /*!<Touch sensor high reference voltage, 2.5V */ 50 TOUCH_HVOLT_2V6, /*!<Touch sensor high reference voltage, 2.6V */ 51 TOUCH_HVOLT_2V7, /*!<Touch sensor high reference voltage, 2.7V */ 52 TOUCH_HVOLT_MAX, 53 } touch_high_volt_t; 54 55 /** Touch sensor low reference voltage */ 56 typedef enum { 57 TOUCH_LVOLT_KEEP = -1, /*!<Touch sensor low reference voltage, no change */ 58 TOUCH_LVOLT_0V5 = 0, /*!<Touch sensor low reference voltage, 0.5V */ 59 TOUCH_LVOLT_0V6, /*!<Touch sensor low reference voltage, 0.6V */ 60 TOUCH_LVOLT_0V7, /*!<Touch sensor low reference voltage, 0.7V */ 61 TOUCH_LVOLT_0V8, /*!<Touch sensor low reference voltage, 0.8V */ 62 TOUCH_LVOLT_MAX, 63 } touch_low_volt_t; 64 65 /** Touch sensor high reference voltage attenuation */ 66 typedef enum { 67 TOUCH_HVOLT_ATTEN_KEEP = -1, /*!<Touch sensor high reference voltage attenuation, no change */ 68 TOUCH_HVOLT_ATTEN_1V5 = 0, /*!<Touch sensor high reference voltage attenuation, 1.5V attenuation */ 69 TOUCH_HVOLT_ATTEN_1V, /*!<Touch sensor high reference voltage attenuation, 1.0V attenuation */ 70 TOUCH_HVOLT_ATTEN_0V5, /*!<Touch sensor high reference voltage attenuation, 0.5V attenuation */ 71 TOUCH_HVOLT_ATTEN_0V, /*!<Touch sensor high reference voltage attenuation, 0V attenuation */ 72 TOUCH_HVOLT_ATTEN_MAX, 73 } touch_volt_atten_t; 74 75 /** Touch sensor charge/discharge speed */ 76 typedef enum { 77 TOUCH_PAD_SLOPE_0 = 0, /*!<Touch sensor charge / discharge speed, always zero */ 78 TOUCH_PAD_SLOPE_1 = 1, /*!<Touch sensor charge / discharge speed, slowest */ 79 TOUCH_PAD_SLOPE_2 = 2, /*!<Touch sensor charge / discharge speed */ 80 TOUCH_PAD_SLOPE_3 = 3, /*!<Touch sensor charge / discharge speed */ 81 TOUCH_PAD_SLOPE_4 = 4, /*!<Touch sensor charge / discharge speed */ 82 TOUCH_PAD_SLOPE_5 = 5, /*!<Touch sensor charge / discharge speed */ 83 TOUCH_PAD_SLOPE_6 = 6, /*!<Touch sensor charge / discharge speed */ 84 TOUCH_PAD_SLOPE_7 = 7, /*!<Touch sensor charge / discharge speed, fast */ 85 TOUCH_PAD_SLOPE_MAX, 86 } touch_cnt_slope_t; 87 88 /** Touch sensor initial charge level */ 89 typedef enum { 90 TOUCH_PAD_TIE_OPT_LOW = 0, /*!<Initial level of charging voltage, low level */ 91 TOUCH_PAD_TIE_OPT_HIGH = 1, /*!<Initial level of charging voltage, high level */ 92 TOUCH_PAD_TIE_OPT_MAX, 93 } touch_tie_opt_t; 94 95 /** Touch sensor FSM mode */ 96 typedef enum { 97 TOUCH_FSM_MODE_TIMER = 0, /*!<To start touch FSM by timer */ 98 TOUCH_FSM_MODE_SW, /*!<To start touch FSM by software trigger */ 99 TOUCH_FSM_MODE_MAX, 100 } touch_fsm_mode_t; 101 102 /**** ESP32 Only *****/ 103 104 typedef enum { 105 TOUCH_TRIGGER_BELOW = 0, /*!<Touch interrupt will happen if counter value is less than threshold.*/ 106 TOUCH_TRIGGER_ABOVE = 1, /*!<Touch interrupt will happen if counter value is larger than threshold.*/ 107 TOUCH_TRIGGER_MAX, 108 } touch_trigger_mode_t; 109 110 typedef enum { 111 TOUCH_TRIGGER_SOURCE_BOTH = 0, /*!< wakeup interrupt is generated if both SET1 and SET2 are "touched"*/ 112 TOUCH_TRIGGER_SOURCE_SET1 = 1, /*!< wakeup interrupt is generated if SET1 is "touched"*/ 113 TOUCH_TRIGGER_SOURCE_MAX, 114 } touch_trigger_src_t; 115 116 /********************************/ 117 #define TOUCH_PAD_BIT_MASK_ALL ((1<<SOC_TOUCH_SENSOR_NUM)-1) 118 #define TOUCH_PAD_SLOPE_DEFAULT (TOUCH_PAD_SLOPE_7) 119 #define TOUCH_PAD_TIE_OPT_DEFAULT (TOUCH_PAD_TIE_OPT_LOW) 120 #define TOUCH_PAD_BIT_MASK_MAX (TOUCH_PAD_BIT_MASK_ALL) 121 #define TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD (TOUCH_HVOLT_2V7) 122 #define TOUCH_PAD_LOW_VOLTAGE_THRESHOLD (TOUCH_LVOLT_0V5) 123 #define TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD (TOUCH_HVOLT_ATTEN_0V5) 124 #define TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT (TOUCH_PAD_CONN_GND) 125 #define TOUCH_PAD_THRESHOLD_MAX (SOC_TOUCH_PAD_THRESHOLD_MAX) /*!<If set touch threshold max value, The touch sensor can't be in touched status */ 126 127 #ifdef CONFIG_IDF_TARGET_ESP32 128 129 #define TOUCH_PAD_SLEEP_CYCLE_DEFAULT (0x1000) /*!<The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options), max value is 0xffff */ 130 #define TOUCH_PAD_MEASURE_CYCLE_DEFAULT (0x7fff) /*!<The timer frequency is 8Mhz, the max value is 0x7fff */ 131 #define TOUCH_FSM_MODE_DEFAULT (TOUCH_FSM_MODE_SW) /*!<The touch FSM my be started by the software or timer */ 132 #define TOUCH_TRIGGER_MODE_DEFAULT (TOUCH_TRIGGER_BELOW) /*!<Interrupts can be triggered if sensor value gets below or above threshold */ 133 #define TOUCH_TRIGGER_SOURCE_DEFAULT (TOUCH_TRIGGER_SOURCE_SET1) /*!<The wakeup trigger source can be SET1 or both SET1 and SET2 */ 134 135 #endif // CONFIG_IDF_TARGET ESP32 136 137 #if !CONFIG_IDF_TARGET_ESP32 138 /** 139 * Excessive total time will slow down the touch response. 140 * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. 141 * 142 * @note The greater the duty cycle of the measurement time, the more system power is consumed. 143 */ 144 #define TOUCH_PAD_SLEEP_CYCLE_DEFAULT (0xf) /*!<The number of sleep cycle in each measure process of touch channels. 145 The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options). 146 Range: 0 ~ 0xffff */ 147 #define TOUCH_PAD_MEASURE_CYCLE_DEFAULT (500) /*!<The times of charge and discharge in each measure process of touch channels. 148 The timer frequency is 8Mhz. 149 Recommended typical value: Modify this value to make the measurement time around 1ms. 150 Range: 0 ~ 0xffff */ 151 152 typedef enum { 153 TOUCH_PAD_INTR_MASK_DONE = BIT(0), /*!<Measurement done for one of the enabled channels. */ 154 TOUCH_PAD_INTR_MASK_ACTIVE = BIT(1), /*!<Active for one of the enabled channels. */ 155 TOUCH_PAD_INTR_MASK_INACTIVE = BIT(2), /*!<Inactive for one of the enabled channels. */ 156 TOUCH_PAD_INTR_MASK_SCAN_DONE = BIT(3), /*!<Measurement done for all the enabled channels. */ 157 TOUCH_PAD_INTR_MASK_TIMEOUT = BIT(4), /*!<Timeout for one of the enabled channels. */ 158 TOUCH_PAD_INTR_MASK_MAX 159 #define TOUCH_PAD_INTR_MASK_ALL (TOUCH_PAD_INTR_MASK_TIMEOUT \ 160 | TOUCH_PAD_INTR_MASK_SCAN_DONE \ 161 | TOUCH_PAD_INTR_MASK_INACTIVE \ 162 | TOUCH_PAD_INTR_MASK_ACTIVE \ 163 | TOUCH_PAD_INTR_MASK_DONE) /*!<All touch interrupt type enable. */ 164 } touch_pad_intr_mask_t; 165 FLAG_ATTR(touch_pad_intr_mask_t) 166 167 typedef enum { 168 TOUCH_PAD_DENOISE_BIT12 = 0, /*!<Denoise range is 12bit */ 169 TOUCH_PAD_DENOISE_BIT10 = 1, /*!<Denoise range is 10bit */ 170 TOUCH_PAD_DENOISE_BIT8 = 2, /*!<Denoise range is 8bit */ 171 TOUCH_PAD_DENOISE_BIT4 = 3, /*!<Denoise range is 4bit */ 172 TOUCH_PAD_DENOISE_MAX 173 } touch_pad_denoise_grade_t; 174 175 typedef enum { 176 TOUCH_PAD_DENOISE_CAP_L0 = 0, /*!<Denoise channel internal reference capacitance is 5pf */ 177 TOUCH_PAD_DENOISE_CAP_L1 = 1, /*!<Denoise channel internal reference capacitance is 6.4pf */ 178 TOUCH_PAD_DENOISE_CAP_L2 = 2, /*!<Denoise channel internal reference capacitance is 7.8pf */ 179 TOUCH_PAD_DENOISE_CAP_L3 = 3, /*!<Denoise channel internal reference capacitance is 9.2pf */ 180 TOUCH_PAD_DENOISE_CAP_L4 = 4, /*!<Denoise channel internal reference capacitance is 10.6pf */ 181 TOUCH_PAD_DENOISE_CAP_L5 = 5, /*!<Denoise channel internal reference capacitance is 12.0pf */ 182 TOUCH_PAD_DENOISE_CAP_L6 = 6, /*!<Denoise channel internal reference capacitance is 13.4pf */ 183 TOUCH_PAD_DENOISE_CAP_L7 = 7, /*!<Denoise channel internal reference capacitance is 14.8pf */ 184 TOUCH_PAD_DENOISE_CAP_MAX = 8 185 } touch_pad_denoise_cap_t; 186 187 /** Touch sensor denoise configuration */ 188 typedef struct touch_pad_denoise { 189 touch_pad_denoise_grade_t grade; /*!<Select denoise range of denoise channel. 190 Determined by measuring the noise amplitude of the denoise channel. */ 191 touch_pad_denoise_cap_t cap_level; /*!<Select internal reference capacitance of denoise channel. 192 Ensure that the denoise readings are closest to the readings of the channel being measured. 193 Use `touch_pad_denoise_read_data` to get the reading of denoise channel. 194 The equivalent capacitance of the shielded channel can be calculated 195 from the reading of denoise channel. */ 196 } touch_pad_denoise_t; 197 198 /** Touch sensor shield channel drive capability level */ 199 typedef enum { 200 TOUCH_PAD_SHIELD_DRV_L0 = 0,/*!<The max equivalent capacitance in shield channel is 40pf */ 201 TOUCH_PAD_SHIELD_DRV_L1, /*!<The max equivalent capacitance in shield channel is 80pf */ 202 TOUCH_PAD_SHIELD_DRV_L2, /*!<The max equivalent capacitance in shield channel is 120pf */ 203 TOUCH_PAD_SHIELD_DRV_L3, /*!<The max equivalent capacitance in shield channel is 160pf */ 204 TOUCH_PAD_SHIELD_DRV_L4, /*!<The max equivalent capacitance in shield channel is 200pf */ 205 TOUCH_PAD_SHIELD_DRV_L5, /*!<The max equivalent capacitance in shield channel is 240pf */ 206 TOUCH_PAD_SHIELD_DRV_L6, /*!<The max equivalent capacitance in shield channel is 280pf */ 207 TOUCH_PAD_SHIELD_DRV_L7, /*!<The max equivalent capacitance in shield channel is 320pf */ 208 TOUCH_PAD_SHIELD_DRV_MAX 209 } touch_pad_shield_driver_t; 210 211 /** Touch sensor waterproof configuration */ 212 typedef struct touch_pad_waterproof { 213 touch_pad_t guard_ring_pad; /*!<Waterproof. Select touch channel use for guard pad. 214 Guard pad is used to detect the large area of water covering the touch panel. */ 215 touch_pad_shield_driver_t shield_driver;/*!<Waterproof. Shield channel drive capability configuration. 216 Shield pad is used to shield the influence of water droplets covering the touch panel. 217 When the waterproof function is enabled, Touch14 is set as shield channel by default. 218 The larger the parasitic capacitance on the shielding channel, the higher the drive capability needs to be set. 219 The equivalent capacitance of the shield channel can be estimated through the reading value of the denoise channel(Touch0).*/ 220 } touch_pad_waterproof_t; 221 222 /** Touch sensor proximity detection configuration */ 223 #define TOUCH_PROXIMITY_MEAS_NUM_MAX (0xFF) 224 225 /** Touch channel idle state configuration */ 226 typedef enum { 227 TOUCH_PAD_CONN_HIGHZ = 0, /*!<Idle status of touch channel is high resistance state */ 228 TOUCH_PAD_CONN_GND = 1, /*!<Idle status of touch channel is ground connection */ 229 TOUCH_PAD_CONN_MAX 230 } touch_pad_conn_type_t; 231 232 /** 233 * @brief Touch channel IIR filter coefficient configuration. 234 * @note On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter coefficient. 235 * So please select a smaller filter coefficient on the basis of meeting the filtering requirements. 236 * Recommended filter coefficient selection `IIR_16`. 237 */ 238 typedef enum { 239 TOUCH_PAD_FILTER_IIR_4 = 0, /*!<The filter mode is first-order IIR filter. The coefficient is 4. */ 240 TOUCH_PAD_FILTER_IIR_8, /*!<The filter mode is first-order IIR filter. The coefficient is 8. */ 241 TOUCH_PAD_FILTER_IIR_16, /*!<The filter mode is first-order IIR filter. The coefficient is 16 (Typical value). */ 242 TOUCH_PAD_FILTER_IIR_32, /*!<The filter mode is first-order IIR filter. The coefficient is 32. */ 243 TOUCH_PAD_FILTER_IIR_64, /*!<The filter mode is first-order IIR filter. The coefficient is 64. */ 244 TOUCH_PAD_FILTER_IIR_128, /*!<The filter mode is first-order IIR filter. The coefficient is 128. */ 245 TOUCH_PAD_FILTER_IIR_256, /*!<The filter mode is first-order IIR filter. The coefficient is 256. */ 246 TOUCH_PAD_FILTER_JITTER, /*!<The filter mode is jitter filter */ 247 TOUCH_PAD_FILTER_MAX 248 } touch_filter_mode_t; 249 250 /** 251 * @brief Level of filter applied on the original data against large noise interference. 252 * @note On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter coefficient. 253 * So please select a smaller filter coefficient on the basis of meeting the filtering requirements. 254 * Recommended filter coefficient selection `IIR_2`. 255 */ 256 typedef enum { 257 TOUCH_PAD_SMOOTH_OFF = 0, /*!<No filtering of raw data. */ 258 TOUCH_PAD_SMOOTH_IIR_2 = 1, /*!<Filter the raw data. The coefficient is 2 (Typical value). */ 259 TOUCH_PAD_SMOOTH_IIR_4 = 2, /*!<Filter the raw data. The coefficient is 4. */ 260 TOUCH_PAD_SMOOTH_IIR_8 = 3, /*!<Filter the raw data. The coefficient is 8. */ 261 TOUCH_PAD_SMOOTH_MAX, 262 } touch_smooth_mode_t; 263 264 /** Touch sensor filter configuration */ 265 typedef struct touch_filter_config { 266 touch_filter_mode_t mode; /*!<Set filter mode. The input of the filter is the raw value of touch reading, 267 and the output of the filter is involved in the judgment of the touch state. */ 268 uint32_t debounce_cnt; /*!<Set debounce count, such as `n`. If the measured values continue to exceed 269 the threshold for `n+1` times, the touch sensor state changes. 270 Range: 0 ~ 7 */ 271 uint32_t noise_thr; /*!<Noise threshold coefficient. Higher = More noise resistance. 272 The actual noise should be less than (noise coefficient * touch threshold). 273 Range: 0 ~ 3. The coefficient is 0: 4/8; 1: 3/8; 2: 2/8; 3: 1; */ 274 uint32_t jitter_step; /*!<Set jitter filter step size. Range: 0 ~ 15 */ 275 touch_smooth_mode_t smh_lvl;/*!<Level of filter applied on the original data against large noise interference. */ 276 #define TOUCH_DEBOUNCE_CNT_MAX (7) 277 #define TOUCH_NOISE_THR_MAX (3) 278 #define TOUCH_JITTER_STEP_MAX (15) 279 } touch_filter_config_t; 280 281 /** Touch sensor channel sleep configuration */ 282 typedef struct { 283 touch_pad_t touch_num; /*!<Set touch channel number for sleep pad. 284 Only one touch sensor channel is supported in deep sleep mode. 285 If clear the sleep channel, point this pad to `TOUCH_PAD_NUM0` */ 286 bool en_proximity; /*!<enable proximity function for sleep pad */ 287 } touch_pad_sleep_channel_t; 288 289 #endif // !CONFIG_IDF_TARGET_ESP32 290
