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