Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-12-25 17:17:54 +01:00
Code Issues Projects Releases Wiki Activity

Update the touchscreen document's (#3487)

Browse Source 
* 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 2024-01-03 17:01:11 +01:00 committed by GitHub
parent 4b5a5159ff
commit 5cc4b67696
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 164 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
components/touchscreen/index.rst
View File

@ -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

138
components/touchscreen/xpt2046.rst
View File

@ -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,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
--------