mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-13 20:11:53 +01:00
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 <kbx81x@gmail.com> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> * Update components/touchscreen/index.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> * 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 <kbx81x@gmail.com> Co-authored-by: Clyde Stubbs <2366188+clydebarrow@users.noreply.github.com>
This commit is contained in:
NP v/d Spek
GitHub
parent
4b5a5159ff
commit
5cc4b67696
@ -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
|
available in ESPHome and is responsible for passing the touch events to
|
||||||
``binary_sensors`` with the ``touchscreen`` platform.
|
``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:
|
.. _config-touchscreen:
|
||||||
|
|
||||||
Base Touchscreen Configuration
|
Base Touchscreen Configuration
|
||||||
@ -20,6 +29,14 @@ Base Touchscreen Configuration
|
|||||||
touchscreen:
|
touchscreen:
|
||||||
- platform: ...
|
- platform: ...
|
||||||
display: display1
|
display: display1
|
||||||
|
transform:
|
||||||
|
mirror_x: false
|
||||||
|
mirror_y: false
|
||||||
|
swap_xy: false
|
||||||
|
calibration:
|
||||||
|
x_max: 240
|
||||||
|
y_max: 320
|
||||||
|
|
||||||
on_touch:
|
on_touch:
|
||||||
then:
|
then:
|
||||||
...
|
...
|
||||||
@ -32,7 +49,26 @@ Base Touchscreen Configuration
|
|||||||
|
|
||||||
Configuration variables:
|
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
|
- **on_touch** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
||||||
when the touchscreen is touched. See :ref:`touchscreen-on_touch`.
|
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.
|
- ``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.
|
- ``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:
|
.. _touchscreen-on_touch:
|
||||||
|
|
||||||
``on_touch`` Trigger
|
``on_touch`` Trigger
|
||||||
|
|||||||
@ -31,14 +31,12 @@ The :ref:`SPI <spi>` is required to be set up in your configuration for this sen
|
|||||||
cs_pin: 17
|
cs_pin: 17
|
||||||
interrupt_pin: 16
|
interrupt_pin: 16
|
||||||
update_interval: 50ms
|
update_interval: 50ms
|
||||||
report_interval: 1s
|
|
||||||
threshold: 400
|
threshold: 400
|
||||||
calibration_x_min: 3860
|
calibration:
|
||||||
calibration_x_max: 280
|
x_min: 3860
|
||||||
calibration_y_min: 340
|
x_max: 280
|
||||||
calibration_y_max: 3860
|
y_min: 340
|
||||||
swap_x_y: false
|
y_max: 3860
|
||||||
|
|
||||||
|
|
||||||
Configuration variables:
|
Configuration variables:
|
||||||
------------------------
|
------------------------
|
||||||
@ -59,134 +57,24 @@ Base Configuration:
|
|||||||
sensor. If ``interrupt_pin`` is specified the touch will be detected nearly instantaneously and this setting
|
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``.
|
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``.
|
- **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
|
- **calibration_x_min** (*Depricated*): This value is moved to the ``calibration`` values
|
||||||
(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
|
- **calibration_x_max** (*Depricated*): This value is moved to the ``calibration`` values.
|
||||||
(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
|
- **calibration_y_min** (*Depricated*): This value is moved to the ``calibration`` values.
|
||||||
(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``.
|
- **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`.
|
- 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
|
See Also
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user