From ba42c46cb3634066247683616ca1306f899a3b41 Mon Sep 17 00:00:00 2001
From: krzychb <krzychb@gazeta.pl>
Date: Fri, 1 Sep 2017 23:39:27 +0200
Subject: [PATCH] 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 548edbcf5..cc8f85204 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)  /*!<The timer frequency is RTC_SLOW_CLK( can be 150k or 32k depending on the options), max value is 0xffff */
-#define TOUCH_PAD_MEASURE_CYCLE_DEFAULT (0xffff)  /*!<The time frequency is 8Mhz, the max value is 0xffff */
-#define TOUCH_FSM_MODE_DEFAULT          (TOUCH_FSM_MODE_TIMER)
-#define TOUCH_TRIGGER_MODE_DEFAULT      (TOUCH_TRIGGER_BELOW)
-#define TOUCH_TRIGGER_SOURCE_DEFAULT    (TOUCH_TRIGGER_SOURCE_SET1)
+#define TOUCH_PAD_SLEEP_CYCLE_DEFAULT   (0x1000)  /*!<The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options), max value is 0xffff */
+#define TOUCH_PAD_MEASURE_CYCLE_DEFAULT (0xffff)  /*!<The timer frequency is 8Mhz, the max value is 0xffff */
+#define TOUCH_FSM_MODE_DEFAULT          (TOUCH_FSM_MODE_TIMER)  /*!<The touch FSM my be started by the software or timer */
+#define TOUCH_TRIGGER_MODE_DEFAULT      (TOUCH_TRIGGER_BELOW)   /*!<Interrupts can be triggered if sensor value gets below or above threshold */
+#define TOUCH_TRIGGER_SOURCE_DEFAULT    (TOUCH_TRIGGER_SOURCE_SET1)  /*!<The wakeup trigger source can be SET1 or both SET1 and SET2 */
 #define TOUCH_PAD_BIT_MASK_MAX          (0x3ff)
 
 /**
@@ -128,9 +128,10 @@ esp_err_t touch_pad_deinit();
  * @brief Configure touch pad interrupt threshold.
  * @param touch_num touch pad index
  * @param threshold interrupt threshold,
- * @return    - ESP_OK Success
- *            - ESP_ERR_INVALID_ARG if argument wrong
- *            - ESP_FAIL if touch pad not initialized
+ * @return
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG if argument wrong
+ *     - ESP_FAIL if touch pad not initialized
  */
 esp_err_t touch_pad_config(touch_pad_t touch_num, uint16_t threshold);
 
@@ -143,9 +144,10 @@ esp_err_t touch_pad_config(touch_pad_t touch_num, uint16_t threshold);
  *
  * @param touch_num touch pad index
  * @param touch_value pointer to accept touch sensor value
- * @return   - ESP_OK Success
- *            - ESP_ERR_INVALID_ARG Touch pad error
- *            - ESP_FAIL Touch pad not initialized
+ * @return
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG Touch pad error
+ *     - ESP_FAIL Touch pad not initialized
  */
 esp_err_t touch_pad_read(touch_pad_t touch_num, uint16_t * touch_value);
 
@@ -156,9 +158,10 @@ esp_err_t touch_pad_read(touch_pad_t touch_num, uint16_t * touch_value);
  *
  * @param touch_num touch pad index
  * @param touch_value pointer to accept touch sensor value
- * @return   - ESP_OK Success
- *            - ESP_ERR_INVALID_ARG Touch pad error
- *            - ESP_FAIL Touch pad not initialized
+ * @return
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG Touch pad error
+ *     - ESP_FAIL Touch pad not initialized
  */
 esp_err_t touch_pad_read_filtered(touch_pad_t touch_num, uint16_t *touch_value);
 
@@ -460,7 +463,7 @@ esp_err_t touch_pad_get_filter_period(uint32_t* p_period_ms);
  *
  *      If filter is not initialized, this API will initialize the filter with given period.
  *      If filter is already initialized, this API will update the filter period.
- * @note This filter uses FreeRTOS timer, which is dipatched from a task with
+ * @note This filter uses FreeRTOS timer, which is dispatched from a task with
  *       priority 1 by default on CPU 0. So if some application task with higher priority
  *       takes a lot of CPU0 time, then the quality of data obtained from this filter will be affected.
  *       You can adjust FreeRTOS timer task priority in menuconfig.
diff --git a/docs/_static/touch_pad-measurement-parameters.jpg b/docs/_static/touch_pad-measurement-parameters.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..94529576ee204f6dc30193a4c3c2cb62f0d1cdb0
GIT binary patch
literal 29098
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

literal 0
HcmV?d00001

diff --git a/docs/api-reference/peripherals/index.rst b/docs/api-reference/peripherals/index.rst
index 51a46febd..001b1173d 100644
--- a/docs/api-reference/peripherals/index.rst
+++ b/docs/api-reference/peripherals/index.rst
@@ -18,7 +18,7 @@ Peripherals API
    SPI Master <spi_master>
    SPI Slave <spi_slave>
    Timer <timer>
-   Touch pad <touch_pad>
+   Touch Sensor <touch_pad>
    UART <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 a4ee4950e..ae459e1f9 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 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (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
 -------------