update touch with review advice

2021-09-06 21:45:08 +08:00
parent 3ca9da0386
commit 589646a31e
30 changed files with 617 additions and 19 deletions
@@ -0,0 +1,6 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(touch_pad_interrupt)
@@ -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
@@ -0,0 +1,36 @@
+| Supported Targets | ESP32-S2 | ESP32-S3 |
+| ----------------- | -------- | -------- |
+
+# Touch Pad Interrupt Example
+
+## ESP32-S2, ESP32-S3 platform
+
+Demonstrates how to set up ESP32-S2's capacitive touch pad peripheral to trigger interrupt when a pad is touched. It also shows how to detect the touch event by the software for sensor designs when greater touch detection sensitivity is required.
+
+ESP32-S2 supports touch detection by configuring hardware registers. The hardware periodically detects the pulse counts. If the number of pulse counts exceeds the set threshold, a hardware interrupt will be generated to notify the application layer that a certain touch sensor channel may be triggered.
+
+The application is cycling between the interrupt mode and the pooling mode with a filter, to compare performance of the touch sensor system in both scenarios:
+
+```
+I (304) Touch pad: Initializing touch pad
+I (304) Touch pad: Denoise function init
+I (304) Touch pad: touch pad waterproof init
+I (304) Touch pad: touch pad filter init 2
+I (414) Touch pad: test init: touch pad [7] base 7382, thresh 1476
+I (414) Touch pad: test init: touch pad [9] base 7349, thresh 1469
+I (414) Touch pad: test init: touch pad [11] base 8047, thresh 1609
+I (414) Touch pad: test init: touch pad [13] base 8104, thresh 810
+I (5954) Touch pad: TouchSensor [9] be actived, status mask 0x200
+W (6034) Touch pad: TouchSensor [13] be actived, enter guard mode
+W (6034) Touch pad: In guard mode. No response
+W (6174) Touch pad: TouchSensor [13] be actived, exit guard mode
+I (6194) Touch pad: TouchSensor [9] be inactived, status mask 0x0
+```
+
+## Reference Information
+
+For a simpler example how to configure and read capacitive touch pads, please refer to [touch_pad_read](../touch_pad_read).
+
+Design and implementation of the touch sensor system is a complex process. The [Touch Sensor Application Note](https://github.com/espressif/esp-iot-solution/blob/release/v1.0/documents/touch_pad_solution/touch_sensor_design_en.md) contains several ESP32 specific notes and comments to optimize the design and get the best out of the application with sensors controlled with the ESP32.  
+
+See the README.md file in the upper level 'examples' directory for more information about examples.
@@ -0,0 +1,2 @@
+idf_component_register(SRCS "tp_interrupt_main.c"
+                    INCLUDE_DIRS ".")
@@ -0,0 +1,4 @@
+#
+# "main" pseudo-component makefile.
+#
+# (Uses default behaviour of compiling all source files in directory, adding 'include' to include path.)
@@ -0,0 +1,213 @@
+/* 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 "freertos/queue.h"
+#include "esp_log.h"
+#include "driver/touch_pad.h"
+#include "soc/rtc_periph.h"
+#include "soc/sens_periph.h"
+
+static const char *TAG = "Touch pad";
+
+static QueueHandle_t que_touch = NULL;
+typedef struct touch_msg {
+    touch_pad_intr_mask_t intr_mask;
+    uint32_t pad_num;
+    uint32_t pad_status;
+    uint32_t pad_val;
+} touch_event_t;
+
+#define TOUCH_BUTTON_NUM    4
+#define TOUCH_BUTTON_WATERPROOF_ENABLE 1
+#define TOUCH_BUTTON_DENOISE_ENABLE    1
+#define TOUCH_CHANGE_CONFIG            0
+
+static const touch_pad_t button[TOUCH_BUTTON_NUM] = {
+    TOUCH_PAD_NUM7,     // 'SELECT' button.
+    TOUCH_PAD_NUM9,     // 'MENU' button.
+    TOUCH_PAD_NUM11,    // 'BACK' button.
+    TOUCH_PAD_NUM13,    // Guard ring for waterproof design.
+    // If this pad be touched, other pads no response.
+};
+
+/*
+ * Touch threshold. The threshold determines the sensitivity of the touch.
+ * This threshold is derived by testing changes in readings from different touch channels.
+ * If (raw_data - benchmark) > benchmark * threshold, the pad be activated.
+ * If (raw_data - benchmark) < benchmark * threshold, the pad be inactivated.
+ */
+static const float button_threshold[TOUCH_BUTTON_NUM] = {
+    0.2, // 20%.
+    0.2, // 20%.
+    0.2, // 20%.
+    0.1, // 10%.
+};
+
+/*
+  Handle an interrupt triggered when a pad is touched.
+  Recognize what pad has been touched and save it in a table.
+ */
+static void touchsensor_interrupt_cb(void *arg)
+{
+    int task_awoken = pdFALSE;
+    touch_event_t evt;
+
+    evt.intr_mask = touch_pad_read_intr_status_mask();
+    evt.pad_status = touch_pad_get_status();
+    evt.pad_num = touch_pad_get_current_meas_channel();
+
+    xQueueSendFromISR(que_touch, &evt, &task_awoken);
+    if (task_awoken == pdTRUE) {
+        portYIELD_FROM_ISR();
+    }
+}
+
+static void tp_example_set_thresholds(void)
+{
+    uint32_t touch_value;
+    for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
+        //read benchmark value
+        touch_pad_read_benchmark(button[i], &touch_value);
+        //set interrupt threshold.
+        touch_pad_set_thresh(button[i], touch_value * button_threshold[i]);
+        ESP_LOGI(TAG, "touch pad [%d] base %d, thresh %d", \
+                 button[i], touch_value, (uint32_t)(touch_value * button_threshold[i]));
+    }
+}
+
+static void touchsensor_filter_set(touch_filter_mode_t mode)
+{
+    /* Filter function */
+    touch_filter_config_t filter_info = {
+        .mode = mode,           // Test jitter and filter 1/4.
+        .debounce_cnt = 1,      // 1 time count.
+        .noise_thr = 0,         // 50%
+        .jitter_step = 4,       // use for jitter mode.
+        .smh_lvl = TOUCH_PAD_SMOOTH_IIR_2,
+    };
+    touch_pad_filter_set_config(&filter_info);
+    touch_pad_filter_enable();
+    ESP_LOGI(TAG, "touch pad filter init");
+}
+
+static void tp_example_read_task(void *pvParameter)
+{
+    touch_event_t evt = {0};
+    static uint8_t guard_mode_flag = 0;
+    /* Wait touch sensor init done */
+    vTaskDelay(50 / portTICK_RATE_MS);
+    tp_example_set_thresholds();
+
+    while (1) {
+        int ret = xQueueReceive(que_touch, &evt, (portTickType)portMAX_DELAY);
+        if (ret != pdTRUE) {
+            continue;
+        }
+        if (evt.intr_mask & TOUCH_PAD_INTR_MASK_ACTIVE) {
+            /* if guard pad be touched, other pads no response. */
+            if (evt.pad_num == button[3]) {
+                guard_mode_flag = 1;
+                ESP_LOGW(TAG, "TouchSensor [%d] be activated, enter guard mode", evt.pad_num);
+            } else {
+                if (guard_mode_flag == 0) {
+                    ESP_LOGI(TAG, "TouchSensor [%d] be activated, status mask 0x%x", evt.pad_num, evt.pad_status);
+                } else {
+                    ESP_LOGW(TAG, "In guard mode. No response");
+                }
+            }
+        }
+        if (evt.intr_mask & TOUCH_PAD_INTR_MASK_INACTIVE) {
+            /* if guard pad be touched, other pads no response. */
+            if (evt.pad_num == button[3]) {
+                guard_mode_flag = 0;
+                ESP_LOGW(TAG, "TouchSensor [%d] be inactivated, exit guard mode", evt.pad_num);
+            } else {
+                if (guard_mode_flag == 0) {
+                    ESP_LOGI(TAG, "TouchSensor [%d] be inactivated, status mask 0x%x", evt.pad_num, evt.pad_status);
+                }
+            }
+        }
+        if (evt.intr_mask & TOUCH_PAD_INTR_MASK_SCAN_DONE) {
+            ESP_LOGI(TAG, "The touch sensor group measurement is done [%d].", evt.pad_num);
+        }
+        if (evt.intr_mask & TOUCH_PAD_INTR_MASK_TIMEOUT) {
+            /* Add your exception handling in here. */
+            ESP_LOGI(TAG, "Touch sensor channel %d measure timeout. Skip this exception channel!!", evt.pad_num);
+            touch_pad_timeout_resume(); // Point on the next channel to measure.
+        }
+    }
+}
+
+void app_main(void)
+{
+    if (que_touch == NULL) {
+        que_touch = xQueueCreate(TOUCH_BUTTON_NUM, sizeof(touch_event_t));
+    }
+    // Initialize touch pad peripheral, it will start a timer to run a filter
+    ESP_LOGI(TAG, "Initializing touch pad");
+    /* Initialize touch pad peripheral. */
+    touch_pad_init();
+    for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
+        touch_pad_config(button[i]);
+    }
+
+#if TOUCH_CHANGE_CONFIG
+    /* If you want change the touch sensor default setting, please write here(after initialize). There are examples: */
+    touch_pad_set_meas_time(TOUCH_PAD_SLEEP_CYCLE_DEFAULT, TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
+    touch_pad_set_voltage(TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD, TOUCH_PAD_LOW_VOLTAGE_THRESHOLD, TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD);
+    touch_pad_set_idle_channel_connect(TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT);
+    for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
+        touch_pad_set_cnt_mode(i, TOUCH_PAD_SLOPE_DEFAULT, TOUCH_PAD_TIE_OPT_DEFAULT);
+    }
+#endif
+
+#if TOUCH_BUTTON_DENOISE_ENABLE
+    /* Denoise setting at TouchSensor 0. */
+    touch_pad_denoise_t denoise = {
+        /* The bits to be cancelled are determined according to the noise level. */
+        .grade = TOUCH_PAD_DENOISE_BIT4,
+        /* By adjusting the parameters, the reading of T0 should be approximated to the reading of the measured channel. */
+        .cap_level = TOUCH_PAD_DENOISE_CAP_L4,
+    };
+    touch_pad_denoise_set_config(&denoise);
+    touch_pad_denoise_enable();
+    ESP_LOGI(TAG, "Denoise function init");
+#endif
+
+#if TOUCH_BUTTON_WATERPROOF_ENABLE
+    /* Waterproof function */
+    touch_pad_waterproof_t waterproof = {
+        .guard_ring_pad = button[3],   // If no ring pad, set 0;
+        /* It depends on the number of the parasitic capacitance of the shield pad.
+           Based on the touch readings of T14 and T0, estimate the size of the parasitic capacitance on T14
+           and set the parameters of the appropriate hardware. */
+        .shield_driver = TOUCH_PAD_SHIELD_DRV_L2,
+    };
+    touch_pad_waterproof_set_config(&waterproof);
+    touch_pad_waterproof_enable();
+    ESP_LOGI(TAG, "touch pad waterproof init");
+#endif
+
+    /* Filter setting */
+    touchsensor_filter_set(TOUCH_PAD_FILTER_IIR_16);
+    touch_pad_timeout_set(true, SOC_TOUCH_PAD_THRESHOLD_MAX);
+    /* Register touch interrupt ISR, enable intr type. */
+    touch_pad_isr_register(touchsensor_interrupt_cb, NULL, TOUCH_PAD_INTR_MASK_ALL);
+    /* If you have other touch algorithm, you can get the measured value after the `TOUCH_PAD_INTR_MASK_SCAN_DONE` interrupt is generated. */
+    touch_pad_intr_enable(TOUCH_PAD_INTR_MASK_ACTIVE | TOUCH_PAD_INTR_MASK_INACTIVE | TOUCH_PAD_INTR_MASK_TIMEOUT);
+
+    /* Enable touch sensor clock. Work mode is "timer trigger". */
+    touch_pad_set_fsm_mode(TOUCH_FSM_MODE_TIMER);
+    touch_pad_fsm_start();
+
+    // Start a task to show what pads have been touched
+    xTaskCreate(&tp_example_read_task, "touch_pad_read_task", 2048, NULL, 5, NULL);
+}
@@ -0,0 +1,6 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(touch_pad_read)
@@ -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
@@ -0,0 +1,31 @@
+| Supported Targets | ESP32-S2 | ESP32-S3 |
+| ----------------- | -------- | -------- |
+
+# Touch Pad Read Example
+
+## ESP32-S2, ESP32-S3 platform
+
+Read and display raw values from capacitive touch pad sensors.
+
+Once configured, ESP32-S2 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 bigger. In opposite situation, when finger is released, capacitance is smaller and the measured value smaller.
+
+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. For ESP32-S2, the hardware integrates the edge detection algorithm, which can achieve the purpose of detecting touch actions by configuring appropriate parameters. Please find the example in [touch_pad_interrupt](../touch_pad_interrupt).
+
+ESP32-S2 supports reading up to 14 capacitive touch pad sensors T1 - T14, connected to specific GPIO pins. For information on available pins please refer to ESP32-S2 Technical Reference Manual. T0 is the internal denoise channel used to filter out system noise and there is no corresponding external GPIO. Application initializes 14 sensor pads. Then in a loop reads sensors T1 - T14 and displays obtained values (after a colon) on a serial terminal:
+
+```
+Touch Sensor read, the output format is:
+Touchpad num:[raw data]
+
+T1: [6473] T2: [6507] T3: [6638] T4: [8917] T5: [9053] T6: [7190] T7: [7176] T8: [7416] T9: [7145] T10: [7387] T11: [7973] T12: [7776] T13: [8151] T14: [8190]
+T1: [6463] T2: [6512] T3: [6643] T4: [8920] T5: [9050] T6: [7191] T7: [7176] T8: [7416] T9: [7143] T10: [7387] T11: [7974] T12: [7778] T13: [8152] T14: [8192]
+T1: [6476] T2: [6508] T3: [6641] T4: [8919] T5: [9053] T6: [7190] T7: [7177] T8: [7416] T9: [7143] T10: [7386] T11: [7974] T12: [7776] T13: [8153] T14: [8193]
+```
+
+## Reference Information
+
+For hardware and firmware design guidelines on ESP32 touch sensor system, please refer to [Touch Sensor Application Note](https://github.com/espressif/esp-iot-solution/blob/release/v1.0/documents/touch_pad_solution/touch_sensor_design_en.md), where you may find comprehensive information on how to design and implement touch sensing applications, such as linear slider, wheel slider, matrix buttons and spring buttons.
+
+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.
@@ -0,0 +1,2 @@
+idf_component_register(SRCS "tp_read_main.c"
+                    INCLUDE_DIRS ".")
@@ -0,0 +1,4 @@
+#
+# "main" pseudo-component makefile.
+#
+# (Uses default behaviour of compiling all source files in directory, adding 'include' to include path.)
@@ -0,0 +1,90 @@
+/* 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 "driver/touch_pad.h"
+#include "esp_log.h"
+
+#define TOUCH_BUTTON_NUM    14
+#define TOUCH_CHANGE_CONFIG 0
+
+static const char *TAG = "touch read";
+static const touch_pad_t button[TOUCH_BUTTON_NUM] = {
+    TOUCH_PAD_NUM1,
+    TOUCH_PAD_NUM2,
+    TOUCH_PAD_NUM3,
+    TOUCH_PAD_NUM4,
+    TOUCH_PAD_NUM5,
+    TOUCH_PAD_NUM6,
+    TOUCH_PAD_NUM7,
+    TOUCH_PAD_NUM8,
+    TOUCH_PAD_NUM9,
+    TOUCH_PAD_NUM10,
+    TOUCH_PAD_NUM11,
+    TOUCH_PAD_NUM12,
+    TOUCH_PAD_NUM13,
+    TOUCH_PAD_NUM14
+};
+
+/*
+  Read values sensed at all available touch pads.
+ Print out values in a loop on a serial monitor.
+ */
+static void tp_example_read_task(void *pvParameter)
+{
+    uint32_t touch_value;
+
+    /* Wait touch sensor init done */
+    vTaskDelay(100 / portTICK_RATE_MS);
+    printf("Touch Sensor read, the output format is: \nTouchpad num:[raw data]\n\n");
+
+    while (1) {
+        for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
+            touch_pad_read_raw_data(button[i], &touch_value);    // read raw data.
+            printf("T%d: [%4d] ", button[i], touch_value);
+        }
+        printf("\n");
+        vTaskDelay(200 / portTICK_PERIOD_MS);
+    }
+}
+
+void app_main(void)
+{
+    /* Initialize touch pad peripheral. */
+    touch_pad_init();
+    for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
+        touch_pad_config(button[i]);
+    }
+#if TOUCH_CHANGE_CONFIG
+    /* If you want change the touch sensor default setting, please write here(after initialize). There are examples: */
+    touch_pad_set_meas_time(TOUCH_PAD_SLEEP_CYCLE_DEFAULT, TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
+    touch_pad_set_voltage(TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD, TOUCH_PAD_LOW_VOLTAGE_THRESHOLD, TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD);
+    touch_pad_set_idle_channel_connect(TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT);
+    for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
+        touch_pad_set_cnt_mode(i, TOUCH_PAD_SLOPE_DEFAULT, TOUCH_PAD_TIE_OPT_DEFAULT);
+    }
+#endif
+    /* Denoise setting at TouchSensor 0. */
+    touch_pad_denoise_t denoise = {
+        /* The bits to be cancelled are determined according to the noise level. */
+        .grade = TOUCH_PAD_DENOISE_BIT4,
+        .cap_level = TOUCH_PAD_DENOISE_CAP_L4,
+    };
+    touch_pad_denoise_set_config(&denoise);
+    touch_pad_denoise_enable();
+    ESP_LOGI(TAG, "Denoise function init");
+
+    /* Enable touch sensor clock. Work mode is "timer trigger". */
+    touch_pad_set_fsm_mode(TOUCH_FSM_MODE_TIMER);
+    touch_pad_fsm_start();
+
+    /* Start task to read values by pads. */
+    xTaskCreate(&tp_example_read_task, "touch_pad_read_task", 2048, NULL, 5, NULL);
+}