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