Merge branch 'refactor/split_touch_sleep_from_system_example' into 'master'

refactor(touch): separate touch sleep example

Closes IDFCI-2866 and IDF-12974

See merge request espressif/esp-idf!38662

Author: L-KAYA

docs/en/api-reference/peripherals/cap_touch_sens.rst

@@ -476,6 +476,7 @@ Application Examples
 ------------------------
 
     - :example:`peripherals/touch_sensor/touch_sens_basic` demonstrates how to register touch channels and read the data, including hardware requirements and project configuration instructions.
+    - :example:`peripherals/touch_sensor/touch_sens_sleep` demonstrates how to wake up the chip from the light or deep sleep by the touch sensor.
 
 Application Notes
 -----------------

docs/en/api-reference/peripherals/touch_element.rst

@@ -432,8 +432,6 @@ Only Touch Button can be configured as a wake-up source.
 
 Light- or Deep-sleep modes are both supported to be wakened up by a touch sensor. For the Light-sleep mode, any installed touch button can wake it up. But only the sleep button can wake up from Deep-sleep mode, and the touch sensor will do a calibration immediately, the reference value will be calibrated to a wrong value if our finger does not remove timely. Though the wrong reference value recovers after the finger removes away and has no effect on the driver logic, if you do not want to see a wrong reference value while waking up from Deep-sleep mode, you can call :cpp:func:`touch_element_sleep_enable_wakeup_calibration` to disable the wakeup calibration.
 
-The Touch Element Wakeup example is available in `system/light_sleep` directory.
-
 .. code-block:: c
 
     void app_main()

docs/en/api-reference/system/sleep_modes.rst

@@ -475,8 +475,9 @@ Application Examples
     :SOC_WIFI_SUPPORTED: - :example:`wifi/power_save` demonstrates the usage of Wi-Fi Modem-sleep mode and automatic Light-sleep feature to maintain Wi-Fi connections.
     :SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save` demonstrates the usage of Bluetooth Modem-sleep mode and automatic Light-sleep feature to maintain Bluetooth connections.
     :SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` demonstrates the usage of various Deep-sleep wakeup triggers and ULP coprocessor programming.
-    :not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, EXT0, EXT1, the touch sensor, supported by {IDF_TARGET_NAME}.
-    - :example:`system/light_sleep` demonstrates the usage of Light-sleep wakeup triggered by various sources, such as the timer, GPIOs, the touch sensor, supported by {IDF_TARGET_NAME}.
+    :not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, EXT0, EXT1, supported by {IDF_TARGET_NAME}.
+    - :example:`system/light_sleep` demonstrates the usage of Light-sleep wakeup triggered by various sources, such as the timer, GPIOs, supported by {IDF_TARGET_NAME}.
+    :SOC_TOUCH_SENSOR_SUPPORTED and SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP: - :example:`peripherals/touch_sensor/touch_sens_sleep` demonstrates the usage of Light-sleep and Deep-sleep wakeup triggered by the touch sensor.
 
 API Reference
 -------------

docs/zh_CN/api-reference/peripherals/cap_touch_sens.rst

@@ -476,6 +476,7 @@
 --------
 
     - :example:`peripherals/touch_sensor/touch_sens_basic` 演示了如何注册触摸通道并读取数据，并说明了硬件要求及项目配置。
+    - :example:`peripherals/touch_sensor/touch_sens_sleep` 演示了如何通过触摸传感器将芯片从 Light Sleep 或 Deep Sleep 状态唤醒。
 
 应用注意事项
 ------------

docs/zh_CN/api-reference/peripherals/touch_element.rst

@@ -432,8 +432,6 @@
 
 使用触摸传感器，可以唤醒从 Light-sleep 或 Deep-sleep 模式中唤醒芯片。在 Light-sleep 模式下，任何已安装的触摸按键都可以唤醒芯片。但在 Deep-sleep 模式下，只有睡眠按键可以唤醒芯片，触摸传感器还会立即进行校准。如果手指没有及时离开，可能导致校准参考值出错。尽管在手指离开后，校准参考值会自行恢复，不会影响驱动逻辑，但如果你不想在从 Deep-sleep 模式唤醒时看到错误的校准参考值，可以调用 :cpp:func:`touch_element_sleep_enable_wakeup_calibration`，禁用唤醒校准功能。
 
-查看使用触摸元件唤醒芯片的示例代码，请前往 ESP-IDF 示例的 :example:`system/light_sleep` 目录。
-
 .. code-block:: c
 
     void app_main()

docs/zh_CN/api-reference/system/sleep_modes.rst

@@ -475,8 +475,9 @@ UART 输出处理
     :SOC_WIFI_SUPPORTED: - :example:`wifi/power_save` 演示如何通过 Wi-Fi Modem-sleep 模式和自动 Light-sleep 模式保持 Wi-Fi 连接。
     :SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save` 演示如何通过 Bluetooth Modem-sleep 模式和自动 Light-sleep 模式保持 Bluetooth 连接。
     :SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何使用 Deep-sleep 唤醒触发器和 ULP 协处理器编程。
-    :not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器, GPIO, EXT0, EXT1, 触摸传感器等，触发 Deep-sleep 唤醒。
-    - :example:`system/light_sleep` 演示如何使用  {IDF_TARGET_NAME} 的唤醒源，如定时器，GPIO，触摸传感器等，触发 Light-sleep 唤醒。
+    :not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器, GPIO, EXT0, EXT1等，触发 Deep-sleep 唤醒。
+    - :example:`system/light_sleep` 演示如何使用  {IDF_TARGET_NAME} 的唤醒源，如定时器，GPIO等，触发 Light-sleep 唤醒。
+    :SOC_TOUCH_SENSOR_SUPPORTED and SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP: - :example:`peripherals/touch_sensor/touch_sens_sleep` 演示如何使用触摸传感器唤醒 Light-sleep 或 Deep-sleep。
 
 API 参考
 -------------

examples/peripherals/.build-test-rules.yml

@@ -479,6 +479,12 @@ examples/peripherals/touch_sensor/touch_sens_basic:
   depends_components:
     - esp_driver_touch_sens
 
+examples/peripherals/touch_sensor/touch_sens_sleep:
+  disable:
+    - if: SOC_TOUCH_SENSOR_SUPPORTED != 1 or SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP != 1
+  depends_components:
+    - esp_driver_touch_sens
+
 examples/peripherals/twai/twai_alert_and_recovery:
   disable:
     - if: SOC_TWAI_SUPPORTED != 1 or SOC_TWAI_SUPPORT_FD == 1

examples/peripherals/touch_sensor/touch_sens_sleep/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following five 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.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(touch_sens_sleep)

examples/peripherals/touch_sensor/touch_sens_sleep/README.md

@@ -0,0 +1,95 @@
+| Supported Targets | ESP32 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- |
+
+# Touch Sensor Sleep Wake up Example
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example is going to demonstrate how to wake up the chip from light/deep sleep by the touch sensor.
+
+## How to Use Example
+
+### Hardware Required
+
+* A development board with any supported Espressif SOC chip (see `Supported Targets` table above)
+* A USB cable for power supply and programming
+* (Optional) Touch board with touch buttons on it.
+    - If you don't have a touch board, you can connect the touch pins with male jump wires and touch it directly for testing.
+
+### Configure the Project
+
+You can determine the touch channel number by ``EXAMPLE_TOUCH_CHANNEL_NUM`` in the example. And adjust the active threshold by ``s_thresh2bm_ratio``.
+
+You can run `idf.py menuconfig` to configure the example
+
+- `Example Configuration > Touch Sensor wakeup level`: Select `Light sleep wakeup` or `Deep sleep wakeup` mode
+- `Example Configuration > Allow touch sensor power down during the deep sleep`: Choose whether to allow the touch sensor power down during the deep sleep. If enabled, the touch sensor will be powered down during the deep sleep, only one specified touch channel can wakeup the chip from deep sleep. If disabled, the touch sensor will keep working during the deep sleep. Any enabled touch channel can wakeup the chip from deep sleep.
+
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT build flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+### Light Sleep Log
+
+```
+...
+Touch [CH 7] enabled on GPIO9
+Touch [CH 8] enabled on GPIO10
+Touch [CH 9] enabled on GPIO11
+Initial benchmark and new threshold are:
+Touch [CH 7] 0: 4884, 97
+Touch [CH 8] 0: 4993, 99
+Touch [CH 9] 0: 4913, 98
+I (399) touch_wakeup: touch wakeup source is ready
+Entering light sleep in:
+5 sec...
+4 sec...
+3 sec...
+2 sec...
+1 sec...
+W (5399) touch callback: ch 8 active
+I (5399) touch_wakeup: Wake up by touch
+
+Entering light sleep in:
+5 sec...
+W (5479) touch callback: ch 8 inactive
+4 sec...
+3 sec...
+2 sec...
+1 sec...
+```
+
+### Deep Sleep Log
+
+```
+...
+Touch [CH 7] enabled on GPIO9
+Touch [CH 8] enabled on GPIO10
+Touch [CH 9] enabled on GPIO11
+Initial benchmark and new threshold are:
+Touch [CH 7] 0: 4897, 97
+Touch [CH 8] 0: 4879, 97
+Touch [CH 9] 0: 4954, 99
+I (405) touch_wakeup: touch wakeup source is ready
+Entering deep sleep in:
+5 sec...
+4 sec...
+3 sec...
+2 sec...
+1 sec...
+```
+
+## Troubleshooting
+
+For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

examples/peripherals/touch_sensor/touch_sens_sleep/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(SRCS "touch_sens_sleep.c"
+                    PRIV_REQUIRES esp_driver_touch_sens esp_driver_uart
+                    INCLUDE_DIRS ".")