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 /******************************************************************************* 16 * NOTICE 17 * The hal is not public api, don't use in application code. 18 * See readme.md in hal/include/hal/readme.md 19 ******************************************************************************/ 20 21 // The HAL layer for touch sensor (common part) 22 23 #pragma once 24 25 #include "hal/touch_sensor_ll.h" 26 #include "hal/touch_sensor_types.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 typedef struct { 33 touch_high_volt_t refh; 34 touch_low_volt_t refl; 35 touch_volt_atten_t atten; 36 } touch_hal_volt_t; 37 38 typedef struct { 39 touch_cnt_slope_t slope; /*!<Set touch sensor charge/discharge speed(currents) for each pad.*/ 40 touch_tie_opt_t tie_opt; /*!<Set initial voltage state of touch channel for each measurement.*/ 41 } touch_hal_meas_mode_t; 42 43 /** 44 * Set touch sensor sleep time (interval of measurement). 45 * 46 * @param sleep_time The touch sensor will sleep after each measurement. 47 * sleep_cycle decide the interval between each measurement. 48 * t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). 49 * The approximate frequency value of RTC_SLOW_CLK can be obtained using `rtc_clk_slow_freq_get_hz` function. 50 */ 51 #define touch_hal_set_sleep_time(sleep_time) touch_ll_set_sleep_time(sleep_time) 52 53 /** 54 * Get touch sensor sleep time. 55 * 56 * @param sleep_time Pointer to accept sleep cycle count. 57 */ 58 #define touch_hal_get_sleep_time(sleep_time) touch_ll_get_sleep_time(sleep_time) 59 60 /** 61 * Set touch sensor high / low voltage threshold of chanrge. 62 * The touch sensor measures the channel capacitance value by charging and discharging the channel. 63 * So charge threshold should be less than the supply voltage. 64 * The actual charge threshold is high voltage threshold minus attenuation value. 65 * 66 * @param refh The high voltage threshold of chanrge. 67 */ 68 void touch_hal_set_voltage(const touch_hal_volt_t *volt); 69 70 /** 71 * Get touch sensor high / low voltage threshold of chanrge. 72 * The touch sensor measures the channel capacitance value by charging and discharging the channel. 73 * So charge threshold should be less than the supply voltage. 74 * The actual charge threshold is high voltage threshold minus attenuation value. 75 * 76 * @param refh The voltage threshold of chanrge / discharge. 77 */ 78 void touch_hal_get_voltage(touch_hal_volt_t *volt); 79 80 /** 81 * Set touch sensor charge/discharge speed(currents) and initial voltage state for each pad measurement. 82 * 83 * @param touch_num Touch pad index. 84 * @param meas Touch pad measurement config. 85 */ 86 void touch_hal_set_meas_mode(touch_pad_t touch_num, const touch_hal_meas_mode_t *meas); 87 88 /** 89 * Get touch sensor charge/discharge speed(currents) and initial voltage state for each pad measurement. 90 * 91 * @param touch_num Touch pad index. 92 * @param meas Touch pad measurement config. 93 */ 94 void touch_hal_get_meas_mode(touch_pad_t touch_num, touch_hal_meas_mode_t *meas); 95 96 /** 97 * Set touch sensor FSM mode. 98 * The measurement action can be triggered by the hardware timer, as well as by the software instruction. 99 * 100 * @param mode FSM mode. 101 */ 102 #define touch_hal_set_fsm_mode(mode) touch_ll_set_fsm_mode(mode) 103 104 /** 105 * Get touch sensor FSM mode. 106 * The measurement action can be triggered by the hardware timer, as well as by the software instruction. 107 * 108 * @param mode FSM mode. 109 */ 110 #define touch_hal_get_fsm_mode(mode) touch_ll_get_fsm_mode(mode) 111 112 /** 113 * Start touch sensor FSM timer. 114 * The measurement action can be triggered by the hardware timer, as well as by the software instruction. 115 */ 116 #define touch_hal_start_fsm() touch_ll_start_fsm() 117 118 /** 119 * Stop touch sensor FSM timer. 120 * The measurement action can be triggered by the hardware timer, as well as by the software instruction. 121 */ 122 #define touch_hal_stop_fsm() touch_ll_stop_fsm() 123 124 /** 125 * Trigger a touch sensor measurement, only support in SW mode of FSM. 126 */ 127 #define touch_hal_start_sw_meas() touch_ll_start_sw_meas() 128 129 /** 130 * Set touch sensor interrupt threshold. 131 * 132 * @note Refer to `touch_pad_set_trigger_mode` to see how to set trigger mode. 133 * @param touch_num touch pad index. 134 * @param threshold threshold of touchpad count. 135 */ 136 #define touch_hal_set_threshold(touch_num, threshold) touch_ll_set_threshold(touch_num, threshold) 137 138 /** 139 * Get touch sensor interrupt threshold. 140 * 141 * @param touch_num touch pad index. 142 * @param threshold pointer to accept threshold. 143 */ 144 #define touch_hal_get_threshold(touch_num, threshold) touch_ll_get_threshold(touch_num, threshold) 145 146 /** 147 * Enable touch sensor channel. Register touch channel into touch sensor measurement group. 148 * The working mode of the touch sensor is simultaneous measurement. 149 * This function will set the measure bits according to the given bitmask. 150 * 151 * @note If set this mask, the FSM timer should be stop firsty. 152 * @note The touch sensor that in scan map, should be deinit GPIO function firstly. 153 * @param enable_mask bitmask of touch sensor scan group. 154 * e.g. TOUCH_PAD_NUM1 -> BIT(1) 155 * @return 156 * - ESP_OK on success 157 */ 158 #define touch_hal_set_channel_mask(enable_mask) touch_ll_set_channel_mask(enable_mask) 159 160 /** 161 * Get touch sensor channel mask. 162 * 163 * @param enable_mask bitmask of touch sensor scan group. 164 * e.g. TOUCH_PAD_NUM1 -> BIT(1) 165 */ 166 #define touch_hal_get_channel_mask(enable_mask) touch_ll_get_channel_mask(enable_mask) 167 168 /** 169 * Disable touch sensor channel by bitmask. 170 * 171 * @param enable_mask bitmask of touch sensor scan group. 172 * e.g. TOUCH_PAD_NUM1 -> BIT(1) 173 */ 174 #define touch_hal_clear_channel_mask(disable_mask) touch_ll_clear_channel_mask(disable_mask) 175 176 /** 177 * Get the touch sensor status, usually used in ISR to decide which pads are 'touched'. 178 * 179 * @param status_mask The touch sensor status. e.g. Touch1 trigger status is `status_mask & (BIT1)`. 180 */ 181 #define touch_hal_read_trigger_status_mask(status_mask) touch_ll_read_trigger_status_mask(status_mask) 182 183 /** 184 * Clear all touch sensor status. 185 */ 186 #define touch_hal_clear_trigger_status_mask() touch_ll_clear_trigger_status_mask() 187 188 /** 189 * Get touch sensor raw data (touch sensor counter value) from register. No block. 190 * 191 * @param touch_num touch pad index. 192 * @return touch_value pointer to accept touch sensor value. 193 */ 194 #define touch_hal_read_raw_data(touch_num) touch_ll_read_raw_data(touch_num) 195 196 /** 197 * Get touch sensor measure status. No block. 198 * 199 * @return 200 * - If touch sensors measure done. 201 */ 202 #define touch_hal_meas_is_done() touch_ll_meas_is_done() 203 204 /** 205 * Initialize touch module. 206 * 207 * @note If default parameter don't match the usage scenario, it can be changed after this function. 208 */ 209 void touch_hal_init(void); 210 211 /** 212 * Un-install touch pad driver. 213 * 214 * @note After this function is called, other touch functions are prohibited from being called. 215 */ 216 void touch_hal_deinit(void); 217 218 /** 219 * Configure touch sensor for each channel. 220 */ 221 void touch_hal_config(touch_pad_t touch_num); 222 223 #ifdef __cplusplus 224 } 225 #endif 226
