- examples: add 'Capacitive touch sensor read' example

- examples: add 'Capacitive touch sensor interrupts' example
- Code review comments implemented
- use only one image
- add external picture of ESP32 Demo Board V2

examples/peripherals/touch_pad_interrupt/Makefile

@@ -0,0 +1,8 @@
+#
+# This is a project Makefile. It is assumed the directory this Makefile resides in is a
+# project subdirectory.
+#
+
+PROJECT_NAME := touch_pad_interrupt
+
+include $(IDF_PATH)/make/project.mk

examples/peripherals/touch_pad_interrupt/README.md

@@ -0,0 +1,30 @@
+# Touch Pad Interrupt Example
+
+Demonstrates how to set up ESP32's capacitive touch pad peripheral to trigger interrupt when a pad is touched. 
+
+Application has been developed and tested using [ESP32 Demo Board V2](https://dl.espressif.com/dl/schematics/ESP32-Demo-Board-V2_sch.pdf) that has ten capacitive sensor pads T0 to T9 exposed.
+
+![alt text](http://dl.espressif.com/dl/schematics/pictures/esp32-demo-board-v2.jpg "ESP32 Demo Board V2")
+
+The following output is shown when a pad is touched:
+
+```
+I (6303) Touch pad: Waiting for any pad being touched...
+I (6733) Touch pad: T6 activated!
+I (7333) Touch pad: T5 activated!
+I (7723) Touch pad: T3 activated!
+I (8043) Touch pad: T2 activated!
+I (8883) Touch pad: T4 activated!
+I (9523) Touch pad: T7 activated!
+I (12503) Touch pad: Waiting for any pad being touched...
+I (15483) Touch pad: T6 activated!
+I (16253) Touch pad: T5 activated!
+I (17903) Touch pad: Waiting for any pad being touched...
+I (22903) Touch pad: Waiting for any pad being touched...
+```
+
+Note: Sensing threshold is set up automatically at start up by performing simple calibration. Application is reading current value for each pad and assuming half of this value as the sensing threshold. Do not touch pads on application start up, otherwise sensing may not work correctly.
+
+For a simpler example how to configure and read capacitive touch pads, please refer to [touch_pad_read](../touch_pad_read).
+
+See the README.md file in the upper level 'examples' directory for more information about examples.

examples/peripherals/touch_pad_interrupt/main/component.mk

@@ -0,0 +1,5 @@
+#
+# "main" pseudo-component makefile.
+#
+# (Uses default behaviour of compiling all source files in directory, adding 'include' to include path.)
+

examples/peripherals/touch_pad_interrupt/main/tp_interrupt_main.c

@@ -0,0 +1,109 @@
+/* Touch Pad Interrupt Example
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+#include <stdio.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_system.h"
+#include "nvs_flash.h"
+#include "esp_log.h"
+
+#include "driver/touch_pad.h"
+#include "soc/rtc_cntl_reg.h"
+#include "soc/sens_reg.h"
+
+static const char* TAG = "Touch pad";
+
+static bool touch_pad_activated[TOUCH_PAD_MAX];
+
+
+/*
+  Read values sensed at all available touch pads.
+  Use half of read value as the threshold
+  to trigger interrupt when the pad is touched.
+  Note: this routine demonstrates a simple way
+  to configure activation threshold for the touch pads.
+  Do not touch any pads when this routine
+  is running (on application start).
+ */
+static void touch_pad_set_thresholds(void)
+{
+    uint16_t touch_value;
+    for (int i=0; i<TOUCH_PAD_MAX; i++) {
+        ESP_ERROR_CHECK(touch_pad_read(i, &touch_value));
+        ESP_ERROR_CHECK(touch_pad_config(i, touch_value/2));
+    }
+}
+
+/*
+  Check if any of touch pads has been activated
+  by reading a table updated by rtc_intr()
+  If so, then print it out on a serial monitor.
+  Clear related entry in the table afterwards
+ */
+static void touch_pad_read_task(void *pvParameter)
+{
+    static int show_message;
+    while (1) {
+        for (int i=0; i<TOUCH_PAD_MAX; i++) {
+            if (touch_pad_activated[i] == true) {
+                ESP_LOGI(TAG, "T%d activated!", i);
+                // Wait a while for the pad being released
+                vTaskDelay(200 / portTICK_PERIOD_MS);
+                // Clear information on pad activation
+                touch_pad_activated[i] = false;
+                // Reset the counter triggering a message
+                // that application is running
+                show_message = 1;
+            }
+        }
+        // If no pad is touched, every couple of seconds, show a message
+        // that application is running
+        if (show_message++ % 500 == 0) {
+            ESP_LOGI(TAG, "Waiting for any pad being touched...");
+        }
+        vTaskDelay(10 / portTICK_PERIOD_MS);
+    }
+}
+
+/*
+  Handle an interrupt triggered when a pad is touched.
+  Recognize what pad has been touched and save it in a table.
+ */
+static void touch_pad_rtc_intr(void * arg)
+{
+    uint32_t pad_intr = READ_PERI_REG(SENS_SAR_TOUCH_CTRL2_REG) & 0x3ff;
+    uint32_t rtc_intr = READ_PERI_REG(RTC_CNTL_INT_ST_REG);
+    //clear interrupt
+    WRITE_PERI_REG(RTC_CNTL_INT_CLR_REG, rtc_intr);
+    SET_PERI_REG_MASK(SENS_SAR_TOUCH_CTRL2_REG, SENS_TOUCH_MEAS_EN_CLR);
+
+    if (rtc_intr & RTC_CNTL_TOUCH_INT_ST) {
+        for (int i = 0; i < TOUCH_PAD_MAX; i++) {
+            if ((pad_intr >> i) & 0x01) {
+                touch_pad_activated[i] = true;
+            }
+        }
+    }
+}
+
+
+void app_main()
+{
+    ESP_LOGI(TAG, "Starting");
+    nvs_flash_init();
+
+    // Initialize touch pad peripheral
+    ESP_LOGI(TAG, "Initializing touch pad");
+    touch_pad_init();
+    touch_pad_set_thresholds();
+    touch_pad_isr_handler_register(touch_pad_rtc_intr, NULL, 0, NULL);
+
+    // Start a task to show what pads have been touched
+    xTaskCreate(&touch_pad_read_task, "touch_pad_read_task", 2048, NULL, 5, NULL);
+}

examples/peripherals/touch_pad_read/Makefile

@@ -0,0 +1,8 @@
+#
+# This is a project Makefile. It is assumed the directory this Makefile resides in is a
+# project subdirectory.
+#
+
+PROJECT_NAME := touch_pad_read
+
+include $(IDF_PATH)/make/project.mk

examples/peripherals/touch_pad_read/README.md

@@ -0,0 +1,24 @@
+# Touch Pad Read Example
+
+Read and display raw values from capacitive touch pad sensors. 
+
+Once configured, ESP32 is continuously measuring capacitance of touch pad sensors. Measurement is reflected as numeric value inversely related to sensor's capacitance. The capacitance is bigger when sensor is touched with a finger and the measured value smaller. In opposite situation, when finger is released, capacitance is smaller and the measured value bigger.
+
+To detect when a sensor is touched and when not, each particular design should be calibrated by obtaining both measurements for each individual sensor. Then a threshold between both values should be established. Using specific threshold, API is then able to distinguish whether specific sensor is touched or released.
+
+ESP32 supports reading up to ten capacitive touch pad sensors T0 - T9, connected to specific GPIO pins. For information on available pins please refer to [Technical Reference Manual](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf). Application initializes all ten sensor pads. Then in a loop reads sensors T0 - T9 and displays obtained values (after a colon) on a serial terminal:
+
+```
+T0: 486 T1:   1 T2: 559 T3: 567 T4: 871 T5: 522 T6:1174 T7:1531 T8:1508 T9:1640
+T0: 485 T1:   1 T2: 559 T3: 568 T4: 871 T5: 521 T6:1176 T7:1536 T8:1509 T9:1635
+T0: 485 T1:   1 T2: 559 T3: 568 T4: 871 T5: 521 T6:1172 T7:1536 T8:1507 T9:1640
+T0:  11 T1:   1 T2: 558 T3: 568 T4: 871 T5: 522 T6:1172 T7:1535 T8:1507 T9:1638
+```
+
+Above log is prepared using [ESP32 Demo Board V2](https://dl.espressif.com/dl/schematics/ESP32-Demo-Board-V2_sch.pdf) that has all ten pad sensors exposed. Values will be different depending on layout of pads on particular board.
+
+![alt text](http://dl.espressif.com/dl/schematics/pictures/esp32-demo-board-v2.jpg "ESP32 Demo Board V2")
+
+There is another similar example that demonstrates how to perform simple calibration and trigger an interrupt when a pat is touched - see [touch_pad_interrupt](../touch_pad_interrupt).
+
+See the README.md file in the upper level 'examples' directory for more information about examples.

examples/peripherals/touch_pad_read/main/component.mk

@@ -0,0 +1,5 @@
+#
+# "main" pseudo-component makefile.
+#
+# (Uses default behaviour of compiling all source files in directory, adding 'include' to include path.)
+

examples/peripherals/touch_pad_read/main/tp_read_main.c

@@ -0,0 +1,45 @@
+/* Touch Pad Read Example
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+#include <stdio.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_system.h"
+#include "nvs_flash.h"
+
+#include "driver/touch_pad.h"
+
+
+/*
+  Read values sensed at all available touch pads.
+  Print out values in a loop on a serial monitor.
+ */
+void touch_pad_read_task(void *pvParameter)
+{
+    while (1) {
+        uint16_t touch_value;
+        for (int i=0; i<TOUCH_PAD_MAX; i++) {
+            ESP_ERROR_CHECK(touch_pad_read(i, &touch_value));
+            printf("T%d:%4d ", i, touch_value);
+        }
+        printf("\n");
+        vTaskDelay(500 / portTICK_PERIOD_MS);
+    }
+}
+
+void app_main()
+{
+    nvs_flash_init();
+
+    // Initialize touch pad peripheral
+    touch_pad_init();
+
+    // Start task to read values sensed by pads
+    xTaskCreate(&touch_pad_read_task, "touch_pad_read_task", 2048, NULL, 5, NULL);
+
+}