diff --git a/components/touchscreen/ft63x6.rst b/components/touchscreen/ft63x6.rst new file mode 100644 index 000000000..b206d21cb --- /dev/null +++ b/components/touchscreen/ft63x6.rst @@ -0,0 +1,61 @@ +FT63X6 Touchscreen Controller +================================ + +.. seo:: + :description: Instructions for setting up FT63X6 touchscreen controller with ESPHome + :image: wt32-sc01.png + :keywords: FT63X6, WT32-SC01 + +The ``ft63x6`` component allows using the touchscreen controller found in +`Seeed Studio's WT32-SC01 `__ +with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. + +.. code-block:: yaml + + # Example configuration entry + esp32: + board: m5stack-core2 + framework: + type: arduino + + i2c: + sda: GPIO18 + scl: GPIO19 + scan: false + + output: + - platform: ledc + pin: GPIO23 + id: screen_led + + light: + - platform: monochromatic + output: screen_led + default_transition_length: 0.2s + name: 'Backlight' + restore_mode: ALWAYS_ON + + touchscreen: + - platform: ft63x6 + interrupt_pin: GPIO39 + on_touch: + - logger.log: + format: Touch %d at (%d, %d) + args: [touch.id, touch.x, touch.y] + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **reset_pin** (*Optional*, :ref:`Pin Schema `): The reset pin of the controller. +- **interrupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. + +- All other options from :ref:`config-touchscreen`. + +See Also +-------- + +- :doc:`Touchscreen ` +- :apiref:`ft63x6/ft63x6.h` +- :ghedit:`Edit` diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst index 586ec40af..26ea94196 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -5,7 +5,7 @@ Touchscreen Components :description: Instruction for using touchscreen components. :image: folder-open.svg -The ``touchscreen`` component holds the base code for most touchscreen components +The ``touchscreen`` component contains the base code for most touchscreen driver components available in ESPHome and is responsible for passing the touch events to ``binary_sensors`` with the ``touchscreen`` platform. @@ -19,28 +19,82 @@ Base Touchscreen Configuration # Example touchscreen touchscreen: - platform: ... + display: display1 on_touch: then: ... + on_update: + then: + ... + on_release: + then: + ... 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. - **on_touch** (*Optional*, :ref:`Automation `): An automation to perform when the touchscreen is touched. See :ref:`touchscreen-on_touch`. -- **display** (**Required**, :ref:`config-id`): The display to use. If only one display is - available, this can be omitted. +- **on_update** (*Optional*, :ref:`Automation `): An automation to perform + when the touchscreen is touched. See :ref:`touchscreen-on_update`. +- **on_release** (*Optional*, :ref:`Automation `): An automation to perform + when the touchscreen is no longer touched. See :ref:`touchscreen-on_release`. + + +.. _touchscreen-touchpoint: + +``TouchPoint`` Argument Type +---------------------------- + +Both the :ref:`touchscreen-on_touch` and :ref:`touchscreen-on_update` have an argument of the type :apistruct:`touchscreen::TouchPoint` in a +list (``on_update``) or as an ``optional`` (``on_touch``). + +The integer members for the touch positions below are in relation to the display width and height: + +- ``x`` and ``y`` are the current position. +- ``x_last`` and ``y_last`` are the previous position. +- ``x_first`` and ``y_first`` are the position of the touch when it was first detected. +- ``x_raw`` and ``y_raw`` are for calibrating the touchscreen in relation of the display. This replaces the properties with the same name in the touchscreen classes. + +- ``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-on_touch: ``on_touch`` Trigger -------------------- -This automation will be triggered when the touchscreen detects a touch. +This automation will be triggered when the touchscreen initially detects a touch on the touchscreen; it will not be fired again until +all touches (for multi-touch supported drivers) are released. + +NOTE: This has changed (from ESPHome 2023.11.6.) To receive continuous updates from touch drags, use :ref:`touchscreen-on_update`. + +This trigger provides two arguments named ``touch`` of type *touchpoint* and ``touches`` with a list of all touches. + +.. _touchscreen-on_update: + +``on_update`` Trigger +--------------------- + +This new automation will be triggered when the touchscreen detects an extra touch or that a touch has moved around on the screen. + + +This trigger provides one argument named ``touches`` of type :apiref:`touchscreen::TouchPoints_t` which has a list of + :ref:`touchscreen-touchpoint`. + +This trigger may be useful to detect gestures such as swiping across the display. + + +.. _touchscreen-on_release: + +``on_release`` Trigger +---------------------- + +This automation will be triggered when all touches are released from the touchscreen. + +At this point of time it has no extra arguments. -This trigger provides one argument named ``touch`` of type :apistruct:`touchscreen::TouchPoint` which has two integer members: ``x`` and ``y`` which -represent the position of the touch in relation to the display width and height. It also has optional members that will be set -depending on the touchscreen platform. Binary Sensor ------------- diff --git a/components/touchscreen/xpt2046.rst b/components/touchscreen/xpt2046.rst index d000fa970..f3b8ac79a 100644 --- a/components/touchscreen/xpt2046.rst +++ b/components/touchscreen/xpt2046.rst @@ -108,10 +108,10 @@ values nor ``swap_x_y``. on_touch: - lambda: |- ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%0d", - id(my_touchscreen).x, - id(my_touchscreen).y, - id(my_touchscreen).x_raw, - id(my_touchscreen).y_raw + 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 @@ -175,9 +175,9 @@ using a display lambda similar to the following. display: - platform: ili9341 lambda: |- - it.fill(BLACK); - if (id(my_touchscreen).touched) - it.filled_circle(id(my_touchscreen).x, id(my_touchscreen).y, 10, RED); + 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 diff --git a/images/wt32-sc01.png b/images/wt32-sc01.png new file mode 100644 index 000000000..1c0ccfa03 Binary files /dev/null and b/images/wt32-sc01.png differ diff --git a/index.rst b/index.rst index 41b0fde4c..57007ce2b 100644 --- a/index.rst +++ b/index.rst @@ -680,10 +680,10 @@ Touchscreen Components EKTF2232, components/touchscreen/ektf2232, ektf2232.svg, Inkplate 6 Plus Lilygo T5 4.7", components/touchscreen/lilygo_t5_47, lilygo_t5_47_touch.jpg TT21100, components/touchscreen/tt21100, esp32-s3-korvo-2-lcd.png - GT911, components/touchscreen/gt911, esp32_s3_box_3.png XPT2046, components/touchscreen/xpt2046, xpt2046.jpg - - + GT911, components/touchscreen/gt911, esp32_s3_box_3.png + FT63X6, components/touchscreen/ft63x6, wt32-sc01.png + Cover Components ----------------