1 // Copyright 2015-2016 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 "esp_err.h" 18 #include "esp_intr_alloc.h" 19 #include "hal/touch_sensor_types.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 * @brief Initialize touch module. 27 * @note If default parameter don't match the usage scenario, it can be changed after this function. 28 * @return 29 * - ESP_OK Success 30 * - ESP_ERR_NO_MEM Touch pad init error 31 * - ESP_ERR_NOT_SUPPORTED Touch pad is providing current to external XTAL 32 */ 33 esp_err_t touch_pad_init(void); 34 35 /** 36 * @brief Un-install touch pad driver. 37 * @note After this function is called, other touch functions are prohibited from being called. 38 * @return 39 * - ESP_OK Success 40 * - ESP_FAIL Touch pad driver not initialized 41 */ 42 esp_err_t touch_pad_deinit(void); 43 44 /** 45 * @brief Initialize touch pad GPIO 46 * @param touch_num touch pad index 47 * @return 48 * - ESP_OK on success 49 * - ESP_ERR_INVALID_ARG if argument is wrong 50 */ 51 esp_err_t touch_pad_io_init(touch_pad_t touch_num); 52 53 /** 54 * @brief Set touch sensor high voltage threshold of chanrge. 55 * The touch sensor measures the channel capacitance value by charging and discharging the channel. 56 * So the high threshold should be less than the supply voltage. 57 * @param refh the value of DREFH 58 * @param refl the value of DREFL 59 * @param atten the attenuation on DREFH 60 * @return 61 * - ESP_OK on success 62 * - ESP_ERR_INVALID_ARG if argument is wrong 63 */ 64 esp_err_t touch_pad_set_voltage(touch_high_volt_t refh, touch_low_volt_t refl, touch_volt_atten_t atten); 65 66 /** 67 * @brief Get touch sensor reference voltage, 68 * @param refh pointer to accept DREFH value 69 * @param refl pointer to accept DREFL value 70 * @param atten pointer to accept the attenuation on DREFH 71 * @return 72 * - ESP_OK on success 73 */ 74 esp_err_t touch_pad_get_voltage(touch_high_volt_t *refh, touch_low_volt_t *refl, touch_volt_atten_t *atten); 75 76 /** 77 * @brief Set touch sensor charge/discharge speed for each pad. 78 * If the slope is 0, the counter would always be zero. 79 * If the slope is 1, the charging and discharging would be slow, accordingly. 80 * If the slope is set 7, which is the maximum value, the charging and discharging would be fast. 81 * @note The higher the charge and discharge current, the greater the immunity of the touch channel, 82 * but it will increase the system power consumption. 83 * @param touch_num touch pad index 84 * @param slope touch pad charge/discharge speed 85 * @param opt the initial voltage 86 * @return 87 * - ESP_OK on success 88 * - ESP_ERR_INVALID_ARG if argument is wrong 89 */ 90 esp_err_t touch_pad_set_cnt_mode(touch_pad_t touch_num, touch_cnt_slope_t slope, touch_tie_opt_t opt); 91 92 /** 93 * @brief Get touch sensor charge/discharge speed for each pad 94 * @param touch_num touch pad index 95 * @param slope pointer to accept touch pad charge/discharge slope 96 * @param opt pointer to accept the initial voltage 97 * @return 98 * - ESP_OK on success 99 * - ESP_ERR_INVALID_ARG if argument is wrong 100 */ 101 esp_err_t touch_pad_get_cnt_mode(touch_pad_t touch_num, touch_cnt_slope_t *slope, touch_tie_opt_t *opt); 102 103 /** 104 * @brief Deregister the handler previously registered using touch_pad_isr_handler_register 105 * @param fn handler function to call (as passed to touch_pad_isr_handler_register) 106 * @param arg argument of the handler (as passed to touch_pad_isr_handler_register) 107 * @return 108 * - ESP_OK on success 109 * - ESP_ERR_INVALID_STATE if a handler matching both fn and 110 * arg isn't registered 111 */ 112 esp_err_t touch_pad_isr_deregister(void(*fn)(void *), void *arg); 113 114 /** 115 * @brief Get the touch pad which caused wakeup from deep sleep. 116 * @param pad_num pointer to touch pad which caused wakeup 117 * @return 118 * - ESP_OK Success 119 * - ESP_ERR_INVALID_ARG parameter is NULL 120 */ 121 esp_err_t touch_pad_get_wakeup_status(touch_pad_t *pad_num); 122 123 /** 124 * @brief Set touch sensor FSM mode, the test action can be triggered by the timer, 125 * as well as by the software. 126 * @param mode FSM mode 127 * @return 128 * - ESP_OK on success 129 * - ESP_ERR_INVALID_ARG if argument is wrong 130 */ 131 esp_err_t touch_pad_set_fsm_mode(touch_fsm_mode_t mode); 132 133 /** 134 * @brief Get touch sensor FSM mode 135 * @param mode pointer to accept FSM mode 136 * @return 137 * - ESP_OK on success 138 */ 139 esp_err_t touch_pad_get_fsm_mode(touch_fsm_mode_t *mode); 140 141 142 /** 143 * @brief To clear the touch sensor channel active status. 144 * 145 * @note The FSM automatically updates the touch sensor status. It is generally not necessary to call this API to clear the status. 146 * @return 147 * - ESP_OK on success 148 */ 149 esp_err_t touch_pad_clear_status(void); 150 151 /** 152 * @brief Get the touch sensor channel active status mask. 153 * The bit position represents the channel number. The 0/1 status of the bit represents the trigger status. 154 * 155 * @return 156 * - The touch sensor status. e.g. Touch1 trigger status is `status_mask & (BIT1)`. 157 */ 158 uint32_t touch_pad_get_status(void); 159 160 /** 161 * @brief Check touch sensor measurement status. 162 * 163 * @return 164 * - True measurement is under way 165 * - False measurement done 166 */ 167 bool touch_pad_meas_is_done(void); 168 169 #ifdef __cplusplus 170 } 171 #endif 172