diff --git a/components/touchscreen/gt911.rst b/components/touchscreen/gt911.rst new file mode 100644 index 000000000..a1182c6f8 --- /dev/null +++ b/components/touchscreen/gt911.rst @@ -0,0 +1,72 @@ +gt911 Touch Screen Controller +=============================== + +.. seo:: + :description: Instructions for setting up gt911 touch screen controller with ESPHome + :image: esp32_s3_box_3.png + :keywords: GT911, ESP32-S3-BOX-3 + +The ``gt911`` touchscreen platform allows using the touch screen controllers based on the gt911 chip with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration for this touchscreen to work. + +This controller is used in the Espressif ESP32-S3-BOX-3 and the m5paper; + + +.. figure:: images/esp32_s3_box_3.png + :align: center + :width: 50.0% + + gt911 touchscreen on ESP32-S3-BOX-3 + +Base Touchscreen Configuration +------------------------------ + +.. code-block:: yaml + + # Example configuration entry + touchscreen: + platform: gt911 + id: my_touchscreen + interrupt_pin: GPIO3 + +Configuration variables: +************************ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **interrupt_pin** (**Required**, :ref:`Pin Schema `): The touch detection pin. +- **rotation** (*Optional*): Set the rotation of the touchscreen. By default this will be set to match the display associated with the touchscreen, but this allows more control. Choices are ``0``, ``90``, ``180`` and ``270``. + +- All other options from :ref:`Touchscreen `. + +Binary Sensor +------------- + +In addition to touch areas on the screen configured through the :ref:`Touchscreen ` component, +the gt911 supports up to four buttons located outside of the normal touchscreen area. +On the ESP32-S3-BOX-3 the red circle below the display is such a button. +A binary sensor can be configured to react to touching these buttons. + +.. code-block:: yaml + + # Example configuration entry + binary_sensor: + - platform: gt911 + name: "Home" + index: 0 + +Configuration variables: +************************ + +- **gt911_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the touchscreen. +- **index** (*Optional*, int): Internal index of the touch button, between 0 and 3. The default is 0. + +- All other options from :ref:`Binary Sensor `. + + +See Also +-------- + +- :ref:`Binary Sensor Filters ` +- :apiref:`gt911/touchscreen/gt911.h` +- :apiref:`gt911/binary_sensor/gt911_button.h` +- :ghedit:`Edit` diff --git a/components/touchscreen/images/esp32_s3_box_3.png b/components/touchscreen/images/esp32_s3_box_3.png new file mode 100644 index 000000000..75c7a1774 Binary files /dev/null and b/components/touchscreen/images/esp32_s3_box_3.png differ diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst index 2357f646b..586ec40af 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -82,6 +82,7 @@ See Also - :doc:`EKTF2232 ` - :doc:`XPT2046 ` - :doc:`TT21100 ` +- :doc:`GT911 ` - :apiref:`touchscreen/touchscreen.h` - :apiref:`touchscreen/binary_sensor/touchscreen_binary_sensor.h` - :ghedit:`Edit` diff --git a/images/esp32_s3_box_3.png b/images/esp32_s3_box_3.png new file mode 100644 index 000000000..75c7a1774 Binary files /dev/null and b/images/esp32_s3_box_3.png differ diff --git a/index.rst b/index.rst index 3045f33be..f35cbc085 100644 --- a/index.rst +++ b/index.rst @@ -492,7 +492,7 @@ Touchscreen Nextion Binary Sensor, components/binary_sensor/nextion, nextion.jpg Touchscreen, components/touchscreen/index, touch.svg, dark-invert TT21100, components/touchscreen/tt21100, esp32-s3-korvo-2-lcd.png - XPT2046, components/binary_sensor/xpt2046, xpt2046.jpg + GT911, components/touchscreen/gt911, esp32_s3_box_3.png Presence Detection ****************** @@ -679,6 +679,9 @@ 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 + Cover Components ----------------