From 5cc4b6769664d1e218a31e64c4cd8ea675fbfba6 Mon Sep 17 00:00:00 2001 From: NP v/d Spek Date: Wed, 3 Jan 2024 17:01:11 +0100 Subject: [PATCH] Update the touchscreen document's (#3487) * Update Touchscreen documentation move the XPT2046 component to the right section. * search what is wrong * fix typo * restore last fix * Update index.rst * try to resolve the issue by removing the ref-link * Update index.rst * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski * opdate xpt2046 doc for new Touchscreen component. * add documentation for the ft63x6 touchscreen * add new-line * Move image around * Update components/touchscreen/index.rst * Update components/touchscreen/index.rst * Update components/touchscreen/index.rst * Update components/touchscreen/index.rst * Update touchscreen documentation needed to be updated * fix reported issue * fix reported issue * fix reported ref issue --------- Co-authored-by: Keith Burzinski Co-authored-by: Clyde Stubbs <2366188+clydebarrow@users.noreply.github.com> --- components/touchscreen/index.rst | 152 ++++++++++++++++++++++++++++- components/touchscreen/xpt2046.rst | 138 +++----------------------- 2 files changed, 164 insertions(+), 126 deletions(-) diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst index 26ea94196..a171b650d 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -9,6 +9,15 @@ The ``touchscreen`` component contains the base code for most touchscreen driver available in ESPHome and is responsible for passing the touch events to ``binary_sensors`` with the ``touchscreen`` platform. +.. warning:: + + As of version **2023.12** the way how the touchscreen component has changed a bit. + The following variables are now obsolite: + * **rotation** is (temporary) removed in favor the *new* **transform:** + * **size_x_y** is moved inside the **transform:** and renamed to **size_xy** + * **report_interval** is removed in favor of using the **update_interval** + The display id is only just to calculate the touch position reletive to the displays *height* and *width* + .. _config-touchscreen: Base Touchscreen Configuration @@ -20,6 +29,14 @@ Base Touchscreen Configuration touchscreen: - platform: ... display: display1 + transform: + mirror_x: false + mirror_y: false + swap_xy: false + calibration: + x_max: 240 + y_max: 320 + on_touch: then: ... @@ -32,7 +49,26 @@ Base Touchscreen Configuration Configuration variables: ************************ -- **display** (*Required*, :ref:`config-id`): The display to use this touchscreen with. This will be provided automatically if only one display is configured on the device. +- **display** (*Required*, :ref:`config-id`): The display to use this touchscreen with. +- **transform** (*Optional*): Transform the touchscreen presentation using hardware. All defaults are ``false``. + + - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes. + - **mirror_x** (*Optional*, boolean): If true, mirror the x axis. + - **mirror_y** (*Optional*, boolean): If true, mirror the y axis. + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the touchscreen. Defaults to ``never``. +- **calibration** (*Optional*): When the touchscreen is not given the right configuration settings. You can set them here. + + - **x_min** (*Optional*, int): The raw value corresponding to the left + (or top if ``swap_xy`` is specified) edge of the touchscreen. See :ref:`touchscreen-calibration` + for the process to calibrate the touchscreen. Defaults to ``0``. + - **x_max** (*Optional*, int): The raw value corresponding to the right + (or bottom if ``swap_xy`` is specified) edge of the touchscreen. Defaults to ``0``. + - **y_min** (*Optional*, int): The raw value corresponding to the top + (or left if ``swap_xy`` is specified) edge of the touchscreen. Defaults to ``0``. + - **y_max** (*Optional*, int): The raw value corresponding to the bottom + (or right if ``swap_xy`` is specified) edge of the touchscreen. Defaults to ``0``. + - **on_touch** (*Optional*, :ref:`Automation `): An automation to perform when the touchscreen is touched. See :ref:`touchscreen-on_touch`. @@ -60,6 +96,120 @@ The integer members for the touch positions below are in relation to the display - ``id`` is a number provided by the touchscreen to uniquely identify the touch on a multi-touch screen. - ``state`` indicates the state of the touch. This can be **1**, indicating it is an initial touch, or **2** indicating the touch position has changed/moved. +.. _touchscreen-calibration: + +Calibration +----------- + +For most of the touchscreen drivers the dimensions of the touchscreen are automatically set when the driver is setup. +In some cases like for the **XPT2046** this can be different per used display panel. +Then you can set the values using the **calibrate** values. + +To match the point of the touch to the display coordinates the touch screen has to be calibrated. +The touchscreen component returns raw values in the 0 to 4095 range. Those raw values are available +as the ``x_raw`` and ``y_raw`` member variables and for example write them out as in the example +:ref:`touchscreen-on_touch`. The goal of the calibration is to identify the raw values corresponding +to the edges of the screen. + +The calibration assumes a display oriented in a way that you will be using it, i.e. your +:ref:`display-engine` component has to have the [0,0] logical coordinate at the top left. + +.. note:: + + Do not set any calibration values nor ``transform`` settings. + +.. code-block:: yaml + + # Touchscreen + touchscreen: + platform: xpt2046 + id: my_touchscreen + cs_pin: 17 + on_touch: + - lambda: |- + ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%0d", + touch.x, + touch.y, + touch.x_raw, + touch.y_raw + ); + +Get a stylus or a similar object, run the project and touch the corners of the screen at +the edge pixels. Repeat several times and note minimum and maximum x and y raw values. + +.. warning:: + + As long the calibrate settings are not correctly set, the ``x`` and ``y`` coordinates are not calculated. + + +.. code-block:: none + + ... top left ... + [21:07:48][I][cal:071]: x=217, y=34, x_raw=3718, y_raw=445 + [21:07:49][I][cal:071]: x=222, y=32, x_raw=3804, y_raw=419 + ... top right ... + [21:07:52][I][cal:071]: x=19, y=36, x_raw=334, y_raw=370 + [21:07:52][I][cal:071]: x=22, y=35, x_raw=386, y_raw=347 + ... bottom left ... + [21:08:00][I][cal:071]: x=224, y=299, x_raw=3836, y_raw=3835 + [21:08:00][I][cal:071]: x=225, y=303, x_raw=3848, y_raw=3878 + [21:08:01][I][cal:071]: x=223, y=299, x_raw=3807, y_raw=3829 + ... bottom right ... + [21:08:11][I][cal:071]: x=16, y=299, x_raw=281, y_raw=3839 + [21:08:12][I][cal:071]: x=19, y=302, x_raw=328, y_raw=3866 + [21:08:13][I][cal:071]: x=20, y=296, x_raw=358, y_raw=3799 + +That means that the minimum raw x is 281, maximum 3848, minimum y 347 and maximum 3878. + +Identify which raw value is the display's x direction and what the y one. In our case +moving right decreases the x raw value and going down increases the y one so the axes +match and we *don't* need to use ``swap_xy``. If the raw x is the display's y, +use ``swap_xy = true``. + +If one of the coordinates goes in the "wrong" direction it needs to be inverted. +The inversion is performed by setting the ``mirror_x`` and/or ``mirror_y`` to true. + + +.. code-block:: yaml + + touchscreen: + platform: xpt2046 + calibration_x_min: 3848 + calibration_x_max: 281 + calibration_y_min: 347 + calibration_y_max: 3878 + +Compile, run and click on the edges again. The x and y should now match the coordinates +of the display. + +.. code-block:: none + + [21:32:34][I][cal:071]: x=7, y=6, x_raw=3755, y_raw=407 + [21:32:37][I][cal:071]: x=237, y=4, x_raw=313, y_raw=385 + [21:32:43][I][cal:071]: x=239, y=318, x_raw=284, y_raw=3845 + [21:33:05][I][cal:071]: x=2, y=313, x_raw=3821, y_raw=3793 + +Note that the touch screen is not extremely precise and there might be nonlinearities +or similar errors so don't expect a pixel-perfect precision. You can verify the touchpoint +using a display lambda similar to the following. + +.. code-block:: yaml + + display: + - platform: ili9341 + lambda: |- + auto touch = id(my_touchscreen)->get_touch(); + if (touch) // or touch.has_value() + it.filled_circle(touch.value().x, touch.value().y, 10, RED); + +To be exact, the component does the following + +- reads the raw x and y and normalizes it using (non-inverted) min and max values +- swaps x and y if needed +- inverts if needed +- scales to the display dimensions + + .. _touchscreen-on_touch: ``on_touch`` Trigger diff --git a/components/touchscreen/xpt2046.rst b/components/touchscreen/xpt2046.rst index f3b8ac79a..7de79555b 100644 --- a/components/touchscreen/xpt2046.rst +++ b/components/touchscreen/xpt2046.rst @@ -31,14 +31,12 @@ The :ref:`SPI ` is required to be set up in your configuration for this sen cs_pin: 17 interrupt_pin: 16 update_interval: 50ms - report_interval: 1s threshold: 400 - calibration_x_min: 3860 - calibration_x_max: 280 - calibration_y_min: 340 - calibration_y_max: 3860 - swap_x_y: false - + calibration: + x_min: 3860 + x_max: 280 + y_min: 340 + y_max: 3860 Configuration variables: ------------------------ @@ -59,134 +57,24 @@ Base Configuration: sensor. If ``interrupt_pin`` is specified the touch will be detected nearly instantaneously and this setting will be used only for the release detection. Defaults to ``50ms``. -- **report_interval** (*Optional*, :ref:`config-time`): The interval to periodically - report the coordinates while the touch screen is touched. Defaults to ``never``. - - **threshold** (*Optional*, int): The value to detect the touch or release. Defaults to ``400``. -- **calibration_x_min** (*Optional*, int): The raw value corresponding to the left - (or top if ``swap_x_y`` is specified) edge of the display. See :ref:`xpt2046-calibration` - for the process to calibrate the touch screen. Defaults to ``0``. -- **calibration_x_max** (*Optional*, int): The raw value corresponding to the right - (or bottom if ``swap_x_y`` is specified) edge of the display. Defaults to ``4095``. +- **calibration_x_min** (*Depricated*): This value is moved to the ``calibration`` values -- **calibration_y_min** (*Optional*, int): The raw value corresponding to the top - (or left if ``swap_x_y`` is specified) edge of the display. Defaults to ``0``. +- **calibration_x_max** (*Depricated*): This value is moved to the ``calibration`` values. -- **calibration_y_max** (*Optional*, int): The raw value corresponding to the bottom - (or right if ``swap_x_y`` is specified) edge of the display. Defaults to ``4095``. +- **calibration_y_min** (*Depricated*): This value is moved to the ``calibration`` values. -- **swap_x_y** (*Optional*, boolean): If true the x and y axes are swapped. Defaults to ``false``. +- **calibration_y_max** (*Depricated*): This value is moved to the ``calibration`` values. + +- **swap_x_y** (*Depricated*): This value is moved to the ``transform`` values as ``swap_xy`` see :ref:`config-touchscreen`. + +- **report_interval** (*Depricated*): This interval is removed in favor of the ``update_interval``. - All other options from :ref:`config-touchscreen`. -.. _xpt2046-calibration: - -Calibration ------------ - -To match the point of the touch to the display coordinates the touch screen has to be calibrated. -The XPT2046 component returns raw values in the 0 to 4095 range. Those raw values are available -as the ``x_raw`` and ``y_raw`` member variables and for example write them out as in the example -:ref:`touchscreen-on_touch`. The goal of the calibration is to identify the raw values corresponding -to the edges of the screen. - -The calibration assumes a display oriented in a way that you will be using it, i.e. your -:ref:`display-engine` component has to have the [0,0] logical coordinate at the top left. -Set the dimensions as ``dimension_x`` and ``dimension_y`` and do not set any calibration -values nor ``swap_x_y``. - -.. code-block:: yaml - - # Touchscreen - touchscreen: - platform: xpt2046 - id: my_touchscreen - cs_pin: 17 - on_touch: - - lambda: |- - ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%0d", - touch.x, - touch.y, - touch.x_raw, - touch.y_raw - ); - -Get a stylus or a similar object, run the project and touch the corners of the screen at -the edge pixels. Repeat several times and note minimum and maximum x and y raw values. - -.. code-block:: none - - ... top left ... - [21:07:48][I][cal:071]: x=217, y=34, x_raw=3718, y_raw=445 - [21:07:49][I][cal:071]: x=222, y=32, x_raw=3804, y_raw=419 - ... top right ... - [21:07:52][I][cal:071]: x=19, y=36, x_raw=334, y_raw=370 - [21:07:52][I][cal:071]: x=22, y=35, x_raw=386, y_raw=347 - ... bottom left ... - [21:08:00][I][cal:071]: x=224, y=299, x_raw=3836, y_raw=3835 - [21:08:00][I][cal:071]: x=225, y=303, x_raw=3848, y_raw=3878 - [21:08:01][I][cal:071]: x=223, y=299, x_raw=3807, y_raw=3829 - ... bottom right ... - [21:08:11][I][cal:071]: x=16, y=299, x_raw=281, y_raw=3839 - [21:08:12][I][cal:071]: x=19, y=302, x_raw=328, y_raw=3866 - [21:08:13][I][cal:071]: x=20, y=296, x_raw=358, y_raw=3799 - -That means that the minimum raw x is 281, maximum 3848, minimum y 347 and maximum 3878. - -Identify which raw value is the display's x direction and what the y one. In our case -moving right decreases the x raw value and going down increases the y one so the axes -match and we *don't* need to use ``swap_x_y``. If the raw x is the display's y, -use ``swap_x_y = true``. - -If one of the coordinates goes in the "wrong" direction it needs to be inverted. -The inversion is performed by swapping the minimum and maximum values. In our -case the horizontal direction represented by the raw x (no swap) is inverted -so the ``calibration_x_min`` needs to be larger than ``calibration_x_max``. -The vertical direction is fine. The configuration would thus be - -.. code-block:: yaml - - touchscreen: - platform: xpt2046 - calibration_x_min: 3848 - calibration_x_max: 281 - calibration_y_min: 347 - calibration_y_max: 3878 - -Compile, run and click on the edges again. The x and y should now match the coordinates -of the display. - -.. code-block:: none - - [21:32:34][I][cal:071]: x=7, y=6, x_raw=3755, y_raw=407 - [21:32:37][I][cal:071]: x=237, y=4, x_raw=313, y_raw=385 - [21:32:43][I][cal:071]: x=239, y=318, x_raw=284, y_raw=3845 - [21:33:05][I][cal:071]: x=2, y=313, x_raw=3821, y_raw=3793 - -Note that the touch screen is not extremely precise and there might be nonlinearities -or similar errors so don't expect a pixel-perfect precision. You can verify the touchpoint -using a display lambda similar to the following. - -.. code-block:: yaml - - display: - - platform: ili9341 - lambda: |- - auto touch = id(my_touchscreen)->get_touch(); - if (touch) // or touch.has_value() - it.filled_circle(touch.value().x, touch.value().y, 10, RED); - -To be exact, the component does the following - -- reads the raw x and y and normalizes it using (non-inverted) min and max values -- swaps x and y if needed -- inverts if needed -- scales to the display dimensions - - See Also --------