From 6f1373db11def9278188c88a1d2e37409b78a9b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 1 Nov 2022 14:47:05 +0100 Subject: [PATCH 1/5] add touch.rst --- docs/source/api/touch.rst | 122 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/source/api/touch.rst diff --git a/docs/source/api/touch.rst b/docs/source/api/touch.rst new file mode 100644 index 00000000000..1596db02da7 --- /dev/null +++ b/docs/source/api/touch.rst @@ -0,0 +1,122 @@ +##### +TOUCH +##### + +About +----- + +Touch sensor is a peripheral, that can be used to sense electrical changes on respective GPIO pins. Therefore these touch sensors +are also known as capacitive sensors. For example, if you touch any of these pins, the touch sensor will sense output according to +electrical charge on your finger. These pins can be easily integrated into capacitive pads, and replace mechanical buttons. + +.. note:: Touch peripheral is not present in every SoC. Refer to datasheet of each chip for more info. + +Arduino-ESP32 TOUCH API +----------------------- + +TOUCH common API +**************** + +touchRead +^^^^^^^^^ + +This function is used to get the TOUCH pad value for a given pin. + +.. code-block:: arduino + + touch_value_t touchRead(uint8_t pin); + +* ``pin`` GPIO pin to read TOUCH value + +This function will return touch pad value as uint16_t (ESP32) or uint32_t (ESP32-S2/S3). + +touchSetCycles +^^^^^^^^^^^^^^ + +This function is used to set cycles that measurement operation takes. The result from touchRead, threshold and detection accuracy depend on these values. +Defaults are 0x1000 for measure and 0x1000 for sleep. With default values touchRead takes 0.5ms. + +.. code-block:: arduino + + void touchSetCycles(uint16_t measure, uint16_t sleep); + +* ``measure`` Sets time it takes to measure touch pad value +* ``sleep`` Sets waiting time before next measure cycle + +touchAttachInterrupt +^^^^^^^^^^^^^^^^^^^^ + +This function is used to attach interrupt to touch pad. The function will be called if a touch pad value falls below the given +threshold for ESP32 / rises above the given threshold for ESP32-S2/S3. To determine a proper threshold values between touched +and untouched state use touchRead. + +.. code-block:: arduino + + void touchAttachInterrupt(uint8_t pin, void (*userFunc)(void), touch_value_t threshold); + +* ``pin`` GPIO TOUCH pad pin +* ``userFunc`` Function to be called when interrupt is triggered +* ``threshold`` Sets the threshold when to call interrupt + +touchAttachInterruptArg +^^^^^^^^^^^^^^^^^^^^^^^ + +This function is used to attach interrupt to touch pad. In the function called by ISR you have the given arguments available. + +.. code-block:: arduino + + void touchAttachInterruptArg(uint8_t pin, void (*userFunc)(void*), void *arg, touch_value_t threshold); + +* ``pin`` GPIO TOUCH pad pin +* ``userFunc`` Function to be called when interrupt is triggered +* ``arg`` Sets arguments to the interrupt +* ``threshold`` Sets the threshold when to call interrupt + +touchDetachInterrupt +^^^^^^^^^^^^^^^^^^^^ + +This function is used to detach interrupt from touch pad. + +.. code-block:: arduino + + void touchDetachInterrupt(uint8_t pin); + +* ``pin`` GPIO TOUCH pad pin. + +TOUCH API specific for ESP32 chip (TOUCH_V1) +******************************************** + +touchInterruptSetThresholdDirection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function is used to tell the driver if it shall activate the interrupt if the sensor is lower or higher than +the threshold value. Default is lower. + +.. code-block:: arduino + + void touchInterruptSetThresholdDirection(bool mustbeLower); + +TOUCH API specific for ESP32S2 and ESP32S3 chip (TOUCH_V2) +********************************************************** + +touchInterruptGetLastStatus +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function is used get the lastest ISR status for the touch pad. + +.. code-block:: arduino + + bool touchInterruptGetLastStatus(uint8_t pin); + +This function returns true if touch pad has been and continues pressed or false otherwise. + +Example Applications +******************** + +Here are 2 examples of how to use the touchRead and touch interrupts. + +.. literalinclude:: ../../../libraries/ESP32/examples/Touch/TouchRead/TouchRead.ino + :language: arduino + +.. literalinclude:: ../../../libraries/ESP32/examples/Touch/TouchInterrupt/TouchInterrupt.ino + :language: arduino From ee763e5764faa92e241bfb353be79cbb73a8fd53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 1 Nov 2022 14:47:51 +0100 Subject: [PATCH 2/5] update touchRead comment in header file --- cores/esp32/esp32-hal-touch.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cores/esp32/esp32-hal-touch.h b/cores/esp32/esp32-hal-touch.h index a8cda191c31..2dd7dda1f79 100644 --- a/cores/esp32/esp32-hal-touch.h +++ b/cores/esp32/esp32-hal-touch.h @@ -49,7 +49,8 @@ typedef uint32_t touch_value_t; void touchSetCycles(uint16_t measure, uint16_t sleep); /* - * Read touch pad (values close to 0 mean touch detected) + * Read touch pad (for ESP32 values close to 0 mean touch detected / + * for ESP32-S2/S3 higher values meand touch detected) * You can use this method to chose a good threshold value * to use as value for touchAttachInterrupt * */ From 3dca0b5f3ff23d8e8e55b9ded3cab9f72d95d830 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Tue, 1 Nov 2022 14:56:39 +0100 Subject: [PATCH 3/5] Edited examples --- docs/source/api/touch.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/source/api/touch.rst b/docs/source/api/touch.rst index 1596db02da7..2b2d4712ab7 100644 --- a/docs/source/api/touch.rst +++ b/docs/source/api/touch.rst @@ -113,10 +113,14 @@ This function returns true if touch pad has been and continues pressed or false Example Applications ******************** -Here are 2 examples of how to use the touchRead and touch interrupts. +Example of reading the touch pad. .. literalinclude:: ../../../libraries/ESP32/examples/Touch/TouchRead/TouchRead.ino :language: arduino +Example of usage the touch interrupts. + .. literalinclude:: ../../../libraries/ESP32/examples/Touch/TouchInterrupt/TouchInterrupt.ino :language: arduino + +More examples can be found in our repository -> `Touch examples `_. \ No newline at end of file From a261a6df2d451378485df270b6e383792609eb43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 3 Nov 2022 11:02:51 +0100 Subject: [PATCH 4/5] typo changes + updates --- cores/esp32/esp32-hal-touch.h | 2 +- docs/source/api/touch.rst | 23 ++++++++++++----------- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/cores/esp32/esp32-hal-touch.h b/cores/esp32/esp32-hal-touch.h index 2dd7dda1f79..e62a4166206 100644 --- a/cores/esp32/esp32-hal-touch.h +++ b/cores/esp32/esp32-hal-touch.h @@ -50,7 +50,7 @@ void touchSetCycles(uint16_t measure, uint16_t sleep); /* * Read touch pad (for ESP32 values close to 0 mean touch detected / - * for ESP32-S2/S3 higher values meand touch detected) + * for ESP32-S2/S3 higher values mean touch detected) * You can use this method to chose a good threshold value * to use as value for touchAttachInterrupt * */ diff --git a/docs/source/api/touch.rst b/docs/source/api/touch.rst index 2b2d4712ab7..f5b1845ba01 100644 --- a/docs/source/api/touch.rst +++ b/docs/source/api/touch.rst @@ -20,7 +20,8 @@ TOUCH common API touchRead ^^^^^^^^^ -This function is used to get the TOUCH pad value for a given pin. +This function gets the touch sensor data. Each touch sensor has a counter to count the number of charge/discharge cycles. When the pad is ‘touched’, +the value in the counter will change because of the larger equivalent capacitance. The change of the data determines if the pad has been touched or not. .. code-block:: arduino @@ -34,21 +35,21 @@ touchSetCycles ^^^^^^^^^^^^^^ This function is used to set cycles that measurement operation takes. The result from touchRead, threshold and detection accuracy depend on these values. -Defaults are 0x1000 for measure and 0x1000 for sleep. With default values touchRead takes 0.5ms. +The defaults are setting touchRead to take ~0.5ms. .. code-block:: arduino void touchSetCycles(uint16_t measure, uint16_t sleep); -* ``measure`` Sets time it takes to measure touch pad value +* ``measure`` Sets the time that it takes to measure touch sensor value * ``sleep`` Sets waiting time before next measure cycle touchAttachInterrupt ^^^^^^^^^^^^^^^^^^^^ -This function is used to attach interrupt to touch pad. The function will be called if a touch pad value falls below the given -threshold for ESP32 / rises above the given threshold for ESP32-S2/S3. To determine a proper threshold values between touched -and untouched state use touchRead. +This function is used to attach interrupt to the touch pad. The function will be called if a touch sensor value falls below the given +threshold for ESP32 or rises above the given threshold for ESP32-S2/S3. To determine a proper threshold value between touched and untouched state, +use touchRead() function. .. code-block:: arduino @@ -61,7 +62,7 @@ and untouched state use touchRead. touchAttachInterruptArg ^^^^^^^^^^^^^^^^^^^^^^^ -This function is used to attach interrupt to touch pad. In the function called by ISR you have the given arguments available. +This function is used to attach interrupt to the touch pad. In the function called by ISR you have the given arguments available. .. code-block:: arduino @@ -75,7 +76,7 @@ This function is used to attach interrupt to touch pad. In the function called b touchDetachInterrupt ^^^^^^^^^^^^^^^^^^^^ -This function is used to detach interrupt from touch pad. +This function is used to detach interrupt from the touch pad. .. code-block:: arduino @@ -108,17 +109,17 @@ This function is used get the lastest ISR status for the touch pad. bool touchInterruptGetLastStatus(uint8_t pin); -This function returns true if touch pad has been and continues pressed or false otherwise. +This function returns true if the touch pad has been and continues pressed or false otherwise. Example Applications ******************** -Example of reading the touch pad. +Example of reading the touch sensor. .. literalinclude:: ../../../libraries/ESP32/examples/Touch/TouchRead/TouchRead.ino :language: arduino -Example of usage the touch interrupts. +A usage example for the touch interrupts. .. literalinclude:: ../../../libraries/ESP32/examples/Touch/TouchInterrupt/TouchInterrupt.ino :language: arduino From e2dd596271cddc3485579fb96f725e0ae37ca8ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Procha=CC=81zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Thu, 3 Nov 2022 13:14:10 +0100 Subject: [PATCH 5/5] about edit --- docs/source/api/touch.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/api/touch.rst b/docs/source/api/touch.rst index f5b1845ba01..75715ffed70 100644 --- a/docs/source/api/touch.rst +++ b/docs/source/api/touch.rst @@ -5,9 +5,10 @@ TOUCH About ----- -Touch sensor is a peripheral, that can be used to sense electrical changes on respective GPIO pins. Therefore these touch sensors -are also known as capacitive sensors. For example, if you touch any of these pins, the touch sensor will sense output according to -electrical charge on your finger. These pins can be easily integrated into capacitive pads, and replace mechanical buttons. +Touch sensor is a peripheral, that has an internal oscilator circuit and it measures charge/discharge frequency over a fixed period of time on respective GPIO pins. +Therefore these touch sensors are also known as capacitive sensors. For example, if you touch any of these pins, finger electrical charge will change this number of cycles, +by changing the RC circuit attached to the touch sensor. The TouchRead() will return the number of cycles (charges/discharges) in a certain time (meas). +The change of this count will be used to validate if a touch has happened or not. These pins can be easily integrated into capacitive pads, and replace mechanical buttons. .. note:: Touch peripheral is not present in every SoC. Refer to datasheet of each chip for more info.