From 596c3e2035658144ad0adb86b2063b0adcdfa25b Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Wed, 26 Jan 2022 16:26:48 +1300 Subject: [PATCH] Reorganize for base touchscreen docs (#1834) --- components/binary_sensor/ektf2232.rst | 96 --------------------------- components/index.rst | 1 + components/touchscreen/ektf2232.rst | 37 +++++++++++ components/touchscreen/index.rst | 90 +++++++++++++++++++++++++ index.rst | 8 +++ 5 files changed, 136 insertions(+), 96 deletions(-) delete mode 100644 components/binary_sensor/ektf2232.rst create mode 100644 components/touchscreen/ektf2232.rst create mode 100644 components/touchscreen/index.rst diff --git a/components/binary_sensor/ektf2232.rst b/components/binary_sensor/ektf2232.rst deleted file mode 100644 index c0a99877a..000000000 --- a/components/binary_sensor/ektf2232.rst +++ /dev/null @@ -1,96 +0,0 @@ -EKTF2232 Touch Screen Controller -================================ - -.. seo:: - :description: Instructions for setting up EKTF2232 touch screen controller with ESPHome - :image: ektf2232.svg - :keywords: EKTF2232 - -.. _ektf2232-component: - -Component/Hub -------------- - -The ``ektf2232`` component allows using the touch screen controller -found in the :doc:`Inkplate 6 Plus ` 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 - ektf2232: - interrupt_pin: GPIO36 - rts_pin: GPIO16 - - binary_sensor: - - platform: ektf2232 - id: touch_key0 - x_min: 80 - x_max: 160 - y_min: 106 - y_max: 212 - - -Configuration variables: ------------------------- - -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor. - -- **rts_pin** (*Optional*, :ref:`Pin Schema `): The reset pin of the controller. - -- **interupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. - -- **display_width** (*Optional*, int): The dimension of the display in the horizontal - direction. Defaults to ``1024`` to match the Inkplate 6 Plus. - -- **display_height** (*Optional*, int): The dimension of the display in the vertical - direction. Defaults to ``758`` to match the Inkplate 6 Plus. - -- **on_touch** (*Optional*, :ref:`Automation `): An automation to perform - when the touch screen is pressed. See :ref:`ektf2232-on_touch`. - -.. _ektf2232-on_touch: - -``on_touch`` Trigger --------------------- - -This automation will be triggered when the EKTF2232 touch screen detects a touch. - -This trigger provides one arguments of type :apistruct:`ektf2232::TouchPoint` which has two integer members: ``x`` and ``y`` which -represent the position of the touch calibrated to the display width and heigh config options given. - -Binary Sensor -------------- - -The ``ektf2232`` binary sensor allows you to setup areas on the touch screen as virtual -buttons. First, setup a :ref:`ektf2232-component` and then use this binary sensor platform -to create individual binary sensors for each virtual button. - -Configuration variables: ------------------------- - -- **name** (*Optional*, string): The name for the binary sensor. - -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - -- **ektf2232_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the component the sensor is part of. - -- **x_min** (**Required**, int): Left coordinate of the screen area to be detected as the virtual button. - -- **x_max** (**Required**, int): Right coordinate of the screen area to be detected as the virtual button. - -- **y_min** (**Required**, int): Top coordinate of the screen area to be detected as the virtual button. - -- **y_max** (**Required**, int): Bottom coordinate of the screen area to be detected as the virtual button. - -- All other options from :ref:`Binary Sensor `. - - -See Also --------- - -- :ref:`Binary Sensor Filters ` -- :doc:`Inkplate 6 Plus ` -- :apiref:`ektf2232/ektf2232.h` -- :apiref:`ektf2232/binary_sensor/ektf2232_binary_sensor.h` -- :ghedit:`Edit` diff --git a/components/index.rst b/components/index.rst index 3bc1dc371..5a17978d4 100644 --- a/components/index.rst +++ b/components/index.rst @@ -18,4 +18,5 @@ Components display/index text_sensor/index stepper/index + touchscreen/index * diff --git a/components/touchscreen/ektf2232.rst b/components/touchscreen/ektf2232.rst new file mode 100644 index 000000000..29aa7237b --- /dev/null +++ b/components/touchscreen/ektf2232.rst @@ -0,0 +1,37 @@ +EKTF2232 Touchscreen Controller +================================ + +.. seo:: + :description: Instructions for setting up EKTF2232 touchscreen controller with ESPHome + :image: ektf2232.svg + :keywords: EKTF2232 + +The ``ektf2232`` component allows using the touchscreen controller +found in the :doc:`Inkplate 6 Plus ` 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 + touchscreen: + - platform: ektf2232 + interrupt_pin: GPIO36 + rts_pin: GPIO16 + + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **rts_pin** (*Optional*, :ref:`Pin Schema `): The reset pin of the controller. +- **interupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. + +- All other options from :ref:`config-touchscreen`. + +See Also +-------- + +- :doc:`Touchscreen ` +- :doc:`Inkplate 6 Plus ` +- :apiref:`ektf2232/ektf2232.h` +- :ghedit:`Edit` diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst new file mode 100644 index 000000000..4f9781c05 --- /dev/null +++ b/components/touchscreen/index.rst @@ -0,0 +1,90 @@ +Touchscreen Components +====================== + +.. seo:: + :description: Instruction for using touchscreen components. + :image: folder-open.svg + +The ``touchscreen`` component holds the base code for most touchscreen components +available in ESPHome and is responsible for passing the touch events to +``binary_sensors`` with the ``touchscreen`` platform. + +.. _config-touchscreen: + +Base Touchscreen Configuration +------------------------------ + +.. code-block:: yaml + + # Example touchscreen + touchscreen: + - platform: ... + on_touch: + then: + ... + +Configuration variables: +************************ + +- **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. + +.. _touchscreen-on_touch: + +``on_touch`` Trigger +-------------------- + +This automation will be triggered when the touchscreen detects a touch. + +This trigger provides one arguments 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 +------------- + +The ``touchscreen`` binary sensor allows you to setup areas on the touch screen as virtual +buttons. + +.. code-block:: yaml + + binary_sensor: + - platform: touchscreen + name: Top Left Touch Button + x_min: 0 + x_max: 100 + y_min: 0 + y_max: 100 + +Configuration Variables: +************************ + +- **name** (*Optional*, string): The name for the binary sensor. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **touchscreen_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the touchscreen. +- **x_min** (**Required**, int): Left coordinate of the screen area to be detected as the virtual button. +- **x_max** (**Required**, int): Right coordinate of the screen area to be detected as the virtual button. +- **y_min** (**Required**, int): Top coordinate of the screen area to be detected as the virtual button. +- **y_max** (**Required**, int): Bottom coordinate of the screen area to be detected as the virtual button. + +- All other options from :ref:`Binary Sensor `. + + +See Also +-------- + +- :ref:`Binary Sensor Filters ` +- :doc:`Inkplate 6 Plus ` +- :doc:`EKTF2232 ` +- :doc:`XPT2046 ` +- :apiref:`touchscreen/touchscreen.h` +- :apiref:`touchscreen/binary_sensor/touchscreen_binary_sensor.h` +- :ghedit:`Edit` + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/index.rst b/index.rst index 58ca15a7b..d8426858c 100644 --- a/index.rst +++ b/index.rst @@ -526,6 +526,14 @@ Display Components Inkplate, components/display/inkplate6, inkplate6.jpg PCD8544 (Nokia 5110/ 3310), components/display/pcd8544, pcd8544.jpg +Touchscreen Components +---------------------- + +.. imgtable:: + + Touchscreen Core, components/touchscreen/index, folder-open.svg + EKTF2232, components/touchscreen/ektf2232, ektf2232.svg, Inkplate 6 Plus + Cover Components ----------------