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 <[email protected]> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <[email protected]> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <[email protected]> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <[email protected]> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <[email protected]> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <[email protected]> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <[email protected]> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <[email protected]> * 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 <[email protected]> Co-authored-by: Clyde Stubbs <[email protected]>
esphome · Jan 3, 2024 · 5cc4b67 · 5cc4b67
1 parent 4b5a515
commit 5cc4b67
Show file tree

Hide file tree

Showing 2 changed files with 163 additions and 125 deletions.
diff --git 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 <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
@@ -31,14 +31,12 @@ The :ref:`SPI <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,132 +57,22 @@ 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_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_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``.
-
-- **swap_x_y** (*Optional*, boolean): If true the x and y axes are swapped. Defaults to ``false``.
-
-- 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
+- **calibration_x_min** (*Depricated*): This value is moved to the ``calibration`` values
 
-Compile, run and click on the edges again. The x and y should now match the coordinates
-of the display.
+- **calibration_x_max** (*Depricated*): This value is moved to the ``calibration`` values.
 
-.. code-block:: none
+- **calibration_y_min** (*Depricated*): This value is moved to the ``calibration`` values.
 
-    [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
+- **calibration_y_max** (*Depricated*): This value is moved to the ``calibration`` values.
 
-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.
+- **swap_x_y** (*Depricated*): This value is moved to the ``transform`` values as ``swap_xy`` see :ref:`config-touchscreen`.
 
-.. code-block:: yaml
+- **report_interval** (*Depricated*): This interval is removed in favor of the ``update_interval``.
 
-    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
+- All other options from :ref:`config-touchscreen`.
 
 
 See Also