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

Merge branch 'current' into next

Browse Source
This commit is contained in:
Jesse Hills 2022-11-23 13:00:59 +13:00
commit 37b668e9c1
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
9 changed files with 10778 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
changelog/2022.11.0.rst
View File

@ -93,6 +93,10 @@ By default ESPHome tries to compile using all of the processor cores, and this a
...
compile_process_limit: 1
Release 2022.11.1 - November 17
-------------------------------
- Support ADC on RP2040 :esphomepr:`4040` by :ghuser:`jesserockz`
Full list of changes
--------------------

51
components/bluetooth_proxy.rst
View File

@ -5,27 +5,25 @@ Bluetooth Proxy
:description: Instructions for setting up the Bluetooth Proxy in ESPHome.
:image: bluetooth.svg
Home Assistant can expand its Bluetooth reach by communicating through
the Bluetooth proxy component in ESPHome. Place your ESPHome devices close to the
Bluetooth devices that you want to interact with for the best
experience.
Home Assistant can expand its Bluetooth reach by communicating through the Bluetooth proxy component in ESPHome.
The Individual device integrations in Home Assistant (such as BTHome) will receive the data from the Bluetooth
Integration in Home Assistant which automatically aggregates all ESPHome bluetooth proxies with any USB Bluetooth
Adapters you might have. This exceptional feature offers fault tolerant connection between the Bluetooth devices
and Home Assistant.
If you're looking to create a device that is just a Bluetooth Proxy, see our `Bluetooth Proxy installer <https://esphome.github.io/bluetooth-proxies/>`__ website.
The Bluetooth proxy depends on :doc:`esp32_ble_tracker` so make sure to add that to your configuration.
If you're looking to create an ESPHome node that is just a Bluetooth Proxy, see
our `Bluetooth Proxy installer <https://esphome.github.io/bluetooth-proxies/>`__ website.
.. note::
Bluetooth proxy requires Home Assistant 2022.9 or later.
The Bluetooth proxy of ESPHome provides Home Assistant with a maximum number of 3 simultaneous active connections.
Devices which maintain a *continuous active* connection will consume one of these constantly, whilst devices which
do *periodic disconnections and reconnections* will permit using more than 3 of them (on a statistical basis).
Passively broadcasted sensor data (that is advertised by certain devices without active connections) is received
separately from these, and is not limited to a specific number.
.. note::
The Bluetooth proxy of ESPHome currently only provides Home Assistant with passive sensor
data that is advertised by certain devices. Not all devices are supported and ESPHome does not decode or keep a list.
To find out if your device is supported, please search for it in the `Home Assistant Integrations <https://www.home-assistant.io/integrations/>`__ list.
The Individual device integrations in Home Assistant (such as BTHome) will receive the data from the Bluetooth Integration in Home Assistant
which automatically aggregates all ESPHome bluetooth proxies with any USB Bluetooth Adapters you might have.
Not all devices are supported and ESPHome does not decode or keep a list. To find out if your device is supported,
please search for it in the `Home Assistant Integrations <https://www.home-assistant.io/integrations/>`__ list.
Configuration:
--------------
@ -36,6 +34,27 @@ Configuration:
- **active** (*Optional*, boolean): Enables proxying active connections. Defaults to ``false``. Requires Home Assistant 2022.10 or later.
The Bluetooth proxy depends on :doc:`esp32_ble_tracker` so make sure to add that to your configuration.
.. note::
Bluetooth proxy requires Home Assistant 2022.9 or later.
Improving reception performance
-------------------------------
Use a board with an Ethernet connection to the network, to offload ESP32's radio module from WiFi traffic, this gains performance on Bluetooth side.
To maximize the chances of catching advertisements of the sensors, you can set ``interval`` equal to ``window`` in :doc:`/components/esp32_ble_tracker` scan parameter settings:
.. code-block:: yaml
esp32_ble_tracker:
scan_parameters:
interval: 1100ms
window: 1100ms
Avoid placing the ESP node in racks, close to routers/switches or other network equipment as EMI interference will degrade Bluetooth signal reception. For best results put as far away as possible, at least 3 meters distance from any other such equipment. Place your ESPHome devices close to the Bluetooth devices that you want to interact with for the best experience.
See Also
--------

10604
components/display/images/lcd_gpio.svg Normal file
View File

File diff suppressed because it is too large Load Diff
Side by Side

After

Width:  |  Height:  |  Size: 334 KiB

193
components/display/lcd_display.rst
View File

@ -2,32 +2,41 @@ Character-Based LCD Display
===========================
.. seo::
:description: Instructions for setting up character-based LCD displays.
:description: Instructions for setting up character-based HD44780 LCD displays.
:image: lcd.jpg
The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCD displays
with ESPHome. This integration is only for LCD displays that display individual characters on a screen
(usually 8-40 columns and 2-4 rows), and not for LCD displays that can control each pixel individually.
.. figure:: images/lcd-hello_world.jpg
:align: center
:width: 60.0%
.. note::
Multiple versions of the display exist, supporting different character sets:
- HD44780UA00 English-Japanese which includes katakana characters, some Greek letters and mathematical symbols
- HD44780UA02 English-European which includes Greek, Cyrillic and Western European characters (with some diacritics)
- HD44780UBxx custom, manufacturer-specific character sets
It is also possible to add eight user-defined characters.
.. _lcd-pcf8574:
lcd_pcf8574 Component
---------------------
The ``lcd_pcf8574`` display platform allows you to use standard character-based LCD displays like
`this one <https://docs.labs.mediatek.com/resource/linkit7697-arduino/en/tutorial/driving-1602-lcd-with-pcf8574-pcf8574a>`__
with ESPHome. This integration is only for LCD displays that display individual characters on a screen (usually 16-20 columns
and 2-4 rows), and not for LCD displays that can control each pixel individually.
This version of the LCD integration is for LCD displays with a PCF8574 connected to all the data pins. This has
the benefit that you only need to connect two data wires to the ESP instead of the 6 or 10 with the :ref:`lcd-gpio`.
As the communication with the :ref:`I²C Bus <i2c>`, you need to have an ``i2c:`` section in your configuration.
``lcd_pcf8574`` is for LCD displays with a PCF8574 GPIO expander module connected to all the data pins. This has the
benefit that you only need to connect two data wires to the ESP instead of the six or ten as with the :ref:`lcd-gpio`.
The communication happens via :ref:`I²C Bus <i2c>`, you need to have an ``i2c:`` section in your configuration.
.. figure:: images/lcd-pcf8574.jpg
:align: center
:width: 75.0%
The PCF8574 chip attached to the LCD Display.
.. figure:: images/lcd-hello_world.jpg
:align: center
:width: 60.0%
LCD Display with a PCF8574 board attached on the back
.. code-block:: yaml
@ -38,8 +47,8 @@ As the communication with the :ref:`I²C Bus <i2c>`, you need to have an ``i2c:`
display:
- platform: lcd_pcf8574
dimensions: 18x4
address: 0x3F
dimensions: 20x4
address: 0x27
lambda: |-
it.print("Hello World!");
@ -54,29 +63,32 @@ Configuration variables:
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``1s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. note::
If you're not seeing anything on the display, try turning the contrast potentiometer around on the
PCF8574 board.
.. _lcd-gpio:
lcd_gpio Component
------------------
The ``lcd_gpio`` display platform allows you to use standard character-based LCD displays like `this one <https://www.adafruit.com/product/181>`__
with ESPHome. This integration is only for LCD displays that display individual characters on a screen (usually 16-20 columns
and 2-4 rows), and not for LCD displays that can control each pixel individually. Also, this is the GPIO version of the LCD
integration where each of the data pins of the LCD needs a dedicated GPIO pin on the ESP. These LCD displays are also
commonly sold with a PCF8574 chip which only need two lines to the ESP, for that see :ref:`lcd-pcf8574`.
The ``lcd_gpio`` version of this component addresses the screen directly and does not employ a GPIO expander module.
Each of the data pins of the LCD needs a dedicated GPIO pin on the ESP. Connecting the screen this way offers
faster refresh, especially in conjunction with an :ref:`LCD Menu <lcd_menu>`.
.. figure:: images/lcd-full.jpg
.. figure:: images/lcd_gpio.svg
:align: center
:width: 75.0%
LCD Display.
LCD Display GPIO pinout
.. code-block:: yaml
# Example configuration entry
display:
- platform: lcd_gpio
dimensions: 18x4
dimensions: 20x4
data_pins:
- D0
- D1
@ -91,20 +103,25 @@ Configuration variables:
************************
- **dimensions** (**Required**, string): The dimensions of the display with ``COLUMNSxROWS``. If you're not
sure, power the display up and just count them.
- **data_pins** (**Required**, list of :ref:`Pin Schemas <config-pin_schema>`): A list of the data pins you
have hooked up to the LCD. The list can either be 8 items long (when you have connected all 8 data pins), or
4 items long (if you're operating in 4-bit mode with either the first 4 data pins connected or the last 4 data
pins connected).
- **enable_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin you have ``EN`` hooked up to.
- **rs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin you have ``RS`` hooked up to.
- **rw_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Optionally set the pin you have ``RW`` hooked up to.
You can also just permanently connect that pin to GND.
sure, power the display on, turn contrast high up and just count them.
- **data_pins** (**Required**, list of :ref:`pins <config-pin_schema>`): A list of the data pins you
have hooked up to the LCD. The list can either be 4 items long (operating in 4-bit mode with
either the first 4 data pins connected or the last 4 data pins connected), or 8 items long (when you have
connected all 8 data pins).
- **enable_pin** (**Required**, :ref:`pin <config-pin_schema>`): The pin you have ``E`` (``06``) hooked up to.
- **rs_pin** (**Required**, :ref:`pin <config-pin_schema>`): The pin you have ``RS`` (``04``) hooked up to.
- **rw_pin** (*Optional*, :ref:`pin <config-pin_schema>`): Optionally set the pin you have ``R/W`` (``05``) hooked up to. You can also just permanently connect that pin to ``GND``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-lcd_lambda` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``1s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. note::
If you're not seeing anything on the display, make sure you apply ``3.3V`` to the ``VEE`` (``03``) contrast control
pin of the board. You can use a potentiometer to make it adjustable.
.. _display-lcd_lambda:
Rendering Lambda
@ -135,7 +152,7 @@ by default which means the character at the top left.
// Let's write a sensor value (let's assume it's 42.1)
it.printf("%.1f", id(my_sensor).state);
// Result: "42.1" (the dot will appear on the "2" segment)
// Result: "42.1" (the dot will appear on the segment showing "2")
// Print a right-padded sensor value with 0 digits after the decimal
it.printf("Sensor value: %8.0f", id(my_sensor).state);
@ -147,62 +164,12 @@ by default which means the character at the top left.
# (Optional) For displaying time:
time:
- platform: sntp
- platform: homeassistant
id: my_time
.. note::
If you're not seeing anything on the display, make sure you try turning the contrast potentiometer around.
Please see :ref:`display-printf` for a quick introduction into the ``printf`` formatting rules and
:ref:`display-strftime` for an introduction into the ``strftime`` time formatting.
Backlight Control
-----------------
For the GPIO based display, the backlight is lit by applying Vcc to the A pin and K connected to ground.
The backlight can draw more power than the microcontroller output pins can supply, so it is advisable to use
a transistor as a switch to control the power for the backlight pins.
With the ``lcd_pcf8574`` the backlight can be turned on by ``it.backlight()`` and off by ``it.no_backlight()`` in the
display lambda definition. The jumper on the PCF8574 board needs to be closed for the backlight control to work.
Keep in mind that the display lambda runs for every ``update_interval``, so if the backlight is turned on/off there,
it cannot be overridden from other parts.
Here is one solution for a typical use-case where the backlight is turned on after a motion sensor activates and
turns off 90 seconds after the last activation of the sensor.
.. code-block:: yaml
display:
- platform: lcd_pcf8574
id: mydisplay
# ...
binary_sensor:
- platform: gpio
# ...
on_press:
then:
- binary_sensor.template.publish:
id: backlight
state: ON
- binary_sensor.template.publish:
id: backlight
state: OFF
- platform: template
id: backlight
filters:
- delayed_off: 90s
on_press:
then:
- lambda: |-
id(mydisplay).backlight();
on_release:
then:
- lambda: |-
id(mydisplay).no_backlight();
User Defined Characters
-----------------------
@ -242,13 +209,67 @@ defines a dot at the upper left and lower right of the character.
lambda: |-
it.print("Hello, world \x08 \x07!");
Try this `custom character generator <https://omerk.github.io/lcdchargen/>`__ to design your own sybmols.
Backlight Control
-----------------
With the ``lcd_pcf8574`` the backlight can be turned on by ``it.backlight()`` and off by ``it.no_backlight()`` in the
display lambda definition. The jumper on the PCF8574 board needs to be closed for the backlight control to work.
Keep in mind that the display lambda runs for every ``update_interval``, so if the backlight is turned on/off there,
it cannot be overridden from other parts.
With the ``lcd_gpio``, the backlight is lit by applying ``Vcc`` to the ``BLA`` (``15``) pin and connect ``BLK`` (``16``)
pin to ``GND``. The backlight can draw more power than the microcontroller output pins can supply, so it is advisable
to use a transistor as a switch to control the power for the backlight pins.
Below an example for a typical use-case where the backlight is turned on when a motion sensor activates and
turns off ``90`` seconds after the last activation of the sensor.
.. code-block:: yaml
display:
- platform: lcd_pcf8574
id: mydisplay
# ...
binary_sensor:
- platform: gpio
# ...
on_press:
then:
- binary_sensor.template.publish:
id: backlight
state: ON
- binary_sensor.template.publish:
id: backlight
state: OFF
- platform: template
id: backlight
filters:
- delayed_off: 90s
on_press:
then:
- lambda: |-
id(mydisplay).backlight();
on_release:
then:
- lambda: |-
id(mydisplay).no_backlight();
See Also
--------
- :doc:`index`
- :doc:`/components/switch/gpio`
- :doc:`/components/binary_sensor/gpio`
- :ref:`LCD Menu <lcd_menu>`
- :doc:`/components/pcf8574`
- :apiref:`lcd_base/lcd_display.h`
- `HD44780U (LCD-II) datasheet <https://www.sparkfun.com/datasheets/LCD/HD44780.pdf>`__
- `Charset cheatsheet <https://user-images.githubusercontent.com/1550668/173113487-9c98e866-8ee4-4a3c-a83f-61fe62057c5f.png>`__
- `Custom Character Generator <https://omerk.github.io/lcdchargen/>`__
- `Arduino LiquidCrystal Library <https://www.arduino.cc/en/Reference/LiquidCrystal>`__
- :apiref:`lcd_base/lcd_display.h`
- :ghedit:`Edit`

2
components/display_menu/index.rst
View File

@ -757,3 +757,5 @@ See Also
:glob:
*
- :ghedit:`Edit`

40
components/display_menu/lcd_menu.rst
View File

@ -1,3 +1,5 @@
.. _lcd_menu:
LCD Menu
========
@ -6,14 +8,13 @@ LCD Menu
:image: lcd_menu.png
The component provides an infrastructure for setting up a hierarchical menu
on the character based LCD displays.
on character based LCD displays. This offers the user an interactive method to display
labels, control entities like ``switch``, ``select``, ``number`` available locally on the
ESPHome node, without the requirement of a network connection.
.. figure:: images/lcd_menu.png
:align: center
:width: 50.0%
.. _lcd_menu:
:width: 60.0%
Overview
--------
@ -23,10 +24,10 @@ a hierarchical menu primarily intended to be controlled either by a rotary encod
with a button or a five-button joystick controller.
The component needs to be connected to an instance of a character based LCD display, which
at the moment are :ref:`lcd-pcf8574` or a :ref:`lcd-gpio`. For the best results the GPIO
connection is recommended; the I²C one running at the speed according to the datasheet
(usually ``100`` kHz) or even ESPHome default (``50`` kHz) will create perceptible delays especially
when changing a numeric value using the rotary encoder. Most ``PCF8574`` adapters used with
like :ref:`lcd-pcf8574` or :ref:`lcd-gpio`. For the best results the GPIO connection is
recommended; the I²C one running at the speed according to the datasheet (usually ``100``
kHz) or even ESPHome default (``50`` kHz) will create perceptible delays especially when
changing a numeric value using the rotary encoder. Most ``PCF8574`` adapters used with
these displays will happily run at ``200`` or even ``400`` kHz though so if you are comfortable
accepting risks from running your hardware out of spec, you might want to try that
in your :ref:`i2c` configuration.
@ -41,7 +42,7 @@ in your :ref:`i2c` configuration.
...
user_characters:
- position: 0
data: # back arrow
data: # mark_back symbol
- 0b00100
- 0b01000
- 0b11110
@ -68,22 +69,24 @@ in your :ref:`i2c` configuration.
items:
...
# Encoder to provide navigation
# Rotary encoder to provide navigation
sensor:
- platform: rotary_encoder
...
filters:
debounce: 30ms
on_anticlockwise:
- display_menu.up:
on_clockwise:
- display_menu.down:
# A de-bounced GPIO is used to 'click'
# A debounced GPIO push button is used to 'click'
binary_sensor:
- platform: gpio
...
filters:
- delayed_on: 10ms
- delayed_off: 10ms
- delayed_on: 30ms
- delayed_off: 30ms
on_press:
- display_menu.enter:
@ -95,17 +98,20 @@ Configuration variables:
Code of the character used to mark menu items going back one level, a selected one,
the editing mode and item leading to a submenu. Defaults to ``0x5e`` (``^``), ``0x3e`` (``>``),
``0x2a`` (``*``) and ``0x7e`` (a right arrow). As the character set lacks a good looking
up arrow, using a user defined character is advisable (use ``8`` to reference one at
position ``0`` to avoid problems with zeros in a string).
back arrow, using a user defined character is advisable for ``mark_back`` (use ``8`` to
reference one at position ``0`` to avoid problems with zeros in a string).
The rest of the configuration is described in the :ref:`Display Menu <display_menu>` component.
The menu inherits the dimensions of the connected LCD display and uses the whole area.
The menu inherits the dimensions of the connected LCD display and uses the entire area.
See Also
--------
- :ref:`i2c`
- :ref:`lcd-pcf8574`
- :ref:`lcd-gpio`
- :ref:`Display Menu <display_menu>`
- :doc:`/components/sensor/rotary_encoder`
- :doc:`/components/binary_sensor/index`
- :apiref:`lcd_menu/lcd_menu.h`
- :ghedit:`Edit`

2
components/sensor/scd4x.rst
View File

@ -6,7 +6,7 @@ SCD4X CO₂, Temperature and Relative Humidity Sensor
:image: scd4x.jpg
The ``scd4x`` sensor platform allows you to use your Sensirion SCD4X CO₂
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/9.5_CO2/Sensirion_CO2_Sensors_SCD4x_Datasheet.pdf>`__) sensors with ESPHome.
(`datasheet <https://sensirion.com/media/documents/C4B87CE6/627C2DCD/CD_DS_SCD40_SCD41_Datasheet_D1.pdf>`__) sensors with ESPHome.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
.. figure:: images/scd4x.jpg

6
guides/supporters.rst
View File

@ -237,11 +237,9 @@ Contributors
- `Dirk Heinke (@DirkHeinke) <https://github.com/DirkHeinke>`__
- `Dirk Jahnke (@dirkj) <https://github.com/dirkj>`__
- `Johann V. (@divinitas) <https://github.com/divinitas>`__
- `djwlindenaar (@djwlindenaar) <https://github.com/djwlindenaar>`__
- `Marcos Pérez Ferro (@djwmarcx) <https://github.com/djwmarcx>`__
- `Dan Mannock (@dmannock) <https://github.com/dmannock>`__
- `Dmitriy Lopatko (@dmitriy5181) <https://github.com/dmitriy5181>`__
- `dmkif (@dmkif) <https://github.com/dmkif>`__
- `Farzad E. (@dnetguru) <https://github.com/dnetguru>`__
- `DrZoid (@docteurzoidberg) <https://github.com/docteurzoidberg>`__
- `Dominik (@DomiStyle) <https://github.com/DomiStyle>`__
@ -449,6 +447,7 @@ Contributors
- `Johan van der Kuijl (@johanvanderkuijl) <https://github.com/johanvanderkuijl>`__
- `Johboh (@Johboh) <https://github.com/Johboh>`__
- `John Erik Halse (@johnerikhalse) <https://github.com/johnerikhalse>`__
- `John Moxley (@johnmoxley) <https://github.com/johnmoxley>`__
- `JonasEr (@JonasEr) <https://github.com/JonasEr>`__
- `Jonathan Adams (@jonathanadams) <https://github.com/jonathanadams>`__
- `Jonathan Treffler (@JonathanTreffler) <https://github.com/JonathanTreffler>`__
@ -553,6 +552,7 @@ Contributors
- `Ben Marengo (@marengaz) <https://github.com/marengaz>`__
- `Marvin Gaube (@margau) <https://github.com/margau>`__
- `Martynas Griškonis (@Margriko) <https://github.com/Margriko>`__
- `maringeph (@maringeph) <https://github.com/maringeph>`__
- `Mario (@mario-tux) <https://github.com/mario-tux>`__
- `Marek Marczykowski-Górecki (@marmarek) <https://github.com/marmarek>`__
- `Matthew Harrold (@marrold) <https://github.com/marrold>`__
@ -630,7 +630,6 @@ Contributors
- `Nazar Mokrynskyi (@nazar-pc) <https://github.com/nazar-pc>`__
- `Bergont Nicolas (@nbergont) <https://github.com/nbergont>`__
- `NMC (@ncareau) <https://github.com/ncareau>`__
- `Nebula (@nebula-it) <https://github.com/nebula-it>`__
- `NeoAcheron (@NeoAcheron) <https://github.com/NeoAcheron>`__
- `Mike Meessen (@netmikey) <https://github.com/netmikey>`__
- `Nick B. (@NickB1) <https://github.com/NickB1>`__
@ -801,7 +800,6 @@ Contributors
- `Ryan Hoffman (@tekmaven) <https://github.com/tekmaven>`__
- `testbughub (@testbughub) <https://github.com/testbughub>`__
- `Greg Lincoln (@tetious) <https://github.com/tetious>`__
- `Nejc (@thedexboy) <https://github.com/thedexboy>`__
- `Thomas Eckerstorfer (@TheEggi) <https://github.com/TheEggi>`__
- `Theexternaldisk (@Theexternaldisk) <https://github.com/Theexternaldisk>`__
- `TheGroundZero (@TheGroundZero) <https://github.com/TheGroundZero>`__