1Touch Element 2============= 3 4Overview 5-------- 6 7Touch Element library provides a high level abstraction for building capacitive touch applications. The library's implementation gives a unified and friendly software interface thus allows for smooth and easy capacitive touch application development. The library is implemented atop the touch sensor driver (please see :doc:`Touch sensor driver API Reference <../peripherals/touch_pad>` for more information regarding low level API usage). 8 9Architecture 10^^^^^^^^^^^^ 11 12Touch Element library configures touch sensor peripherals via touch sensor driver. While some necessary hardware parameters should be passed to :cpp:func:`touch_element_install` and will be configured automatically only after calling :cpp:func:`touch_element_start`, because it will make great influence on the run-time system. 13 14These parameters include touch channel threshold, waterproof shield sensor driver-level and etc. Touch Element library sets touch sensor interrupt and esp-timer routine up and the hardware information of touch sensor (channel state, channel number) will be obtained in touch sensor interrupt service routine. When the specified channel event occurs, and those hardware information will be passed to the esp-timer callback routine, esp-timer callback routine will dispatch the touch sensor channel information to the touch elements(such as button, slider etc). Then runs the specified algorithm to update touch element's state or calculate its position, dispatch the result to user. 15 16So using Touch Element library, user doesn't need to care about the implementation of touch sensor peripheral, Touch Element library will handle most of the hardware information and pass the more meaningful messages to user event handler routine. 17 18Workflow of Touch Element library is illustrated in the picture below. 19 20.. figure:: /../_static/touch_element/te_architecture.svg 21 :scale: 100 % 22 :align: center 23 24 Touch Element architecture 25 26 27The features in relation to the Touch Element library in {IDF_TARGET_NAME} are given in the table below. 28 29+--------------------------------------------------------------+---------------------+ 30| Features | ESP32S2 | 31+==============================================================+=====================+ 32| Touch Element waterproof | ✔ | 33+--------------------------------------------------------------+---------------------+ 34| Touch Element button | ✔ | 35+--------------------------------------------------------------+---------------------+ 36| Touch Element slider | ✔ | 37+--------------------------------------------------------------+---------------------+ 38| Touch Element matrix button | ✔ | 39+--------------------------------------------------------------+---------------------+ 40 41 42Peripheral 43^^^^^^^^^^ 44 45{IDF_TARGET_NAME} integrates one touch sensor peripheral with several physical channels. 46 47.. only:: esp32s2 48 49 - 14 physical capacitive touch channels 50 - Timer or software FSM trigger mode 51 - Up to 5 kinds of interrupt(Upper threshold and lower threshold interrupt, measure one channel finish and measure all channels finish interrupt, measurement timeout interrupt) 52 - Sleep mode wakeup source 53 - Hardware internal de-noise 54 - Hardware filter 55 - Hardware waterproof sensor 56 - Hardware proximity sensor 57 58 59.. only:: esp32 60 61 - 10 physical capacitive touch channels 62 - Timer or software FSM trigger mode 63 - 2 kinds of interrupt(Greater than threshold and less than threshold) 64 - Sleep mode wakeup source 65 66 67The channels are located as follows: 68 69======================= ======================= 70 Channel {IDF_TARGET_NAME} 71======================= ======================= 72 **Channel 0** **GPIO 0 (reserved)** 73 **Channel 1** **GPIO 1** 74 **Channel 2** **GPIO 2** 75 **Channel 3** **GPIO 3** 76 **Channel 4** **GPIO 4** 77 **Channel 5** **GPIO 5** 78 **Channel 6** **GPIO 6** 79 **Channel 7** **GPIO 7** 80 **Channel 8** **GPIO 8** 81 **Channel 9** **GPIO 9** 82 **Channel 10** **GPIO 10** 83 **Channel 11** **GPIO 11** 84 **Channel 12** **GPIO 12** 85 **Channel 13** **GPIO 13** 86 **Channel 14** **GPIO 14** 87======================= ======================= 88 89 90Terminology 91----------- 92 93The terms used in relation to the Touch Element library are given in the below. 94 95======================= ========================================================================================= 96 Term Definition 97======================= ========================================================================================= 98 **Touch sensor** Touch sensor peripheral inside the chip 99 **Touch channel** Touch sensor channels inside the touch sensor peripheral 100 **Touch pad** Off-chip physical solder pad (Generally inside the PCB) 101 **De-noise channel** Internal de-noise channel (Is always Channel 0 and it is reserved) 102 **Shield sensor** One of the waterproof sensor, use for compensating the influence of water drop 103 **Guard sensor** One of the waterproof sensor, use for detecting the water stream 104 **Shield channel** The channel that waterproof shield sensor connected to (Is always Channel 14) 105 **Guard channel** The channel that waterproof guard sensor connected to 106 **Shield pad** Off-chip physical solder pad (Generally is grids) and is connected to shield sensor 107 **Guard pad** Off-chip physical solder pad (Is usually a ring) and is connected to guard sensor 108======================= ========================================================================================= 109 110.. figure:: /../_static/touch_element/te_component.svg 111 :scale: 100 % 112 :align: center 113 114 Touch sensor application system components 115 116 117Touch Sensor Signal 118^^^^^^^^^^^^^^^^^^^ 119 120Each touch senor is able to provide the following types of signals: 121 122- Raw: The Raw signal is the unfiltered signal from the touch sensor 123- Smooth: The Smooth signal is a filtered version of the Raw signal via an internal hardware filter 124- Benchmark: The Benchmark signal is also a filtered signal that filters out extremely low-frequency noise. 125 126All of these signals can be obtained using touch sensor driver API. 127 128.. figure:: /../_static/touch_element/te_signal.png 129 :scale: 40 % 130 :align: center 131 132 Touch sensor signals 133 134 135Touch Sensor Threshold 136^^^^^^^^^^^^^^^^^^^^^^ 137 138The Touch Sensor Threshold value is a configurable threshold value used to determine when a touch sensor is touched or not. When difference between the Smooth signal and the Benchmark signal becomes greater than the threshold value (i.e., ``(smooth - benchmark) > threshold``), the touch channel's state will be changed and a touch interrupt will be triggered simultaneously. 139 140.. figure:: /../_static/touch_element/te_threshold.svg 141 :scale: 40 % 142 :align: center 143 144 Touch sensor signal threshold 145 146 147Sensitivity 148^^^^^^^^^^^ 149 150Important performance parameter of touch sensor, the larger it is, the better touch sensor will perform. It could be calculated by the format in below: 151 152.. math:: 153 154 Sensitivity = \frac{Signal_{press} - Signal_{release}}{Signal_{release}} = \frac{Signal_{delta}}{Signal_{benchmark}} 155 156 157Waterproof 158^^^^^^^^^^ 159 160Waterproof is a hardware feature of touch sensor which has guard sensor and shield sensor (Always connect to Channel 14) that has the ability to resist a degree influence of water drop and detect the water stream. 161 162 163Touch Button 164^^^^^^^^^^^^ 165 166Touch button consumes one channel of touch sensor, and it looks like as the picture below: 167 168 169.. figure:: /../_static/touch_element/te_button.svg 170 :scale: 100 % 171 :align: center 172 173 Touch button 174 175 176Touch Slider 177^^^^^^^^^^^^ 178 179Touch slider consumes several channels(at least three channels) of touch sensor, the more channels consumed, the higher resolution and accuracy position it will perform. Touch slider looks like as the picture below: 180 181.. figure:: /../_static/touch_element/te_slider.svg 182 :scale: 100 % 183 :align: center 184 185 Touch slider 186 187 188Touch Matrix 189^^^^^^^^^^^^ 190 191Touch matrix button consumes several channels(at least 2 + 2 = 4 channels), it gives a solution to use fewer channels and get more buttons. {IDF_TARGET_NAME} supports up to 49 buttons. Touch matrix button looks like as the picture below: 192 193.. figure:: /../_static/touch_element/te_matrix.svg 194 :scale: 100 % 195 :align: center 196 197 Touch matrix 198 199 200Touch Element Library Usage 201--------------------------- 202 203Using this library should follow the initialization flow below: 204 2051. To initialize Touch Element library by calling :cpp:func:`touch_element_install` 2062. To initialize touch elements(button/slider etc) by calling :cpp:func:`touch_xxxx_install` 2073. To create a new element instance by calling :cpp:func:`touch_xxxx_create` 2084. To subscribe events by calling :cpp:func:`touch_xxxx_subscribe_event` 2095. To choose a dispatch method by calling :cpp:func:`touch_xxxx_set_dispatch_method` that tells the library how to notify you while the subscribed event occur 2106. (If dispatch by callback) Call :cpp:func:`touch_xxxx_set_callback` to set the event handler function. 2117. To start Touch Element library by calling :cpp:func:`touch_element_start` 2128. (If dispatch by callback) The callback will be called by the driver core when event happen, no need to do anything; (If dispatch by event task) create an event task and call :cpp:func:`touch_element_message_receive` to obtain messages in a loop. 2139. [Optional] If user wants to suspend the Touch Element run-time system or for some reason that could not obtain the touch element message, :cpp:func:`touch_element_stop` should be called to suspend the Touch Element system and then resume it by calling :cpp:func:`touch_element_start` again. 214 215In code, the flow above may look like as follows: 216 217.. code-block:: c 218 219 static touch_xxx_handle_t element_handle; //Declare a touch element handle 220 221 //Define the subscribed event handler 222 void event_handler(touch_xxx_handle_t out_handle, touch_xxx_message_t out_message, void *arg) 223 { 224 //Event handler logic 225 } 226 227 void app_main() 228 { 229 //Using the default initializer to config Touch Element library 230 touch_elem_global_config_t global_config = TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG(); 231 touch_element_install(&global_config); 232 233 //Using the default initializer to config Touch elements 234 touch_xxx_global_config_t elem_global_config = TOUCH_XXXX_GLOBAL_DEFAULT_CONFIG(); 235 touch_xxx_install(&elem_global_config); 236 237 //Create a new instance 238 touch_xxx_config_t element_config = { 239 ... 240 ... 241 }; 242 touch_xxx_create(&element_config, &element_handle); 243 244 //Subscribe the specified events by using the event mask 245 touch_xxx_subscribe_event(element_handle, TOUCH_ELEM_EVENT_ON_PRESS | TOUCH_ELEM_EVENT_ON_RELEASE, NULL); 246 247 //Choose CALLBACK as the dispatch method 248 touch_xxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_CALLBACK); 249 250 //Register the callback routine 251 touch_xxx_set_callback(element_handle, event_handler); 252 253 //Start Touch Element library processing 254 touch_element_start(); 255 } 256 257 258Initialization 259^^^^^^^^^^^^^^ 260 2611. To initialize Touch Element library, user has to configure touch sensor peripheral and Touch Element library by calling :cpp:func:`touch_element_install` with :cpp:type:`touch_elem_global_config_t`, the default initializer is available in :cpp:func:`TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG` and this default configuration is suitable for the most general application scene, and users are suggested not to change the default configuration before fully understanding Touch Sensor peripheral, because some changes might bring several impacts to the system. 262 2632. To initialize the specified element, all the elements will not work before its constructor (:cpp:func:`touch_xxxx_install`) is called so as to save memory, so user has to call the constructor of each used touch element respectively, to set up the specified element. 264 265 266Touch Element Instance Startup 267^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 268 2691. To create a new touch element instance by calling :cpp:func:`touch_xxxx_create`, selects channel and passes its `Sensitivity`_ for the new element instance. 270 2712. To subscribe events by calling :cpp:func:`touch_xxxx_subscribe_event`, there several events in Touch Element library and the event mask is available on :idf_file:`components/touch_element/include/touch_element/touch_element.h`, user could use those events mask to subscribe specified event or combine them to subscribe multiple events. 272 2733. To configure dispatch method by calling :cpp:func:`touch_xxxx_subscribe_event`, there are two dispatch methods in Touch Element library, one is :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT`, the other one is :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK`, it means that user could use two methods to obtain the touch element message and handle it. 274 275Events Processing 276^^^^^^^^^^^^^^^^^ 277 278If :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT` dispatch method is configured, user need to startup an event handler task to obtain the touch element message, all the elements raw message could be obtained by calling :cpp:func:`touch_element_message_receive`, then extract the element-class-specific message by calling the corresponding message decoder (:cpp:func:`touch_xxxx_get_message`) to get the touch element's extracted message; If :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK` dispatch method is configured, user need to pass an event handler by calling :cpp:func:`touch_xxxx_set_callback` before the touch elem starts working, all the element's extracted message will be passed to the event handler function. 279 280.. warning:: 281 Since the event handler function runs on the library driver core(The context located in esp-timer callback routine), user 282 should not do something that attempts to block or delay, such as call :cpp:func:`vTaskDelay`. 283 284 285In code, the events handle procedure may look like as follows: 286 287.. code-block:: c 288 289 /* ---------------------------------------------- TOUCH_ELEM_DISP_EVENT ----------------------------------------------- */ 290 void element_handler_task(void *arg) 291 { 292 touch_elem_message_t element_message; 293 while(1) { 294 if (touch_element_message_receive(&element_message, Timeout) == ESP_OK) { 295 const touch_xxxx_message_t *extracted_message = touch_xxxx_get_message(&element_message); //Decode message 296 ... //Event handler logic 297 } 298 } 299 } 300 void app_main() 301 { 302 ... 303 304 touch_xxxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_EVENT); //Set TOUCH_ELEM_DISP_EVENT as the dispatch method 305 xTaskCreate(&element_handler_task, "element_handler_task", 2048, NULL, 5, NULL); //Create a handler task 306 307 ... 308 } 309 /* -------------------------------------------------------------------------------------------------------------- */ 310 311 ... 312 /* ---------------------------------------------- TOUCH_ELEM_DISP_CALLBACK ----------------------------------------------- */ 313 void element_handler(touch_xxxx_handle_t out_handle, touch_xxxx_message_t out_message, void *arg) 314 { 315 //Event handler logic 316 } 317 318 void app_main() 319 { 320 ... 321 322 touch_xxxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_CALLBACK); //Set TOUCH_ELEM_DISP_CALLBACK as the dispatch method 323 touch_xxxx_set_callback(element_handle, element_handler); //Register an event handler function 324 325 ... 326 } 327 /* -------------------------------------------------------------------------------------------------------------- */ 328 329 330Waterproof Usage 331^^^^^^^^^^^^^^^^ 332 3331. To initialize Touch Element waterproof, the waterproof shield sensor is always-on after Touch Element waterproof is initialized, however the waterproof guard sensor is optional, hence if user doesn't need the guard sensor, `TOUCH_WATERPROOF_GUARD_NOUSE` has to be passed to :cpp:func:`touch_element_waterproof_install` by the configuration struct. 334 3352. To associate the touch element with the guard sensor, pass the touch element's handle to the Touch Element waterproof's masked list by calling :cpp:func:`touch_element_waterproof_add`. By associating a touch element with the Guard sensor, the touch element will be disabled when the guard sensor is triggered by a stream of water so as to protect the touch element. 336 337The Touch Element Waterproof example is available in `peripherals/touch_element/touch_element_waterproof` directory. 338 339In code, the waterproof configuration may look like as follows: 340 341.. code-block:: c 342 343 void app_main() 344 { 345 ... 346 347 touch_xxxx_install(); //Initialize instance (button, slider, etc) 348 touch_xxxx_create(&element_handle); //Create a new Touch element 349 350 ... 351 352 touch_element_waterproof_install(); //Initialize Touch Element waterproof 353 touch_element_waterproof_add(element_handle); //Let a element associates with guard sensor 354 355 ... 356 } 357 358 359Application Example 360------------------- 361All the Touch Element library examples could be found in the `peripherals/touch_element` directory of ESP-IDF examples. 362 363 364API Reference - Touch Element core 365---------------------------------- 366 367.. include-build-file:: inc/touch_element.inc 368 369 370API Reference - Touch Button 371---------------------------------- 372 373.. include-build-file:: inc/touch_button.inc 374 375 376API Reference - Touch Slider 377---------------------------------- 378 379.. include-build-file:: inc/touch_slider.inc 380 381 382API Reference - Touch Slider 383---------------------------------- 384 385.. include-build-file:: inc/touch_matrix.inc 386
