From ba42c46cb3634066247683616ca1306f899a3b41 Mon Sep 17 00:00:00 2001 From: krzychb Date: Fri, 1 Sep 2017 23:39:27 +0200 Subject: [PATCH 1/3] Touch Pad driver overview --- components/driver/include/driver/touch_pad.h | 33 +++-- .../touch_pad-measurement-parameters.jpg | Bin 0 -> 29098 bytes docs/api-reference/peripherals/index.rst | 2 +- docs/api-reference/peripherals/touch_pad.rst | 130 +++++++++++++++++- 4 files changed, 146 insertions(+), 19 deletions(-) create mode 100644 docs/_static/touch_pad-measurement-parameters.jpg diff --git a/components/driver/include/driver/touch_pad.h b/components/driver/include/driver/touch_pad.h index 548edbcf52..cc8f85204e 100644 --- a/components/driver/include/driver/touch_pad.h +++ b/components/driver/include/driver/touch_pad.h @@ -101,11 +101,11 @@ typedef enum { typedef intr_handle_t touch_isr_handle_t; -#define TOUCH_PAD_SLEEP_CYCLE_DEFAULT (0x1000) /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 uFw~8Q##Fi SPI Slave Timer - Touch pad + Touch Sensor UART Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples. diff --git a/docs/api-reference/peripherals/touch_pad.rst b/docs/api-reference/peripherals/touch_pad.rst index a4ee4950e5..ae459e1f97 100644 --- a/docs/api-reference/peripherals/touch_pad.rst +++ b/docs/api-reference/peripherals/touch_pad.rst @@ -1,12 +1,133 @@ Touch Sensor ============ -Overview --------- +Introduction +------------ A touch-sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When a user touches the surface, the capacitance variation is triggered and a binary signal is generated to indicate whether the touch is valid. -ESP32 can provide up to 10 capacitive touch pads / GPIOs. The sensing pads can be arranged in different combinations, so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer. +ESP32 can provide up to 10 capacitive touch pads / GPIOs. The sensing pads can be arranged in different combinations (e.g. matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer. + +Design, operation and control registers of touch sensor are discussed in `ESP32 Technical Reference Manual `_ (PDF). Please refer to it for additional details how this subsystem works. + + +Functionality Overview +---------------------- + +Description of API is broken down into groups of functions to provide quick overview of features like: + +- Initialization of touch pad driver +- Configuration of touch pad GPIO pins +- Taking measurements +- Adjusting parameters of measurements +- Filtering measurements +- Setting up interrupts to report touch detection +- Waking up from sleep mode on interrupt + +For detailed description of particular function please go to section :ref:`touch_pad-api-reference`. Practical implementation of this API is covered in section :ref:`touch_pad-api-examples`. + + +Initialization +^^^^^^^^^^^^^^ + +Touch pad driver should be initialized before use by calling function :cpp:func:`touch_pad_init`. This function sets several ``.._DEFAULT`` driver parameters listed in :ref:`touch_pad-api-reference` under "Macros". It also clears information what pads have been touched before (if any) and disables interrupts. + +If not required anymore, driver can be disabled by calling :cpp:func:`touch_pad_deinit`. + + +Configuration +^^^^^^^^^^^^^ + +Enabling of touch sensor functionality for particular GPIO is done with :cpp:func:`touch_pad_config`. + +The function :cpp:func:`touch_pad_set_fsm_mode` is used to select whether touch pad measurement (operated by FSM) is started automatically by hardware timer, or by software. If software mode is selected, then use :cpp:func:`touch_pad_sw_start` to start of the FSM. + + +Touch State Measurements +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following two functions come handy to read raw or filtered measurements from the sensor: + +* :cpp:func:`touch_pad_read` +* :cpp:func:`touch_pad_read_filtered` + +They may be used to characterize particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information is then used to establish the touch threshold. + +.. note:: + + Start and configure filter before using :cpp:func:`touch_pad_read_filtered` by calling specific filter functions described down below. + +To see how to use both read functions check :example:`peripherals/touch_pad_read` application example. + + +Optimization of Measurements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Touch sensor has several configurable parameters to match characteristics of particular touch pad design. For instance, to sense smaller capacity changes, it is possible to narrow the reference voltage range within which the touch pads are charged / discharged. The high and low reference voltages are set using function :cpp:func:`touch_pad_set_voltage`. A positive side effect, besides ability to discern smaller capacity changes, will be reduction of power consumption for low power applications. A likely negative effect will be increase of measurement noise. If dynamic rage of obtained readings is still satisfactory, then further reduction of power consumption may be done by lowering the measurement time with :cpp:func:`touch_pad_set_meas_time`. + +The following summarizes available measurement parameters and corresponding 'set' functions: + +* Touch pad charge / discharge parameters: + + * voltage range: :cpp:func:`touch_pad_set_voltage` + * speed (slope): :cpp:func:`touch_pad_set_cnt_mode` + +* Measure time: :cpp:func:`touch_pad_set_meas_time` + +Relationship between voltage range (high / low reference voltages), speed (slope) and measure time is shown on figure below. + +.. figure:: ../../_static/touch_pad-measurement-parameters.jpg + :align: center + :alt: Touch Pad - relationship between measurement parameters + :figclass: align-center + + Touch Pad - relationship between measurement parameters + +The last chart "Output" represents the touch sensor reading, i.e. the count of pulses collected within measure time. + +All functions are provided in pairs to 'set' specific parameter and to 'get' the current parameter's value, e.g. :cpp:func:`touch_pad_set_voltage` and :cpp:func:`touch_pad_get_voltage`. + + +Filtering of Measurements +^^^^^^^^^^^^^^^^^^^^^^^^^ + +To avoid false touch detection you may filter noisy measurements. The filter should be started before first use by calling :cpp:func:`touch_pad_filter_start`. + +The filter type is IIR (Infinite Impulse Response) and it has configurable period that can be set with function :cpp:func:`touch_pad_set_filter_period`. + +You can stop the filter with :cpp:func:`touch_pad_filter_stop`. If not required anymore, the filter may be deleted by invoking :cpp:func:`touch_pad_filter_delete`. + + +Touch Triggered Interrupts +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before enabling an interrupt on touch detection, user should establish touch detection threshold. Use functions described above to read and display sensor measurements when pad is touched and released. Apply a filter when measurements are noisy and relative changes are small. Depending on your application and environmental conditions, test the influence of temperature and power supply voltage changes on measured values. + +Once detection threshold is established, it may be set on initialization with :cpp:func:`touch_pad_config` or at the runtime with :cpp:func:`touch_pad_set_thresh`. + +In next step configure how interrupts are triggered. They may be triggered below or above threshold and this is set –with function :cpp:func:`touch_pad_set_trigger_mode`. + +Finally configure and manage interrupt calls using the following functions: + +* :cpp:func:`touch_pad_isr_handler_register` +* :cpp:func:`touch_pad_isr_register` / :cpp:func:`touch_pad_isr_deregister` +* :cpp:func:`touch_pad_intr_enable` / :cpp:func:`touch_pad_intr_disable` + +When interrupts are operational, you can obtain information what particular pad triggered interrupt by invoking :cpp:func:`touch_pad_get_status` and clear pad status with :cpp:func:`touch_pad_clear_status`. + + +Wakeup from Sleep Mode +^^^^^^^^^^^^^^^^^^^^^^ + +If touch pad interrupts are used to wakeup the chip from a sleep mode, then user can select certain configuration of pads (SET1 or both SET1 and SET2), that should be touched to trigger the interrupt and cause subsequent wakeup. To do so, use function :cpp:func:`touch_pad_set_trigger_source`. + +Configuration of required bit patterns of pads may be managed for each 'SET' with: + +* :cpp:func:`touch_pad_set_group_mask` / :cpp:func:`touch_pad_get_group_mask` +* :cpp:func:`touch_pad_clear_group_mask` + + +.. _touch_pad-api-examples: Application Examples -------------------- @@ -14,6 +135,9 @@ Application Examples - Touch sensor read example: :example:`peripherals/touch_pad_read`. - Touch sensor interrupt example: :example:`peripherals/touch_pad_interrupt`. + +.. _touch_pad-api-reference: + API Reference ------------- From 7c7d29dc4ae29078902435eed9a9d4ad54808080 Mon Sep 17 00:00:00 2001 From: krzychb Date: Tue, 5 Sep 2017 08:27:32 +0200 Subject: [PATCH 2/3] Implemented 2 of 3 review comments --- .../touch_pad-measurement-parameters.jpg | Bin 29098 -> 30737 bytes docs/api-reference/peripherals/touch_pad.rst | 1 - 2 files changed, 1 deletion(-) diff --git a/docs/_static/touch_pad-measurement-parameters.jpg b/docs/_static/touch_pad-measurement-parameters.jpg index 94529576ee204f6dc30193a4c3c2cb62f0d1cdb0..581410be14958159e66f03f56c52c408fa64c3f2 100644 GIT binary patch literal 30737 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 B<}LsL literal 29098 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 uFw~8Q##Fi Date: Tue, 5 Sep 2017 20:22:21 +0200 Subject: [PATCH 3/3] Separate section on touch detection --- docs/api-reference/peripherals/touch_pad.rst | 22 +++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/api-reference/peripherals/touch_pad.rst b/docs/api-reference/peripherals/touch_pad.rst index b25aa12379..0b868f17e6 100644 --- a/docs/api-reference/peripherals/touch_pad.rst +++ b/docs/api-reference/peripherals/touch_pad.rst @@ -21,6 +21,7 @@ Description of API is broken down into groups of functions to provide quick over - Taking measurements - Adjusting parameters of measurements - Filtering measurements +- Touch detection methods - Setting up interrupts to report touch detection - Waking up from sleep mode on interrupt @@ -51,7 +52,7 @@ The following two functions come handy to read raw or filtered measurements from * :cpp:func:`touch_pad_read` * :cpp:func:`touch_pad_read_filtered` -They may be used to characterize particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information is then used to establish the touch threshold. +They may be used to characterize particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish the touch threshold. .. note:: @@ -87,17 +88,28 @@ The last chart "Output" represents the touch sensor reading, i.e. the count of p All functions are provided in pairs to 'set' specific parameter and to 'get' the current parameter's value, e.g. :cpp:func:`touch_pad_set_voltage` and :cpp:func:`touch_pad_get_voltage`. +.. _touch_pad-api-filtering-of-measurements: Filtering of Measurements ^^^^^^^^^^^^^^^^^^^^^^^^^ -To avoid false touch detection you may filter noisy measurements. The filter should be started before first use by calling :cpp:func:`touch_pad_filter_start`. +If measurements are noisy, you may filter them with provided API. The filter should be started before first use by calling :cpp:func:`touch_pad_filter_start`. The filter type is IIR (Infinite Impulse Response) and it has configurable period that can be set with function :cpp:func:`touch_pad_set_filter_period`. You can stop the filter with :cpp:func:`touch_pad_filter_stop`. If not required anymore, the filter may be deleted by invoking :cpp:func:`touch_pad_filter_delete`. +Touch Detection +^^^^^^^^^^^^^^^ + +Touch detection is implemented in ESP32's hardware basing on user configured threshold and raw measurements executed by FSM. Use function :cpp:func:`touch_pad_get_status` to check what pads have been touched and :cpp:func:`touch_pad_clear_status` to clear the touch status information. + +Hardware touch detection may be also wired to interrupts and this is described in next section. + +If measurements are noisy and capacity changes small, then hardware touch detection may be not reliable. To resolve this issue, instead of using hardware detection / provided interrupts, implement measurement filtering and perform touch detection in your own application. See :example:`peripherals/touch_pad_interrupt` for sample implementation of both methods of touch detection. + + Touch Triggered Interrupts ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -105,7 +117,7 @@ Before enabling an interrupt on touch detection, user should establish touch det Once detection threshold is established, it may be set on initialization with :cpp:func:`touch_pad_config` or at the runtime with :cpp:func:`touch_pad_set_thresh`. -In next step configure how interrupts are triggered. They may be triggered below or above threshold and this is set –with function :cpp:func:`touch_pad_set_trigger_mode`. +In next step configure how interrupts are triggered. They may be triggered below or above threshold and this is set with function :cpp:func:`touch_pad_set_trigger_mode`. Finally configure and manage interrupt calls using the following functions: @@ -114,6 +126,10 @@ Finally configure and manage interrupt calls using the following functions: When interrupts are operational, you can obtain information what particular pad triggered interrupt by invoking :cpp:func:`touch_pad_get_status` and clear pad status with :cpp:func:`touch_pad_clear_status`. +.. note:: + + Interrupts on touch detection operate on raw / unfiltered measurements checked against user established threshold and are implemented in hardware. Enabling software filtering API (see :ref:`touch_pad-api-filtering-of-measurements`) does not affect this process. + Wakeup from Sleep Mode ^^^^^^^^^^^^^^^^^^^^^^