Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #2361 from esphome/bump-2022.10.0b1 

2022.10.0b1
This commit is contained in:
Jesse Hills 2022-10-13 09:50:26 +13:00 committed by GitHub
parent 22b8120c66 305886fe23
commit 60e2d523b6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 274 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doxygen
View File

@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 2022.9.4
PROJECT_NUMBER = 2022.10.0b1
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a

2
Makefile
View File

@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
ESPHOME_REF = 2022.9.4
ESPHOME_REF = 2022.10.0b1
.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify

1
_redirects
View File

@ -3,3 +3,4 @@
# Moved components
# e.g: /components/sensors/abc.html /components/sensors/xyz.html 301
/components/sensor/sgp40.html /components/sensor/sgp4x.html 301
/components/binary_sensor/xpt2046.html /components/touchscreen/xpt2046.html 301

2
_static/version
View File

@ -1 +1 @@
2022.9.4
2022.10.0b1

107
changelog/2022.10.0.rst Normal file
View File

@ -0,0 +1,107 @@
ESPHome 2022.10.0 - 19th October 2022
=====================================
.. seo::
:description: Changelog for ESPHome 2022.10.0.
:image: /_static/changelog-2022.9.0.png
:author: Jesse Hills
:author_twitter: @jesserockz
This month we have been busy upgrading the Bluetooth Proxy support for Home Assistant,
and this meant there are many PRs awaiting reviews for new components that were unable to be
reviewed and merged in time.
Python Version 3.9
------------------
ESPHome now requires Python 3.9 or newer. This is taken care of if you use the Home Assistant addon
or docker image. If using pip, you will need to upgrade your Python version manually before ESPHome will
upgrade.
BLE Client Sensors
------------------
Due to adding a new RSSI sensor to the ``ble_client`` sensor platform, a new ``type`` configuration variable.
You will get a validation error when you try to install and you have not added a ``type`` to your
existing configurations.
XPT2046 Touchscreen
-------------------
The ``xpt2046`` touchscreen component has been updated to be a platform of ``touchscreen`` instead of a
top level component. This requires a small change to your configuration, see :doc:`/components/touchscreen/xpt2046`
for the new way to configure.
Full list of changes
--------------------
Breaking Changes
^^^^^^^^^^^^^^^^
- Thermostat remove deprecated config :esphomepr:`3643` by :ghuser:`MrMDavidson` (breaking-change)
- Bump python min to 3.9 :esphomepr:`3871` by :ghuser:`jesserockz` (breaking-change)
- Refactor xpt2046 to be a touchscreen platform :esphomepr:`3793` by :ghuser:`nielsnl68` (breaking-change)
- Add ble RSSI sensor for connected devices :esphomepr:`3860` by :ghuser:`RoboMagus` (breaking-change)
All changes
^^^^^^^^^^^
- Update mcp23s17.cpp :esphomepr:`3797` by :ghuser:`pawel3410`
- Allow CORS for web_server :esphomepr:`3819` by :ghuser:`zhzhzhy`
- Dont fail fast on CI for docker :esphomepr:`3832` by :ghuser:`jesserockz`
- Thermostat remove deprecated config :esphomepr:`3643` by :ghuser:`MrMDavidson` (breaking-change)
- Add support for parsing the short local name in the tracker :esphomepr:`3854` by :ghuser:`bdraco`
- Add display GPIO setup instruction for Aliexpress display :esphomepr:`3851` by :ghuser:`kbx81`
- fix dump preset string type :esphomepr:`3863` by :ghuser:`glmnet`
- Bump CI to python 3.9 :esphomepr:`3869` by :ghuser:`jesserockz`
- Add cg.with_local_variable :esphomepr:`3577` by :ghuser:`jpeletier`
- Fix time/automation (cron) wdt crash when time jumps ahead too much :esphomepr:`3844` by :ghuser:`jpeletier`
- Bump pyupgrade from 2.37.3 to 3.0.0 :esphomepr:`3867` by :ghuser:`dependabot[bot]`
- Add min_version to esphome config :esphomepr:`3866` by :ghuser:`jesserockz`
- Bump python min to 3.9 :esphomepr:`3871` by :ghuser:`jesserockz` (breaking-change)
- Bump pylint from 2.15.2 to 2.15.3 :esphomepr:`3870` by :ghuser:`dependabot[bot]`
- Add new sensor device classes :esphomepr:`3895` by :ghuser:`jesserockz`
- Refactor xpt2046 to be a touchscreen platform :esphomepr:`3793` by :ghuser:`nielsnl68` (breaking-change)
- Proxy friendly host url resolution for `use_address` with path. :esphomepr:`3653` by :ghuser:`RoboMagus`
- Update webserver index file :esphomepr:`3896` by :ghuser:`jesserockz`
- Correctly set ble_write UUIDs based on their lengths. :esphomepr:`3885` by :ghuser:`RoboMagus`
- Fix default unit for ble_rssi sensor :esphomepr:`3874` by :ghuser:`RoboMagus`
- Exposing coordinates from touchscreen binary sensor :esphomepr:`3891` by :ghuser:`gpambrozio`
- Fix type annotation on `extract_registry_entry_config` :esphomepr:`3623` by :ghuser:`quentinmit`
- Add ble RSSI sensor for connected devices :esphomepr:`3860` by :ghuser:`RoboMagus` (breaking-change)
- Fix pulse_meter filter logic :esphomepr:`3321` by :ghuser:`cstaahl`
- Add support for ZHLT01 heatpump IR protocol :esphomepr:`3655` by :ghuser:`cfeenstra1024`
- Send GATT error events to HA :esphomepr:`3884` by :ghuser:`jesserockz`
- Do not require CS pin for ST7789V :esphomepr:`3888` by :ghuser:`definitio`
Past Changelogs
---------------
- :doc:`2022.9.0`
- :doc:`2022.8.0`
- :doc:`2022.6.0`
- :doc:`2022.5.0`
- :doc:`2022.4.0`
- :doc:`2022.3.0`
- :doc:`2022.2.0`
- :doc:`2022.1.0`
- :doc:`2021.12.0`
- :doc:`2021.11.0`
- :doc:`2021.10.0`
- :doc:`2021.9.0`
- :doc:`2021.8.0`
- :doc:`v1.20.0`
- :doc:`v1.19.0`
- :doc:`v1.18.0`
- :doc:`v1.17.0`
- :doc:`v1.16.0`
- :doc:`v1.15.0`
- :doc:`v1.14.0`
- :doc:`v1.13.0`
- :doc:`v1.12.0`
- :doc:`v1.11.0`
- :doc:`v1.10.0`
- :doc:`v1.9.0`
- :doc:`v1.8.0`
- :doc:`v1.7.0`

2
changelog/index.rst
View File

@ -2,7 +2,7 @@ Changelog
=========
.. redirect::
:url: /changelog/2022.9.0.html
:url: /changelog/2022.10.0.html
.. toctree::
:glob:

4
components/climate/climate_ir.rst
View File

@ -102,7 +102,7 @@ This platform utilises the library's generic one-size-fits-all API, which might
Additional configuration must be specified for this platform:
- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyac``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba``
- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyac``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba``, ``zhlt01``
- **horizontal_default** (**Required**, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Options are: ``left``, ``mleft``, ``middle``, ``mright``, ``right``, ``auto``
- **vertical_default** (**Required**, string): What to default to when the AC unit's vertical direction is *not* set to swing. Options are: ``down``, ``mdown``, ``middle``, ``mup``, ``up``, ``auto``
- **max_temperature** (**Required**, float): The maximum temperature that the AC unit supports being set to.
@ -120,6 +120,8 @@ Additional configuration must be specified for this platform:
internal temperature sensor; a value of 2 minutes seems to work well. See :doc:`/components/sensor/index`
for more information.
- The ``zhlt01`` protocol supports multiple AC brands: Eurom, Chigo, Tristar, Tecnomaster, Elgin, Geant, Tekno, Topair, Proma, Sumikura, JBS, Turbo Air, Nakatomy, Celestial Air, Ager, Blueway, Airlux, etc.
.. _ir-receiver_id:
Using a Receiver

116
components/climate/thermostat.rst
View File

@ -52,8 +52,6 @@ modes that Home Assistant offers.
- platform: thermostat
name: "Thermostat Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
default_target_temperature_high: 22 °C
min_cooling_off_time: 300s
min_cooling_run_time: 300s
min_heating_off_time: 300s
@ -66,6 +64,11 @@ modes that Home Assistant offers.
idle_action:
- switch.turn_off: air_cond
- switch.turn_off: heater
default_preset: Home
preset:
- name: Home
default_target_temperature_low: 20 °C
default_target_temperature_high: 22 °C
.. code-block:: yaml
@ -74,7 +77,6 @@ modes that Home Assistant offers.
- platform: thermostat
name: "Thermostat Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
min_heating_off_time: 300s
min_heating_run_time: 300s
min_idle_time: 30s
@ -82,6 +84,11 @@ modes that Home Assistant offers.
- switch.turn_on: heater
idle_action:
- switch.turn_off: heater
default_preset: Home
preset:
- name: Home
default_target_temperature_low: 20 °C
.. code-block:: yaml
@ -90,7 +97,6 @@ modes that Home Assistant offers.
- platform: thermostat
name: "Thermostat Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_high: 22 °C
min_cooling_off_time: 300s
min_cooling_run_time: 300s
min_idle_time: 30s
@ -98,6 +104,11 @@ modes that Home Assistant offers.
- switch.turn_on: air_cond
idle_action:
- switch.turn_off: air_cond
default_preset: Home
preset:
- name: Home
default_target_temperature_high: 22 °C
Controller Behavior and Hysteresis
@ -163,7 +174,7 @@ Default Target Temperatures and Mode
These configuration items determine default values the thermostat controller should use when it starts.
- **default_mode** (*Optional*, *Deprecated*, climate mode): The default climate mode the controller should
- **default_mode** (*Optional*, *Deprecated*, climate mode): The default climate mode the controller should
use if it is unable to restore it from memory. One of:
- ``off`` (default)
@ -173,7 +184,7 @@ These configuration items determine default values the thermostat controller sho
- ``dry``
- ``fan_only``
- ``auto``
This value is used the first time your device starts after ESPHome is initially installed onto it. Add
this option into your configuration if you want your thermostat component to start in a climate mode other
than ``off``. If this option is not configured, you'll need to manually change the climate mode later via
@ -190,9 +201,9 @@ device's configuration.
.. note::
**default_mode**, **default_target_temperature_low**, and **default_target_temperature_high** are
**default_mode**, **default_target_temperature_low**, and **default_target_temperature_high** are
being removed in a future release. In the future you will need to migrate your configuration to using
a :ref:`preset <thermostat-preset>` which will allow for more flexibility and customisation
a :ref:`preset <thermostat-preset>` which will allow for more flexibility and customisation
Note that ``min_temperature`` and ``max_temperature`` from the base climate component are used to define
the range of allowed temperature values in the thermostat component. See :doc:`/components/climate/index`.
@ -315,22 +326,6 @@ Set Point Options/Behavior
- **supplemental_heating_delta** (*Required with* ``supplemental_heating_action``, float): When the temperature
difference between the lower set point and the current temperature exceeds this value,
``supplemental_heating_action`` will be called immediately.
- **away_config** (*Optional*, *Deprecated*): Additionally specify target temperature range settings for away mode.
Away mode can be used to have a second set of target temperatures (for example, while the user is
away or sleeping/at night).
- **default_target_temperature_low** (*Optional*, float): The default low target temperature for the control
algorithm when Away mode is selected. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (*Optional*, float): The default high target temperature for the control
algorithm when Away mode is selected. This can be dynamically set in the frontend later.
**If configured, at least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
**must be specified in the away mode configuration.**
.. note::
**away_config** is deprecated and will be removed in a future release. You should migrate your configuration
to using a :ref:`preset <thermostat-preset>` which allows for more flexibility and customisation
.. _thermostat-preset:
@ -343,19 +338,19 @@ experience and automation.
- **preset**: (*Optional*, list)
- **name** (*Required*, string): Name of the preset. If this is one of the *standard* presets (``eco``, ``away``,
- **name** (*Required*, string): Name of the preset. If this is one of the *standard* presets (``eco``, ``away``,
``boost``, ``comfort``, ``home``, ``sleep``, or ``activity``) it is considered a *standard* preset. Any other
string will make the preset a *custom* preset. *Standard* and *custom* presets are functionally equivalent,
the only difference is that when switching the mode via :ref:`climate.control Action <climate-control_action>`
you will need to use the `preset` or `custom_preset` property as appropriate. The Home Assistant
you will need to use the `preset` or `custom_preset` property as appropriate. The Home Assistant
`climate.set_preset_mode` service treats them identically
- **default_target_temperature_low** (*Optional*, float): The default low target temperature when switching to
- **default_target_temperature_low** (*Optional*, float): The default low target temperature when switching to
this preset
- **default_target_temperature_high** (*Optional*, float): The default high target temperature when switching
to this preset.
- **mode** (*Optional*, climate mode): The mode the thermostat should switch to when this preset is activated.
If not specified, the thermostat's mode will remain unchanged when the preset is activated. One of:
- ``heat_cool``
- ``cool``
- ``heat``
@ -378,7 +373,7 @@ experience and automation.
- **swing_mode** (*Optional*, climate swing mode): The fan swing mode the thermostat should switch to when this
preset is activated. If not specified, the thermostat's fan swing mode will remain unchanged when the preset
is activated. One of:
- ``off``
- ``both``
- ``horizontal``
@ -422,6 +417,67 @@ experience and automation.
preset_change:
- logger.log: Preset has been changed!
Default Preset
**************
These configuration items determine default values the thermostat controller should use when it starts.
- **default_preset** (*Optional*, string): The name of the preset to use by default. Must match a preset
as per :ref:`preset <thermostat-preset>`.
- **on_boot_restore_from**: (*Optional*, on_boot_restore_from): Controls what the thermostat will do when
it first boots. One of:
- ``memory`` (default): The thermostat will restore any settings from last time it was running.
- ``default_preset``: The thermostat will always switch to the preset specified by **default_preset**
.. note::
You can specify a ``default_preset`` and set ``on_boot_restore_from`` to ``memory``. In this mode when
the settings from last boot cannot be retrieved, for any reason, then the specified ``default_preset``
will be applied.
.. code-block:: yaml
# This climate controller, on first boot, will switch to "My Startup Preset". Subsequent boots would
# restore to whatever mode it was in prior to the reboot
climate:
- platform: thermostat
name: "From Memory Thermostat"
default_preset: My Startup Preset
on_boot_restore_from: memory
preset:
- name: My Startup Preset
default_target_temperature_low: 17
default_target_temperature_high: 26
fan_mode: OFF
swing_mode: OFF
mode: OFF
# Custom preset
- name: A custom preset
default_target_temperature_low: 21
default_target_temperature_high: 23
fan_mode: HIGH
mode: HEAT_COOL
# This climate controller will always switch to "Every Start Preset"
climate:
- platform: thermostat
name: "Default Preset Thermostat"
default_preset: Every Start Preset
on_boot_restore_from: default_preset
preset:
- name: Every Start Preset
default_target_temperature_low: 17
default_target_temperature_high: 26
fan_mode: OFF
swing_mode: OFF
mode: OFF
# Custom preset
- name: A custom preset
default_target_temperature_low: 21
default_target_temperature_high: 23
fan_mode: HIGH
mode: HEAT_COOL
Additional Actions/Behavior
***************************
@ -487,7 +543,7 @@ Hysteresis Values
- While this platform uses the term temperature everywhere, it can also be used to regulate other values.
For example, controlling humidity is also possible with this platform.
- ``min_temperature`` and ``max_temperature`` from the base climate component are used the define the range of
- ``min_temperature`` and ``max_temperature`` from the base climate component are used the define the range of
adjustability and the defaults will probably not make sense for control of things like humidity. See
:doc:`/components/climate/index`.

2
components/display/st7789v.rst
View File

@ -63,7 +63,7 @@ Configuration variables:
- ``Adafruit RR 280x240`` (round-rectangular display -- some pixels are "deleted" from corners to form rounded shape)
- ``Custom`` (see details below)
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **reset_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **height** (*Optional*, int): When ``model`` is set to "Custom", use this to specify the ``height`` of the display

16
components/esphome.rst
View File

@ -50,6 +50,8 @@ Advanced options:
- **name** (**Required**, string): Name of the project
- **version** (**Required**, string): Version of the project
- **min_version** (*Optional*, string): The minimum ESPHome version required to compile this configuration.
See :ref:`esphome-min_version`.
Old-style platform options, which have been moved to the platform-specific :doc:`esp32 </components/esp32>` and
:doc:`esp8266 </components/esp8266>` sections but are still accepted here for compatibility reasons (usage not
@ -129,11 +131,11 @@ too many WiFi/MQTT connection attempts, Over-The-Air updates being applied or th
Configuration variables:
- **priority** (*Optional*, float): The priority to execute your custom shutdown code. A higher value
means a high priority and in case of shutdown triggers that the code is executed **later**.
means a high priority and in case of shutdown triggers that the code is executed **later**.
Priority is used primarily for the initialization order of components. Shutdowns for these components are handled in *reverse* order, such that e.g. sensors (600) are shutdown before the hardware components (800) they depend on.
Please note this is an ESPHome-internal value and any change will not be marked as a breaking change.
Please note this is an ESPHome-internal value and any change will not be marked as a breaking change.
Defaults to ``600``. For priority values refer to the list in the :ref:`esphome-on_boot` section.
- See :ref:`Automation <automation>`.
.. _esphome-on_loop:
@ -337,6 +339,14 @@ should be ``author_name.project_name``.
name: "jesse.leds_party"
version: "1.0.0"
.. _esphome-min_version:
Minimum ESPHome version
-----------------------
This allows YAML files to specify the minimum version of ESPHome required to compile.
This is useful in the case of packages where a published package might use features only
available in a newer version of ESPHome. This allows for a more friendly error message.
See Also
--------

40
components/sensor/ble_client.rst
View File

@ -6,7 +6,7 @@ BLE Client Sensor
:image: bluetooth.svg
The ``ble_client`` component is a sensor platform that can
query BLE devices for specific values of service characteristics.
query BLE devices for RSSI or specific values of service characteristics.
For more information on BLE services and characteristics, see
:doc:`/components/ble_client`.
@ -21,6 +21,7 @@ For more information on BLE services and characteristics, see
sensor:
- platform: ble_client
type: characteristic
ble_client_id: itag_black
name: "iTag battery level"
service_uuid: '180f'
@ -28,20 +29,34 @@ For more information on BLE services and characteristics, see
icon: 'mdi:battery'
unit_of_measurement: '%'
- platform: ble_client
type: rssi
ble_client_id: itag_black
name: "iTag RSSI"
Configuration variables:
------------------------
- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
- **service_uuid** (**Required**, UUID): UUID of the service on the device.
- **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to query.
- **descriptor_uuid** (*Optional*, UUID): UUID of the characteristic's descriptor to query.
- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for converting a raw data
reading to a sensor value. See :ref:`ble-sensor-lambda` for more information.
- **notify** (*Optional*, boolean): Instruct the server to send notifications for this
characteristic.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
- All other options from :ref:`Sensor <config-sensor>`.
- **type** (**Required**): One of ``rssi``, ``characteristic``.
rssi options:
- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
- All other options from :ref:`Sensor <config-sensor>`.
characteristic options:
- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
- **service_uuid** (**Required**, UUID): UUID of the service on the device.
- **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to query.
- **descriptor_uuid** (*Optional*, UUID): UUID of the characteristic's descriptor to query.
- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for converting a raw data
reading to a sensor value. See :ref:`ble-sensor-lambda` for more information.
- **notify** (*Optional*, boolean): Instruct the server to send notifications for this
characteristic.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
- All other options from :ref:`Sensor <config-sensor>`.
Automations:
@ -64,6 +79,7 @@ variable ``x`` of type ``std::vector<uint8_t>``. The function must return a sing
sensor:
- platform: ble_client
type: characteristic
ble_client_id: t_sensor
name: "Temperature Sensor 32bit float"
...

0
components/binary_sensor/images/xpt2046-full.jpg → components/touchscreen/images/xpt2046-full.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

2
components/touchscreen/index.rst
View File

@ -80,7 +80,7 @@ See Also
- :ref:`Binary Sensor Filters <binary_sensor-filters>`
- :doc:`Inkplate 6 Plus </components/display/inkplate6>`
- :doc:`EKTF2232 </components/touchscreen/ektf2232>`
- :doc:`XPT2046 </components/binary_sensor/xpt2046>`
- :doc:`XPT2046 </components/touchscreen/xpt2046>`
- :apiref:`touchscreen/touchscreen.h`
- :apiref:`touchscreen/binary_sensor/touchscreen_binary_sensor.h`
- :ghedit:`Edit`

116
components/binary_sensor/xpt2046.rst → components/touchscreen/xpt2046.rst
View File

@ -1,5 +1,5 @@
XPT2046 Touch Screen Controller
==================================
XPT2046 Touch Screen Controller (Updated version)
==================================================
.. seo::
:description: Instructions for setting up XPT2046 touch screen controller with ESPHome
@ -8,10 +8,7 @@ XPT2046 Touch Screen Controller
.. _xpt2046-component:
Component/Hub
-------------
The ``xpt2046`` component allows using the touch screen controllers
The ``xpt2046`` touchscreen platform allows using the touch screen controllers
based on the XPT2046 chip
(`datasheet <https://datasheetspdf.com/pdf-file/746665/XPTEK/XPT2046/1>`__,
`AZ-Delivery`_) with ESPHome. Many cheap LCD displays contain this controller.
@ -28,32 +25,20 @@ The :ref:`SPI <spi>` is required to be set up in your configuration for this sen
.. code-block:: yaml
# Example configuration entry
xpt2046:
touchscreen:
platform: xpt2046
id: touchscreen
cs_pin: 17
irq_pin: 16
interupt_pin: 16
update_interval: 50ms
report_interval: 1s
threshold: 400
dimension_x: 240
dimension_y: 320
calibration_x_min: 3860
calibration_x_max: 280
calibration_y_min: 340
calibration_y_max: 3860
swap_x_y: false
binary_sensor:
- platform: xpt2046
xpt2046_id: touchscreen
id: touch_key0
x_min: 80
x_max: 160
y_min: 106
y_max: 212
on_state:
- lambda: 'ESP_LOGI("main", "key0: %s", (x ? "touch" : "release"));'
Configuration variables:
------------------------
@ -66,12 +51,12 @@ Base Configuration:
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The chip select pin.
Often marked ``T_CS`` on the board.
- **irq_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
- **interupt_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
Often marked ``T_IRQ`` on the board. If not specified the component will use polling
via SPI.
via SPI. This key is renamed from **irq_pin**
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. If ``irq_pin`` is specified the touch will be detected nearly instantaneously and this setting
sensor. If ``interupt_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
@ -79,12 +64,6 @@ Base Configuration:
- **threshold** (*Optional*, int): The value to detect the touch or release. Defaults to ``400``.
- **dimension_x** (*Optional*, int): The dimension of the display in the horizontal
direction. Usually in pixels but a percentage can be useful as well. Defaults to ``100``.
- **dimension_y** (*Optional*, int): The dimension of the display in the vertical
direction. Usually in pixels but a percentage can be useful as well. Defaults to ``100``.
- **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``.
@ -100,65 +79,8 @@ Base Configuration:
- **swap_x_y** (*Optional*, boolean): If true the x and y axes are swapped. Defaults to ``false``.
- **on_state** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the touch screen is pressed or released. See :ref:`xpt2046-on_state`.
- All other options from :ref:`config-touchscreen`.
.. _xpt2046-on_state:
``on_state`` Action
-------------------
This automation will be triggered when the XPT2046 touch screen detects a touch, a release
or periodically each ``report_interval`` while touched.
This trigger provides three arguments: ``x`` and ``y`` are of the type int and specify the
coordinates of the touch and a bool ``touched`` specifying whether a touch or release was
detected.
Additionally to the coordinates, the touch status and the raw values needed for the calibration
can be accessed as member variables.
The following code
.. code-block:: yaml
xpt2046:
on_state:
- lambda: |-
ESP_LOGI("main", "args x=%d, y=%d, touched=%s", x, y, (touched ? "touch" : "release"));
ESP_LOGI("main", "member x=%d, y=%d, touched=%d, x_raw=%d, y_raw=%d, z_raw=%d",
id(touchscreen).x,
id(touchscreen).y,
(int) id(touchscreen).touched,
id(touchscreen).x_raw,
id(touchscreen).y_raw,
id(touchscreen).z_raw
);
produces
.. code-block:: none
[20:17:37][I][main:065]: args x=145, y=261, touched=touch
[20:17:37][I][main:073]: member x=145, y=261, touched=1, x_raw=1686, y_raw=3218, z_raw=424
[20:17:37][I][main:065]: args x=145, y=261, touched=release
[20:17:37][I][main:073]: member x=145, y=261, touched=0, x_raw=0, y_raw=0, z_raw=0
Binary Sensor
-------------
The ``xpt2046`` binary sensor allows you to setup areas on the touch screen as virtual
buttons. First, setup a :ref:`xpt2046-component` and then use this binary sensor platform
to create individual binary sensors for each virtual button.
- **name** (*Optional*, string): The name for the binary sensor.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **xpt2046_id** (*Optional*, :ref:`config-id`): Specify the ID of the component the sensor is part of. Useful when you have more than one touch screen.
- **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 <config-binary_sensor>`.
.. _xpt2046-calibration:
@ -168,7 +90,7 @@ 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:`xpt2046-on_state`. The goal of the calibration is to identify the raw values corresponding
: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
@ -179,16 +101,13 @@ values nor ``swap_x_y``.
.. code-block:: yaml
# Touchscreen
xpt2046:
touchscreen:
platform: xpt2046
id: touchscreen
cs_pin: 17
irq_pin: 16
dimension_x: 240
dimension_y: 320
on_state:
on_touch:
- lambda: |-
if (touched)
ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%d",
ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%0d",
id(touchscreen).x,
id(touchscreen).y,
id(touchscreen).x_raw,
@ -230,7 +149,8 @@ The vertical direction is fine. The configuration would thus be
.. code-block:: yaml
xpt2046:
touchscreen:
platform: xpt2046
calibration_x_min: 3848
calibration_x_max: 281
calibration_y_min: 347
@ -250,7 +170,7 @@ Note that the touch screen is not extremely precise and there might be nonlinear
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:: none
.. code-block:: yaml
display:
- platform: ili9341

4
conf.py
View File

@ -66,9 +66,9 @@ author = "ESPHome"
# built documents.
#
# The short X.Y version.
version = "2022.9"
version = "2022.10"
# The full version, including alpha/beta/rc tags.
release = "2022.9.4"
release = "2022.10.0b1"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

7
cookbook/ble_itag.rst
View File

@ -55,6 +55,7 @@ Configuration example:
# a notification is received, the corresponding binary_sensor
# is briefly toggled.
- platform: ble_client
type: characteristic
ble_client_id: itag_black
name: "Black iTag btn"
service_uuid: 'ffe0'
@ -73,12 +74,18 @@ Configuration example:
# support this characteristic, you will see 'Unknown' in the
# HA frontend.
- platform: ble_client
type: characteristic
ble_client_id: itag_black
name: "Black iTag Battery"
service_uuid: '180f'
characteristic_uuid: '2a19'
icon: 'mdi:battery'
unit_of_measurement: '%'
# This entry queries polls the RSSI when the tag is connected.
- platform: ble_client
type: rssi
ble_client_id: itag_black
name: "Black iTag RSSI"
Explanation
-----------

6
guides/supporters.rst
View File

@ -152,6 +152,7 @@ Contributors
- `Ciprian Constantinescu (@cciprian5) <https://github.com/cciprian5>`__
- `Marco (@cdrfun) <https://github.com/cdrfun>`__
- `Cellie (@CelliesProjects) <https://github.com/CelliesProjects>`__
- `Chris Feenstra (@cfeenstra1024) <https://github.com/cfeenstra1024>`__
- `Kostas Chatzikokolakis (@chatziko) <https://github.com/chatziko>`__
- `chris-jennings (@chris-jennings) <https://github.com/chris-jennings>`__
- `Chris (@chrismaki) <https://github.com/chrismaki>`__
@ -483,10 +484,8 @@ Contributors
- `Kevin Lewis (@kll) <https://github.com/kll>`__
- `Koen Vervloesem (@koenvervloesem) <https://github.com/koenvervloesem>`__
- `Petr Vraník (@konikvranik) <https://github.com/konikvranik>`__
- `korellas (@korellas) <https://github.com/korellas>`__
- `Kevin Pelzel (@kpelzel) <https://github.com/kpelzel>`__
- `Karl Q. (@kquinsland) <https://github.com/kquinsland>`__
- `krahabb (@krahabb) <https://github.com/krahabb>`__
- `Kodey Converse (@krconv) <https://github.com/krconv>`__
- `KristopherMackowiak (@KristopherMackowiak) <https://github.com/KristopherMackowiak>`__
- `kroimon (@kroimon) <https://github.com/kroimon>`__
@ -699,6 +698,7 @@ Contributors
- `Qc (@qc24) <https://github.com/qc24>`__
- `Karol Zlot (@qqgg231) <https://github.com/qqgg231>`__
- `Tommy Jonsson (@quazzie) <https://github.com/quazzie>`__
- `Quentin Smith (@quentinmit) <https://github.com/quentinmit>`__
- `Quinn Hosler (@quinnhosler) <https://github.com/quinnhosler>`__
- `Johannes Rebling (@r0oland) <https://github.com/r0oland>`__
- `Richard Kuhnt (@r15ch13) <https://github.com/r15ch13>`__
@ -898,4 +898,4 @@ Contributors
- `Zack Barett (@zsarnett) <https://github.com/zsarnett>`__
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
*This page was last updated October 7, 2022.*
*This page was last updated October 13, 2022.*