Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-02-28 03:41:57 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #2135 from esphome/bump-2022.6.0

Browse Source 
2022.6.0
This commit is contained in:
Jesse Hills 2022-06-16 12:59:57 +12:00 committed by GitHub
commit 5a20bbd23f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 922 additions and 100 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.5.1
PROJECT_NUMBER = 2022.6.0
# 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.5.1
ESPHOME_REF = 2022.6.0
.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify

1
_redirects
View File

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

BIN
_static/changelog-2022.6.0.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

2
_static/version
View File

@ -1 +1 @@
2022.5.1
2022.6.0

220
changelog/2022.6.0.rst Normal file
View File

@ -0,0 +1,220 @@
ESPHome 2022.6.0 - 15th June 2022
=================================
.. seo::
:description: Changelog for ESPHome 2022.6.0.
:image: /_static/changelog-2022.6.0.png
:author: Jesse Hills
:author_twitter: @jesserockz
.. imgtable::
:columns: 2
Tuya Select, components/select/tuya, tuya.png
SGP41, components/sensor/sgp4x, sgp40.jpg
Media Player Core, components/media_player/index, folder-open.svg
I2S Audio, components/media_player/i2s_audio, i2s_audio.svg
We are almost half way through 2022 already! My, how fast time flies when we
are having fun with ESPHome. This release is kind of small, but packs some big features.
There will be no 2022.7.0 (July) release next month as I (:ghuser:`jesserockz`) will be away
around that time. So lets hope we can make 2022.8.0 worth the wait.
🎶🎶🎶 Media Players
--------------------
ESPHome can now become a media player target for Home Assistant. This allows users to buy or build
ESP32 based speakers and place them around the house.
Link to `Media Players <https://esphome.github.io/media-players>`_.
Join us in a live stream all about Audio in the Open Home!
When: Thursday, June 16, at 7pm UTC / 12pm PST / 9pm CET
More info here...
.. raw:: html
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/SEH-DxOsywg"
title="YouTube video player" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>
Includes with vars
------------------
:ghuser:`jimtng` is a newcomer to ESPHome. While migrating everything from a certain other
firmware, they found that they had to duplicate lots of yaml configuration for their many devices.
Basically, they decided to upgrade the ``!include`` yaml "directive" to allow variables.
.. code-block:: yaml
# device.yaml
binary_sensor:
- <<: !include
file: bin-sensor.yaml
vars:
pin: GPIO1
name: "Binary Sensor 1"
switch: my_switch_1_id
delay: 10s
- <<: !include
file: bin-sensor.yaml
vars:
pin: GPIO1
name: "Binary Sensor 2"
switch: my_switch_2_id
delay: 60s
# bin-sensor.yaml
platform: gpio
pin: ${pin}
name: ${name}
on_press:
- switch.turn_on: ${switch}
- delay: ${delay}
- switch.turn_off: ${switch}
Now while this is probably not the best example, the variables act as ``substitutions``
and can be used anywhere in the underlying yaml file and can very much DRY out your configurations.
Breaking Changes
----------------
TCS34725 integration time
^^^^^^^^^^^^^^^^^^^^^^^^^
The sampling settings for the TCS34725 have had a new option ``auto`` added and set as the default. This allows for better accuracy.
You are able to set it back to the previous default value by specifying ``integration_time: 2.4ms`` in your configuration.
SGP40 moved
^^^^^^^^^^^
While adding support for the SGP41 chip, the SGP40 was moved and they were both combined into a new ``sgp4x`` component.
MQTT fan speeds
^^^^^^^^^^^^^^^
:esphomepr:`3397` removes deprecated MQTT fan speed state and speed command topics.
These were replaced with speed level state and command topics in ESPHome 2021.10.0.
AC Dimmer
^^^^^^^^^
Due to an output power calculation the perceived power might vary slightly specially in the lower and upper regions.
DisplayBuffer
^^^^^^^^^^^^^
A new virtual method was added to the DisplayBuffer class for specifying the display type. This change only affects ``external_components``.
See :esphomepr:`3430` for more details.
Full list of changes
--------------------
New Components
^^^^^^^^^^^^^^
- Add Tuya select :esphomepr:`3469` by :ghuser:`bearpawmaxim` (new-integration)
- Add support for SGP41 :esphomepr:`3382` by :ghuser:`martgras` (new-integration) (breaking-change)
- Implement Media Player and I2S Media player :esphomepr:`3487` by :ghuser:`jesserockz` (new-integration)
Breaking Changes
^^^^^^^^^^^^^^^^
- Tcs34725 automatic sampling settings for improved dynamics and accuracy :esphomepr:`3258` by :ghuser:`swifty99` (breaking-change)
- Add support for SGP41 :esphomepr:`3382` by :ghuser:`martgras` (new-integration) (breaking-change)
- Remove deprecated fan speeds :esphomepr:`3397` by :ghuser:`kbickar` (breaking-change)
- Output a true RMS voltage % :esphomepr:`3494` by :ghuser:`josephdouce` (breaking-change)
- Add display_type property to DisplayBuffer :esphomepr:`3430` by :ghuser:`guillempages` (breaking-change)
Beta Changes
^^^^^^^^^^^^
- publish fan speed count for discovery :esphomepr:`3537` by :ghuser:`ssieb`
- Nextion brightness setting requires an assignment :esphomepr:`3533` by :ghuser:`nagyv`
- Implement media player volume actions :esphomepr:`3551` by :ghuser:`jesserockz`
- Fix compilation with ESP32-S3 :esphomepr:`3543` by :ghuser:`misery`
- Bm3xx: Fix typo :esphomepr:`3559` by :ghuser:`martgras`
Notable Changes
^^^^^^^^^^^^^^^
- Add variable substitutions for !include :esphomepr:`3510` by :ghuser:`jimtng` (notable-change)
All changes
^^^^^^^^^^^
- Tcs34725 automatic sampling settings for improved dynamics and accuracy :esphomepr:`3258` by :ghuser:`swifty99` (breaking-change)
- Remove duplicate convert_to_8bit_color function. :esphomepr:`2469` by :ghuser:`davet2001`
- Bump esptool from 3.3 to 3.3.1 :esphomepr:`3468` by :ghuser:`dependabot[bot]`
- Bump pylint from 2.13.8 to 2.13.9 :esphomepr:`3470` by :ghuser:`dependabot[bot]`
- Tuya status gpio support :esphomepr:`3466` by :ghuser:`bearpawmaxim`
- Add Tuya select :esphomepr:`3469` by :ghuser:`bearpawmaxim` (new-integration)
- MQTT cover: send state even if position is available :esphomepr:`3473` by :ghuser:`pyos`
- Ili9341 8bit indexed mode pt1 :esphomepr:`2490` by :ghuser:`davet2001`
- feat: esp32-camera add stream event :esphomepr:`3285` by :ghuser:`myml`
- Add support for SGP41 :esphomepr:`3382` by :ghuser:`martgras` (new-integration) (breaking-change)
- add support user-defined modbus functions :esphomepr:`3461` by :ghuser:`gazoodle`
- Remove deprecated fan speeds :esphomepr:`3397` by :ghuser:`kbickar` (breaking-change)
- Fix compile issues on windows :esphomepr:`3491` by :ghuser:`jesserockz`
- midea: New power_toggle action. Auto-use remote transmitter. :esphomepr:`3496` by :ghuser:`dudanov`
- Output a true RMS voltage % :esphomepr:`3494` by :ghuser:`josephdouce` (breaking-change)
- [scd4x] Fix not passing arguments to templatable value for perform_forced_calibration :esphomepr:`3495` by :ghuser:`Wumpf`
- Thermostat preset with modes :esphomepr:`3298` by :ghuser:`MrMDavidson`
- Allow Prometheus component to export internal components :esphomepr:`3508` by :ghuser:`jangrewe`
- [BedJet] Add configurable heating strategy :esphomepr:`3519` by :ghuser:`jhansche`
- Add variable substitutions for !include :esphomepr:`3510` by :ghuser:`jimtng` (notable-change)
- Change rain intensity sensor string :esphomepr:`3511` by :ghuser:`wtremmel`
- Implement Media Player and I2S Media player :esphomepr:`3487` by :ghuser:`jesserockz` (new-integration)
- Add mqtt.on_connect and mqtt.on_disconnect triggers :esphomepr:`3520` by :ghuser:`jimtng`
- Refactor clock syncing :esphomepr:`3503` by :ghuser:`jhansche`
- Added RC6 protocol support :esphomepr:`3514` by :ghuser:`Emrvb`
- Add display_type property to DisplayBuffer :esphomepr:`3430` by :ghuser:`guillempages` (breaking-change)
- Correct ADC auto-range for ESP32-S2 variant (13 bit adc) :esphomepr:`3158` by :ghuser:`CarlosGS`
- Suppress first rotary encoder event :esphomepr:`3532` by :ghuser:`mmakaay`
- Fix endless 'WiFi Unknown connection status 0' loop :esphomepr:`3530` by :ghuser:`mmakaay`
- support rotated ILI9341 (ILI9342) :esphomepr:`3526` by :ghuser:`ssieb`
- Fix sdp3x error checking :esphomepr:`3531` by :ghuser:`Azimath`
- Fix percentage validation for wrong data type input :esphomepr:`3524` by :ghuser:`mmakaay`
- Block Tuya light from reacting to dp changes if transitioning :esphomepr:`3076` by :ghuser:`VitaliyKurokhtin`
- Cleanup deprecated EntityBase::hash_base() :esphomepr:`3525` by :ghuser:`mmakaay`
- Fix bogus reading on no communication with MAX31865 :esphomepr:`3505` by :ghuser:`DAVe3283`
- Implement the media player actions :esphomepr:`3534` by :ghuser:`jesserockz`
- RG15 data is float/double, not int :esphomepr:`3512` by :ghuser:`wtremmel`
- publish fan speed count for discovery :esphomepr:`3537` by :ghuser:`ssieb`
- Nextion brightness setting requires an assignment :esphomepr:`3533` by :ghuser:`nagyv`
- Implement media player volume actions :esphomepr:`3551` by :ghuser:`jesserockz`
- Fix compilation with ESP32-S3 :esphomepr:`3543` by :ghuser:`misery`
- Bm3xx: Fix typo :esphomepr:`3559` by :ghuser:`martgras`
Past Changelogs
---------------
- :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.5.0.html
:url: /changelog/2022.6.0.html
.. toctree::
:glob:

28
components/climate/bedjet.rst
View File

@ -41,6 +41,10 @@ Configuration variables:
- **ble_client_id** (**Required**, :ref:`config-id`): The ID of the BLE Client.
- **time_id** (*Optional*, :ref:`config-id`): The ID of a :ref:`Time Component <time>` which
can be used to set the time on the BedJet device.
- **heat_mode** (*Optional*, string): The primary heating mode to use for `HVACMode.HEAT`:
- ``"heat"`` (Default) - Setting ``hvac_mode=heat`` uses the BedJet "HEAT" mode.
- ``"extended"`` - Setting ``hvac_mode=heat`` uses BedJet "EXT HEAT" mode.
- Whichever is not selected will be made available as a custom preset.
- All other options from :ref:`Climate <config-climate>`.
lambda calls
@ -60,6 +64,30 @@ From :ref:`lambdas <config-lambda>`, you can call methods to do some advanced st
- lambda: |-
id(my_bedjet_fan).upgrade_firmware();
- ``.send_local_time``: If `time_id` is set, attempt to sync the clock now.
.. code-block:: yaml
button:
- platform: template
name: "Sync Clock"
on_press:
then:
- lambda: |-
id(my_bedjet_fan).send_local_time();
- ``.set_clock``: Set the BedJet clock to a specified time; works with or without a `time_id`.
.. code-block:: yaml
button:
- platform: template
name: "Set Clock to 10:10pm"
on_press:
then:
- lambda: |-
id(my_bedjet_fan).set_clock(22, 10);
Known issues:
-------------

22
components/climate/midea.rst
View File

@ -40,7 +40,6 @@ The ``midea`` component creates a Midea air conditioner climate device.
climate:
- platform: midea
name: Midea Climate # Use a unique name.
transmitter_id: # Optional. Add this option to use IR transmitter.
period: 1s # Optional
timeout: 2s # Optional
num_attempts: 3 # Optional
@ -83,7 +82,7 @@ Configuration variables:
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :doc:`../uart` if you want
to use multiple UART buses.
- **name** (**Required**, string): The name of the climate device.
- **transmitter_id** (*Optional*, :ref:`config-id`): Set if you use :doc:`../remote_transmitter` component for IR commands transmit.
- **transmitter_id** (*Optional*, :ref:`config-id`): Defined and used automatically when using :doc:`../remote_transmitter` component for IR commands transmit.
- **period** (*Optional*, :ref:`config-time`): Minimal period between requests to the appliance. Defaults to ``1s``.
- **timeout** (*Optional*, :ref:`config-time`): Request response timeout until next request attempt. Defaults to ``2s``.
- **num_attempts** (*Optional*, int): Number of request attempts between 1 and 5 inclusive. Defaults to ``3``.
@ -121,7 +120,7 @@ Automations
.. _midea_ac-power_on_action:
``midea_ac.power_on`` Action
******************************
****************************
This action turn on power. The mode and preset will be restored to the last state before turned off.
@ -134,7 +133,7 @@ This action turn on power. The mode and preset will be restored to the last stat
.. _midea_ac-power_off_action:
``midea_ac.power_off`` Action
******************************
*****************************
This action turn off power.
@ -144,6 +143,19 @@ This action turn off power.
then:
- midea_ac.power_off:
.. _midea_ac-power_toggle_action:
``midea_ac.power_toggle`` Action
********************************
This action toggle the power state. Identical to pressing the power button on the remote control.
.. code-block:: yaml
on_...:
then:
- midea_ac.power_toggle:
.. _midea_ac-follow_me_action:
@ -200,7 +212,7 @@ This action adjust the louver by one step. :doc:`../remote_transmitter` required
.. _midea_ac-beeper_on_action:
``midea_ac.beeper_on`` Action
******************************
*****************************
This action turn on beeper feedback.

112
components/climate/thermostat.rst
View File

@ -163,8 +163,8 @@ Default Target Temperatures and Mode
These configuration items determine default values the thermostat controller should use when it starts.
- **default_mode** (*Optional*, climate mode): The default climate mode the controller should use if it
is unable to restore it from memory. One of:
- **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)
- ``heat_cool``
@ -180,14 +180,20 @@ than ``off``. If this option is not configured, you'll need to manually change
the front end (Home Assistant), an ESPHome action, automation, or from within a lambda elsewhere in your
device's configuration.
- **default_target_temperature_low** (*Optional*, float): The default low target
- **default_target_temperature_low** (*Optional*, *Deprecated*, float): The default low target
temperature for the control algorithm. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (*Optional*, float): The default high target
- **default_target_temperature_high** (*Optional*, *Deprecated*, float): The default high target
temperature for the control algorithm. This can be dynamically set in the frontend later.
**At least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
**must be specified.**
.. note::
**default_mode**, **default_target_temperature_low**, and **default_target_temperature_high** are
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
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`.
@ -309,7 +315,7 @@ 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*): Additionally specify target temperature range settings for away mode.
- **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).
@ -321,6 +327,102 @@ Set Point Options/Behavior
**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:
Presets
*******
Presets allow you to define a combination of set points, climate, fan, and swing modes that can be recalled from
the front end (Home Assistant) as a single operation for quick and easy access. This can simplify the user
experience and automation.
- **preset**: (*Optional*, list)
- **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
`climate.set_preset_mode` service treats them identically
- **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``
- ``dry``
- ``fan_only``
- ``auto``
- **fan_mode** (*Optional*, climate fan mode): The fan mode the thermostat should switch to when this preset
is activated. If not specified, the thermostat's fan mode will remain unchanged when the preset is activated.
One of:
- ``on``
- ``off``
- ``auto``
- ``low``
- ``medium``
- ``high``
- ``middle``
- ``focus``
- ``diffuse``
- **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``
- ``vertical``
.. code-block:: yaml
# Example climate controller with presets
climate:
- platform: thermostat
name: "Thermostat with Presets"
preset:
# Standard Preset
- name: sleep
default_target_temperature_low: 17
default_target_temperature_high: 26
fan_mode: LOW
swing_mode: OFF
# Custom preset
- name: A custom preset
default_target_temperature_low: 21
default_target_temperature_high: 23
fan_mode: HIGH
mode: HEAT_COOL
- **preset_change**: (*Optional*, :ref:`Action <config-action>`): The action to call when the preset is changed. This
will be called either when a user changes the mode through the Home Assistant UI or through a call to ``climate.control``
.. code-block:: yaml
# Example climate controller with preset and change action
climate:
- platform: thermostat
name: "Thermostat with Presets Actions"
preset:
- name: sleep
default_target_temperature_low: 17
default_target_temperature_high: 26
fan_mode: LOW
swing_mode: OFF
preset_change:
- logger.log: Preset has been changed!
Additional Actions/Behavior
***************************

5
components/display/ili9341.rst
View File

@ -45,6 +45,7 @@ Configuration variables:
- ``M5STACK``
- ``TFT 2.4``
- ``TFT 2.4R`` (ILI9342)
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin.
@ -60,6 +61,10 @@ Configuration variables:
or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **color_palette** (*Optional*): The type of color pallet that will be used in the ESP's internal 8-bits-per-pixel buffer. This can be used to improve color depth quality of the image. For example if you know that the display will only be showing grayscale images, the clarity of the display can be improved by targeting the available colors to monochrome only. Options are:
- ``NONE`` (default)
- ``GRAYSCALE``
Configuration examples
**********************

7
components/esp32_camera.rst
View File

@ -147,6 +147,13 @@ White Balance Setting:
- ``office``: White balance office mode
- ``home``: White balance home mode
Automations:
- **on_stream_start** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when a stream starts.
- **on_stream_end** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when a stream stops.
Test Setting:
- **test_pattern** (*Optional*, boolean): For tests purposes, it's possible to replace picture get from sensor by a test color pattern. Defaults to ``false``.

1
components/index.rst
View File

@ -20,4 +20,5 @@ Components
stepper/index
touchscreen/index
lock/index
media_player/index
*

54
components/media_player/i2s_audio.rst Normal file
View File

@ -0,0 +1,54 @@
I2S Audio Media Player
======================
.. seo::
:description: Instructions for setting up I2S based media players in ESPHome.
:image: i2s_audio.svg
The ``i2s_audio`` media player platform allows you to play media from webservers and web streams
via the I2S bus. This platform only works on ESP32 based chips.
.. code-block:: yaml
# Example configuration entry
media_player:
- platform: i2s_audio
name: ESPHome I2S Media Player
dac_type: external
i2s_lrclk_pin: GPIO33
i2s_dout_pin: GPIO22
i2s_bclk_pin: GPIO19
mode: mono
Configuration variables:
------------------------
- **dac_type** (**Required**, enum)
- ``external``: Use an external DAC, for example the NS4168.
- ``internal``: Use the internal DAC
- All other options from :ref:`Media Player <config-media_player>`
External DAC
************
- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S LRCLK signal.
- **i2s_dout_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S DOUT signal.
- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S BCLK signal.
- **mode** (*Optional*, string): The mode of the I2S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
Internal DAC
************
- **mode** (**Required**, enum): The channel mode of the internal DAC.
- ``left``
- ``right``
- ``stereo``
See also
--------
- :doc:`index`
- :ghedit:`Edit`

130
components/media_player/index.rst Normal file
View File

@ -0,0 +1,130 @@
Media Player Components
=======================
.. seo::
:description: Instructions for setting up generic media players in ESPHome.
:image: folder-open.svg
The ``media_player`` domain includes all platforms that implement media player
functionality.
.. note::
ESPHome media players require Home Assistant 2022.6 or newer.
.. _config-media_player:
Base Media Player Configuration
-------------------------------
.. code-block:: yaml
media_player:
- platform: ...
name: "Media Player Name"
Configuration variables:
- **name** (**Required**, string): The name of the media player.
- **icon** (*Optional*, icon): Manually set the icon to use for the
media player in the frontend.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Set to ``""`` to remove the default entity category.
Media Player Actions
--------------------
All ``media_player`` actions can be used without specifying an ``id`` if you have only one ``media_player`` in
your configuration YAML.
Configuration variables:
**id** (*Optional*, :ref:`config-id`): The media player to control. Defaults to the only one in YAML.
.. _media_player-play:
``media_player.play`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This action will resume playing the media player.
A future change will allow specifying the ``media_url`` for starting
a new stream.
.. _media_player-pause:
``media_player.pause`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This action pauses the current playback.
.. _media_player-stop:
``media_player.stop`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This action stops the current playback.
.. _media_player-toggle:
``media_player.toggle`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This action will pause or resume the current playback.
.. _media_player-volume_up:
``media_player.volume_up`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This action will increase the volume of the media player.
.. _media_player-volume_down:
``media_player.volume_down`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This action will decrease the volume of the media player.
.. _media_player-volume_set:
``media_player.volume_set`` Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This action will set the volume of the media player.
.. code-block::
on_...:
# Simple
- media_player.volume_set: 50%
# Full
- media_player.volume_set:
id: media_player_id
volume: 50%
# Simple with lambda
- media_player.volume_set: !lambda "return 0.5;"
Configuration variables:
**volume** (**Required**, percentage): The volume to set the media player to.
See Also
--------
.. toctree::
:maxdepth: 1
:glob:
*
- :ghedit:`Edit`

20
components/mqtt.rst
View File

@ -89,6 +89,10 @@ Configuration variables:
- **keepalive** (*Optional*, :ref:`config-time`): The time
to keep the MQTT socket alive, decreasing this can help with overall stability due to more
WiFi traffic with more pings. Defaults to 15 seconds.
- **on_connect** (*Optional*, :ref:`Automation <automation>`): An action to be performed when a connection
to the broker is established.
- **on_disconnect** (*Optional*, :ref:`Automation <automation>`): An action to be performed when the connection
to the broker is dropped.
- **on_message** (*Optional*, :ref:`Automation <automation>`): An action to be
performed when a message on a specific MQTT topic is received. See :ref:`mqtt-on_message`.
- **on_json_message** (*Optional*, :ref:`Automation <automation>`): An action to be
@ -368,6 +372,22 @@ Configuration variables:
When changing these options and you're using MQTT discovery, you will need to restart Home Assistant.
This is because Home Assistant only discovers a device once in every Home Assistant start.
.. _mqtt-on_connect_disconnect:
``on_connect`` / ``on_disconnect`` Trigger
------------------------------------------
This trigger is activated when a connection to the MQTT broker is established or dropped.
.. code-block:: yaml
mqtt:
# ...
on_connect:
- switch.turn_on: switch1
on_disconnect:
- switch.turn_off: switch1
.. _mqtt-on_message:
``on_message`` Trigger

2
components/prometheus.rst
View File

@ -27,6 +27,8 @@ Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **include_internal** (*Optional*, boolean): Whether ``internal`` entities should be displayed on the
web interface. Defaults to ``false``.
.. note::

9
components/remote_receiver.rst
View File

@ -43,6 +43,7 @@ Configuration variables:
- **pronto**: Print remote code in Pronto form. Useful for using arbitrary protocols.
- **raw**: Print all remote codes in their raw form. Also useful for using arbitrary protocols.
- **rc5**: Decode and dump RC5 IR codes.
- **rc6**: Decode and dump RC6 IR codes.
- **rc_switch**: Decode and dump RCSwitch RF codes.
- **samsung**: Decode and dump Samsung infrared codes.
- **samsung36**: Decode and dump Samsung36 infrared codes.
@ -111,6 +112,9 @@ Automations:
- **on_rc5** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
RC5 remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::RC5Data`
is passed to the automation for use in lambdas.
- **on_rc6** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
RC6 remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::RC6Data`
is passed to the automation for use in lambdas.
- **on_rc_switch** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
RCSwitch RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::RCSwitchData`
is passed to the automation for use in lambdas.
@ -232,6 +236,11 @@ Remote code selection (exactly one of these has to be included):
- **address** (**Required**, int): The address to trigger on, see dumper output for more info.
- **command** (**Required**, int): The RC5 command to listen for.
- **rc6**: Trigger on a decoded RC6 remote code with the given data.
- **address** (**Required**, int): The address to trigger on, see dumper output for more info.
- **command** (**Required**, int): The RC6 command to listen for.
- **rc_switch_raw**: Trigger on a decoded RC Switch raw remote code with the given data.
- **code** (**Required**, string): The remote code to listen for, copy this from the dumper output. To ignore a bit

20
components/remote_transmitter.rst
View File

@ -358,6 +358,26 @@ Configuration variables:
- **command** (**Required**, int): The RC5 command to send.
- All other options from :ref:`remote_transmitter-transmit_action`.
.. _remote_transmitter-transmit_rc6:
``remote_transmitter.transmit_rc6`` Action
******************************************
This :ref:`action <config-action>` sends an RC6 infrared remote code to a remote transmitter.
.. code-block:: yaml
on_...:
- remote_transmitter.transmit_rc6:
address: 0x1F
command: 0x3F
Configuration variables:
- **address** (**Required**, int): The address to send, see dumper output for more details.
- **command** (**Required**, int): The RC6 command to send.
- All other options from :ref:`remote_transmitter-transmit_action`.
.. _remote_transmitter-transmit_rc_switch_raw:
``remote_transmitter.transmit_rc_switch_raw`` Action

69
components/select/tuya.rst Normal file
View File

@ -0,0 +1,69 @@
Tuya Select
===========
.. seo::
:description: Instructions for setting up a Tuya device select.
:image: tuya.png
The ``tuya`` select platform creates a select from a tuya serial component
and requires :doc:`/components/tuya` to be configured.
.. code-block:: text
[08:51:09][C][tuya:032]: Tuya:
[08:51:09][C][tuya:043]: Datapoint 1: switch (value: ON)
[08:51:09][C][tuya:045]: Datapoint 24: int value (value: 220)
[08:51:09][C][tuya:045]: Datapoint 16: int value (value: 22)
[08:51:09][C][tuya:049]: Datapoint 2: enum (value: 1)
[08:51:09][C][tuya:045]: Datapoint 19: int value (value: 40)
[08:51:09][C][tuya:045]: Datapoint 101: int value (value: 1)
[08:51:09][C][tuya:045]: Datapoint 27: int value (value: -2)
[08:51:09][C][tuya:049]: Datapoint 43: enum (value: 1)
[08:51:09][C][tuya:049]: Datapoint 102: enum (value: 1)
[08:51:09][C][tuya:051]: Datapoint 45: bitmask (value: 0)
[08:51:09][C][tuya:043]: Datapoint 10: switch (value: ON)
[08:51:09][C][tuya:041]: Datapoint 38: raw (value: 06.00.14.08.00.0F.0B.1E.0F.0C.1E.0F.11.00.16.16.00.0F.08.00.16.17.00.0F (24))
[08:51:09][C][tuya:049]: Datapoint 36: enum (value: 1)
[08:51:09][C][tuya:057]: GPIO Configuration: status: pin 14, reset: pin 0 (not supported)
[08:51:09][C][tuya:061]: Status Pin: GPIO14
[08:51:09][C][tuya:063]: Product: '{"p":"gogb05wrtredz3bs","v":"1.0.0","m":0}'
On this controller, the datapoint 36 represents the temperature sensor selection
setting which is what we are interested in controlling using this platform.
Based on this, you can create the select as follows:
.. code-block:: yaml
# Create a select
select:
- platform: "tuya"
name: "Sensor selection"
enum_datapoint: 2
optimistic: true
options:
0: Internal:
1: Floor:
2: Both:
Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the switch.
- **enum_datapoint** (**Required**, int): The enum datapoint id number for the select.
- **options** (**Required**, Map[int, str]): Provide a mapping from values (int) of
this Select to options (str) of the *enum_datapoint* and vice versa. All options and
all values have to be unique.
- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
any command sent to the Select will immediately update the reported state.
- All other options from :ref:`Select <config-select>`.
See Also
--------
- :doc:`/components/select/index`
- :apiref:`tuya/select/tuya_select.h`
- :ghedit:`Edit`

2
components/sensor/sen5x.rst
View File

@ -213,6 +213,6 @@ See Also
- :doc:`ccs811`
- :doc:`scd4x`
- :doc:`sps30`
- :doc:`sgp40`
- :doc:`sgp4x`
- :apiref:`sen5x/sen5x.h`
- :ghedit:`Edit`

72
components/sensor/sgp40.rst
View File

@ -1,72 +0,0 @@
SGP40 Volatile Organic Compound Sensor
======================================
.. seo::
:description: Instructions for setting up SGP40 Volatile Organic Compound sensor
:image: sgp40.jpg
The ``sgp40`` sensor platform allows you to use your Sensirion SGP40 VOC sensor
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/9_Gas_Sensors/Sensirion_Gas_Sensors_SGP40_Datasheet.pdf>`__) with ESPHome.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
.. note::
This sensor need to be driven at a rate of 1Hz. Because of this, the
sensor will be read out on device once a second separately from the
update_interval. The state will be reported to other components, or
the front end at the update_interval, saving wifi power and network
communication.
.. figure:: images/sgp40.jpg
:align: center
:width: 80.0%
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: sgp40
name: "Workshop VOC"
Configuration variables:
------------------------
- **name** (**Required**, string): The name for the CO₂eq sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``
- **store_baseline** (*Optional*, boolean): Stores and retrieves the baseline information for quicker startups. Defaults to ``true``
- **compensation** (*Optional*): The block containing sensors used for compensation. If not set defaults will be used.
- **temperature_source** (*Optional*, :ref:`config-id`): Give an external temperature sensor ID
here. This can improve the sensor's internal calculations. Defaults to ``25``
- **humidity_source** (*Optional*, :ref:`config-id`): Give an external humidity sensor ID
here. This can improve the sensor's internal calculations. Defaults to ``50``
- All other options from :ref:`Sensor <config-sensor>`.
Example With Compensation
-------------------------
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: sgp40
name: "Workshop VOC"
update_interval: 5s
compensation:
humidity_source: dht1_hum
temperature_source: dht1_temp
See Also
--------
- :ref:`sensor-filters`
- :doc:`dht`
- :doc:`dht12`
- :doc:`hdc1080`
- :doc:`htu21d`
- :doc:`sht3xd`
- :apiref:`sgp40/sgp40.h`
- :ghedit:`Edit`

109
components/sensor/sgp4x.rst Normal file
View File

@ -0,0 +1,109 @@
SGP40 Volatile Organic Compound Sensor and SGP41 VOC and NOx Sensor
===================================================================
.. seo::
:description: Instructions for setting up SGP40/SGP41 Volatile Organic Compound and NOx sensor
:image: sgp40.jpg
The ``sgp4x`` sensor platform allows you to use your Sensirion SGP40
(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/9_Gas_Sensors/Sensirion_Gas_Sensors_SGP40_Datasheet.pdf>`__) or SGP41
(`datasheet <https://sensirion.com/media/documents/5FE8673C/61E96F50/Sensirion_Gas_Sensors_Datasheet_SGP41.pdf>`__) with ESPHome.
The type of sensor used is automatically detected.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
.. note::
This sensor need to be driven at a rate of 1Hz. Because of this, the
sensor will be read out on device once a second separately from the
update_interval. The state will be reported to other components, or
the front end at the update_interval, saving wifi power and network
communication.
.. figure:: images/sgp40.jpg
:align: center
:width: 80.0%
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: sgp4x
voc:
name: "VOC Index"
nox:
name: "NOx Index"
Configuration variables:
------------------------
- **voc** (*Optional*): VOC Index
- **name** (**Required**, string): The name of the sensor.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **algorithm_tuning** (*Optional*): The VOC algorithm can be customized by tuning 6 different parameters. For more details see `Engineering Guidelines for SEN5x <https://sensirion.com/media/documents/25AB572C/61E961EA/Sensirion_Engineering_Guidelines_SEN5x.pdf>`__
- **index_offset** (*Optional*): VOC index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100.
- **learning_time_offset_hours** (*Optional*): Time constant to estimate the VOC algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hour
- **learning_time_gain_hours** (*Optional*): Time constant to estimate the VOC algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
- **gating_max_duration_minutes** (*Optional*): Maximum duration of gating in minutes (freeze of estimator during high VOC index signal). Zero disables the gating. Allowed values are in range 0..3000. The default value is 180 minutes
- **std_initial** (*Optional*): Initial estimate for standard deviation. Lower value boosts events during initial learning period, but may result in larger device-todevice variations. Allowed values are in range 10..5000. The default value is 50.
- **gain_factor:** (*Optional*): Gain factor to amplify or to attenuate the VOC index output. Allowed values are in range 1..1000. The default value is 230.
- All other options from :ref:`Sensor <config-sensor>`.
- **nox** (*Optional*): NOx Index. Only available with SGP41. If a SGP40 sensor is detected this sensor will be ignored
- **name** (**Required**, string): The name of the sensor.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **algorithm_tuning** (*Optional*): The NOx algorithm can be customized by tuning 5 different parameters.For more details see `Engineering Guidelines for SEN5x <https://sensirion.com/media/documents/25AB572C/61E961EA/Sensirion_Engineering_Guidelines_SEN5x.pdf>`__
- **index_offset** (*Optional*): NOx index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100.
- **learning_time_offset_hours** (*Optional*): Time constant to estimate the NOx algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hour
- **learning_time_gain_hours** (*Optional*): Time constant to estimate the NOx algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
- **gating_max_duration_minutes** (*Optional*): Maximum duration of gating in minutes (freeze of estimator during high NOx index signal). Zero disables the gating. Allowed values are in range 0..3000. The default value is 180 minutes
- **std_initial** (*Optional*): The initial estimate for standard deviation parameter has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command. This parameter must always be set to 50.
- **gain_factor:** (*Optional*)
- All other options from :ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``
- **store_baseline** (*Optional*, boolean): Stores and retrieves the baseline information for quicker startups. Defaults to ``true``
- **compensation** (*Optional*): The block containing sensors used for compensation. If not set defaults will be used.
- **temperature_source** (*Optional*, :ref:`config-id`): Give an external temperature sensor ID
here. This can improve the sensor's internal calculations. Defaults to ``25``
- **humidity_source** (*Optional*, :ref:`config-id`): Give an external humidity sensor ID
here. This can improve the sensor's internal calculations. Defaults to ``50``
Example With Compensation
-------------------------
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: sgp4x
voc:
name: "VOC Index"
nox:
name: "NOx Index"
compensation:
humidity_source: dht1_hum
temperature_source: dht1_temp
See Also
--------
- :ref:`sensor-filters`
- :doc:`dht`
- :doc:`dht12`
- :doc:`hdc1080`
- :doc:`htu21d`
- :doc:`sht3xd`
- :doc:`sht4x`
- :apiref:`sgp4x/sgp4x.h`
- :ghedit:`Edit`

22
components/sensor/tcs34725.rst
View File

@ -60,9 +60,10 @@ Configuration variables:
- **illuminance** (*Optional*): Get the total illuminance of the sensor in lx.
- **color_temperature** (*Optional*): Get the calculated color temperature of the light in Kelvin.
- **gain** (*Optional*): Set the gain for the internal ADCs to work better in certain low-light conditions. Valid
values are ``1x`` (default), ``4x``, ``16x``, ``60x`` (highest gain).
values are ``1x`` (default), ``4x``, ``16x``, ``60x`` (highest gain). Will be overwritten if auto integration time
is used
- **integration_time** (*Optional*): The amount of time the light sensor is exposed. Valid values are
``2.4ms`` (default), ``24ms``, ``50ms``, ``101ms``, ``120ms``, ``154ms``, ``180ms``, ``199ms``,
``auto`` (default), ``2.4ms``, ``24ms``, ``50ms``, ``101ms``, ``120ms``, ``154ms``, ``180ms``, ``199ms``,
``240ms``, ``300ms``, ``360ms``, ``401ms``, ``420ms``, ``480ms``, ``499ms``, ``540ms``, ``600ms``, ``614ms``.
- **glass_attenuation_factor** (*Optional*): The attenuation factor of glass if it's behind some glass facia.
Default is ``1.0`` means ``100%`` transmissivity. ``2`` means ``50%`` transmissivity etc.
@ -70,6 +71,23 @@ Configuration variables:
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
For many applications, you can use AUTO timing or leave integration time empty to have the ESP select a suitable gain
setting based on the previous measurement. If light levels change dramatically this may cause the next reading to saturate,
after which the gain will adjust down and subsequent readings will be in range.
If auto is used in a dynamic environment an update rate of 1 second is best. Filters can be used to throttle the output and
prevent updates of marginal changes like:
.. code-block:: yaml
illuminance:
name: "TCS34725 Illuminance"
filters:
- or:
- delta: 50
- throttle: 60sec
When using integration times lower than 154ms the accuracy of the sensor drops with no further gain in possible light
accumulation. Use faster timings only if fast readout is necessary with stable light conditions recommended.
See Also
--------

26
components/tuya.rst
View File

@ -40,12 +40,38 @@ Here is an example output for a Tuya fan controller:
[12:39:45][C][tuya:032]: Datapoint 9: switch (value: OFF)
[12:39:45][C][tuya:046]: Product: '{"p":"hqq73kftvzh8c92u","v":"1.0.0","m":0}'
Here is another example output for a Tuya ME-81H thermostat:
.. code-block:: text
[08:51:09][C][tuya:032]: Tuya:
[08:51:09][C][tuya:043]: Datapoint 1: switch (value: ON)
[08:51:09][C][tuya:045]: Datapoint 24: int value (value: 220)
[08:51:09][C][tuya:045]: Datapoint 16: int value (value: 22)
[08:51:09][C][tuya:049]: Datapoint 2: enum (value: 1)
[08:51:09][C][tuya:045]: Datapoint 19: int value (value: 40)
[08:51:09][C][tuya:045]: Datapoint 101: int value (value: 1)
[08:51:09][C][tuya:045]: Datapoint 27: int value (value: -2)
[08:51:09][C][tuya:049]: Datapoint 43: enum (value: 1)
[08:51:09][C][tuya:049]: Datapoint 102: enum (value: 1)
[08:51:09][C][tuya:051]: Datapoint 45: bitmask (value: 0)
[08:51:09][C][tuya:043]: Datapoint 10: switch (value: ON)
[08:51:09][C][tuya:041]: Datapoint 38: raw (value: 06.00.14.08.00.0F.0B.1E.0F.0C.1E.0F.11.00.16.16.00.0F.08.00.16.17.00.0F (24))
[08:51:09][C][tuya:049]: Datapoint 36: enum (value: 1)
[08:51:09][C][tuya:057]: GPIO Configuration: status: pin 14, reset: pin 0 (not supported)
[08:51:09][C][tuya:061]: Status Pin: GPIO14
[08:51:09][C][tuya:063]: Product: '{"p":"gogb05wrtredz3bs","v":"1.0.0","m":0}'
Configuration variables:
------------------------
- **time_id** (*Optional*, :ref:`config-id`): Some Tuya devices support obtaining local time from ESPHome.
Specify the ID of the :ref:`Time Component <time>` which will be used.
- **status_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Some Tuya devices support WiFi status reporting ONLY through gpio pin.
Specify the pin reported in the config dump or leave empty otherwise.
More about this `here <https://developer.tuya.com/en/docs/iot/tuya-cloud-universal-serial-port-access-protocol?id=K9hhi0xxtn9cb#title-6-Query%20working%20mode>`__.
- **ignore_mcu_update_on_datapoints** (*Optional*, list): A list of datapoints to ignore MCU updates for. Useful for certain broken/erratic hardware and debugging.
Automations:

4
conf.py
View File

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

2
cookbook/iaq_board.rst
View File

@ -53,7 +53,7 @@ See Also
- :doc:`/components/sensor/pmsx003`
- :doc:`/components/sensor/mhz19`
- :doc:`/components/sensor/sgp30`
- :doc:`/components/sensor/sgp40`
- :doc:`/components/sensor/sgp4x`
- :doc:`/components/sensor/tsl2561`
- :doc:`/components/binary_sensor/gpio`
- :doc:`/components/sensor/template`

5
guides/automations.rst
View File

@ -330,7 +330,8 @@ All Triggers
- :ref:`light.on_turn_on / light.on_turn_off <light-on_turn_on_off_trigger>`
- :ref:`logger.on_message <logger-on_message>`
- :ref:`time.on_time <time-on_time>` / - :ref:`time.on_time_sync <time-on_time_sync>`
- :ref:`mqtt.on_message <mqtt-on_message>` / :ref:`mqtt.on_json_message <mqtt-on_json_message>`
- :ref:`mqtt.on_message <mqtt-on_message>` / :ref:`mqtt.on_json_message <mqtt-on_json_message>` /
:ref:`mqtt.on_connect / mqtt.on_disconnect <mqtt-on_connect_disconnect>`
- :ref:`pn532.on_tag <pn532-on_tag>` / :ref:`rdm6300.on_tag <rdm6300-on_tag>`
- :ref:`interval.interval <interval>`
- :ref:`switch.on_turn_on / switch.on_turn_off <switch-on_turn_on_off_trigger>`
@ -391,6 +392,8 @@ All Actions
- :ref:`pzemac.reset_energy <pzemac-reset_energy_action>`
- :ref:`number.set <number-set_action>` / :ref:`number.to_min <number-to-min_action>` / :ref:`number.to_max <number-to-max_action>` / :ref:`number.decrement <number-decrement_action>` / :ref:`number.increment <number-increment_action>` / :ref:`number.operation <number-operation_action>`
- :ref:`select.set <select-set_action>` / :ref:`select.set_index <select-set_index_action>` / :ref:`select.first <select-first_action>` / :ref:`select.last <select-last_action>` / :ref:`select.previous <select-previous_action>` / :ref:`select.next <select-next_action>` / :ref:`select.operation <select-operation_action>`
- :ref:`media_player.play <media_player-play>` / :ref:`media_player.pause <media_player-pause>` / :ref:`media_player.stop <media_player-stop>` / :ref:`media_player.toggle <media_player-toggle>`
/ :ref:`media_player.volume_up <media_player-volume_up>` / :ref:`media_player.volume_down <media_player-volume_down>` / :ref:`media_player.volume_set <media_player-volume_set>`
.. _config-condition:

35
guides/faq.rst
View File

@ -13,6 +13,41 @@ Tips for using ESPHome
``!include`` and ``!secret``. So you can store all your secret WiFi passwords and so on
in a file called ``secrets.yaml`` within the directory where the configuration file is.
An enhancement to Home Assistant's ``!include`` accepts a list of variables that can be
substituted within the included file.
.. code-block:: yaml
binary_sensor:
- platform: gpio
id: button1
pin: GPIO16
on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax
- platform: gpio
id: button2
pin: GPIO4
on_multi_click: !include
# multi-line syntax
file: on-multi-click.yaml
vars:
id: 2
``on-multi-click.yaml``:
.. code-block:: yaml
- timing: !include click-single.yaml
then:
- mqtt.publish:
topic: ${device_name}/button${id}/status
payload: single
- timing: !include click-double.yaml
then:
- mqtt.publish:
topic: ${device_name}/button${id}/status
payload: double
For even more configuration templating, take a look at :ref:`config-substitutions`.
2. If you want to see how ESPHome interprets your configuration, run

25
guides/supporters.rst
View File

@ -132,6 +132,7 @@ Contributors
- `cbialobos (@cbialobos) <https://github.com/cbialobos>`__
- `Ciprian Constantinescu (@cciprian5) <https://github.com/cciprian5>`__
- `Marco (@cdrfun) <https://github.com/cdrfun>`__
- `Cellie (@CelliesProjects) <https://github.com/CelliesProjects>`__
- `Kostas Chatzikokolakis (@chatziko) <https://github.com/chatziko>`__
- `chris-jennings (@chris-jennings) <https://github.com/chris-jennings>`__
- `Christian Taedcke (@chrta) <https://github.com/chrta>`__
@ -203,6 +204,7 @@ Contributors
- `Mark (@Diramu) <https://github.com/Diramu>`__
- `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>`__
@ -242,6 +244,7 @@ Contributors
- `EmbeddedDevver (@EmbeddedDevver) <https://github.com/EmbeddedDevver>`__
- `EmmanuelLM (@EmmanuelLM) <https://github.com/EmmanuelLM>`__
- `Emory Dunn (@emorydunn) <https://github.com/emorydunn>`__
- `Eric van Blokland (@Emrvb) <https://github.com/Emrvb>`__
- `Eric Muehlstein (@emuehlstein) <https://github.com/emuehlstein>`__
- `Anders Persson (@emwap) <https://github.com/emwap>`__
- `Bert (@Engelbert) <https://github.com/Engelbert>`__
@ -272,6 +275,7 @@ Contributors
- `Francis-labo (@Francis-labo) <https://github.com/Francis-labo>`__
- `Francisk0 (@Francisk0) <https://github.com/Francisk0>`__
- `Frank Bakker (@FrankBakkerNl) <https://github.com/FrankBakkerNl>`__
- `Frank (@FrankBoesing) <https://github.com/FrankBoesing>`__
- `Frank Langtind (@frankiboy1) <https://github.com/frankiboy1>`__
- `Frankster-NL (@Frankster-NL) <https://github.com/Frankster-NL>`__
- `Fredrik Erlandsson (@fredrike) <https://github.com/fredrike>`__
@ -358,9 +362,11 @@ Contributors
- `James Braid (@jamesbraid) <https://github.com/jamesbraid>`__
- `James Duke (@jamesduke) <https://github.com/jamesduke>`__
- `James Gao (@jamesgao) <https://github.com/jamesgao>`__
- `Jan Grewe (@jangrewe) <https://github.com/jangrewe>`__
- `János Rusiczki (@janosrusiczki) <https://github.com/janosrusiczki>`__
- `Jan Pieper (@janpieper) <https://github.com/janpieper>`__
- `Jarek.P (@JaroslawPrzybyl) <https://github.com/JaroslawPrzybyl>`__
- `Jason-nz (@Jason-nz) <https://github.com/Jason-nz>`__
- `Jason2866 (@Jason2866) <https://github.com/Jason2866>`__
- `Jason Hines (@jasonehines) <https://github.com/jasonehines>`__
- `JasperPlant (@JasperPlant) <https://github.com/JasperPlant>`__
@ -384,6 +390,7 @@ Contributors
- `Yuval Brik (@jhamhader) <https://github.com/jhamhader>`__
- `Joe (@jhansche) <https://github.com/jhansche>`__
- `Jim Bauwens (@jimbauwens) <https://github.com/jimbauwens>`__
- `jimtng (@jimtng) <https://github.com/jimtng>`__
- `Jérémy JOURDIN (@JJK801) <https://github.com/JJK801>`__
- `Jonathan Jefferies (@jjok) <https://github.com/jjok>`__
- `John K. Luebs (@jkl1337) <https://github.com/jkl1337>`__
@ -455,6 +462,7 @@ Contributors
- `Luca Gugelmann (@lgugelmann) <https://github.com/lgugelmann>`__
- `Lubos Horacek (@lhoracek) <https://github.com/lhoracek>`__
- `Juraj Liso (@LiJu09) <https://github.com/LiJu09>`__
- `lingex (@lingex) <https://github.com/lingex>`__
- `Lazar Obradovic (@lobradov) <https://github.com/lobradov>`__
- `Barry Loong (@loongyh) <https://github.com/loongyh>`__
- `LuBeDa (@lubeda) <https://github.com/lubeda>`__
@ -468,6 +476,7 @@ Contributors
- `Alex Peters (@Lx) <https://github.com/Lx>`__
- `Michael Klamminger (@m1ch) <https://github.com/m1ch>`__
- `M95D (@M95D) <https://github.com/M95D>`__
- `maaadc (@maaadc) <https://github.com/maaadc>`__
- `Marc-Antoine Courteau (@macourteau) <https://github.com/macourteau>`__
- `Massimiliano Ravelli (@madron) <https://github.com/madron>`__
- `Alexandre-Jacques St-Jacques (@Maelstrom96) <https://github.com/Maelstrom96>`__
@ -554,6 +563,7 @@ Contributors
- `Kevin Uhlir (@n0bel) <https://github.com/n0bel>`__
- `Erik Näsström (@Naesstrom) <https://github.com/Naesstrom>`__
- `H. Árkosi Róbert (@nagyrobi) <https://github.com/nagyrobi>`__
- `Viktor Nagy (@nagyv) <https://github.com/nagyv>`__
- `Oskar Napieraj (@napieraj) <https://github.com/napieraj>`__
- `Nate Lust (@natelust) <https://github.com/natelust>`__
- `ueno (@nayuta-ueno) <https://github.com/nayuta-ueno>`__
@ -677,6 +687,7 @@ Contributors
- `Robert Alfaro (@robert-alfaro) <https://github.com/robert-alfaro>`__
- `Rob Gridley (@robgridley) <https://github.com/robgridley>`__
- `Robin Smidsrød (@robinsmidsrod) <https://github.com/robinsmidsrod>`__
- `RoboMagus (@RoboMagus) <https://github.com/RoboMagus>`__
- `RockBomber (@RockBomber) <https://github.com/RockBomber>`__
- `RoganDawes (@RoganDawes) <https://github.com/RoganDawes>`__
- `Roi Tagar (@roitagar) <https://github.com/roitagar>`__
@ -699,7 +710,9 @@ Contributors
- `Jan Čermák (@sairon) <https://github.com/sairon>`__
- `sascha lammers (@sascha432) <https://github.com/sascha432>`__
- `Nils Schulte (@Schnilz) <https://github.com/Schnilz>`__
- `Wolle (@schreibfaul1) <https://github.com/schreibfaul1>`__
- `Ville Skyttä (@scop) <https://github.com/scop>`__
- `Stefan Seyfried (@seife) <https://github.com/seife>`__
- `sekkr1 (@sekkr1) <https://github.com/sekkr1>`__
- `SenexCrenshaw (@SenexCrenshaw) <https://github.com/SenexCrenshaw>`__
- `Sergio (@sergio303) <https://github.com/sergio303>`__
@ -742,6 +755,7 @@ Contributors
- `Sympatron GmbH (@Sympatron) <https://github.com/Sympatron>`__
- `synco (@synco) <https://github.com/synco>`__
- `Marcel Feix (@Syndlex) <https://github.com/Syndlex>`__
- `SyXavier (@SyXavier) <https://github.com/SyXavier>`__
- `Teemu Mikkonen (@T3m3z) <https://github.com/T3m3z>`__
- `Taigar2015 (@Taigar2015) <https://github.com/Taigar2015>`__
- `Levente Tamas (@tamisoft) <https://github.com/tamisoft>`__
@ -753,6 +767,7 @@ Contributors
- `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>`__
- `thejonesyboy (@thejonesyboy) <https://github.com/thejonesyboy>`__
- `TheJulianJES (@TheJulianJES) <https://github.com/TheJulianJES>`__
@ -776,6 +791,7 @@ Contributors
- `TomFahey (@TomFahey) <https://github.com/TomFahey>`__
- `tomlut (@tomlut) <https://github.com/tomlut>`__
- `Tom Matheussen (@Tommatheussen) <https://github.com/Tommatheussen>`__
- `tomle (@tomole444) <https://github.com/tomole444>`__
- `Tom Price (@tomtom5152) <https://github.com/tomtom5152>`__
- `tony (@tony-fav) <https://github.com/tony-fav>`__
- `David Kiliani (@torfbolt) <https://github.com/torfbolt>`__
@ -797,14 +813,13 @@ Contributors
- `Tyler Menezes (@tylermenezes) <https://github.com/tylermenezes>`__
- `ukewea (@ukewea) <https://github.com/ukewea>`__
- `Unai (@unaiur) <https://github.com/unaiur>`__
- `user897943 (@user897943) <https://github.com/user897943>`__
- `UT2UH (@UT2UH) <https://github.com/UT2UH>`__
- `Vc (@Valcob) <https://github.com/Valcob>`__
- `Nad (@valordk) <https://github.com/valordk>`__
- `André Lademann (@vergissberlin) <https://github.com/vergissberlin>`__
- `Víctor Ferrer García (@vicfergar) <https://github.com/vicfergar>`__
- `Vincèn (@vincegre) <https://github.com/vincegre>`__
- `VitaliyKurokhtin (@VitaliyKurokhtin) <https://github.com/VitaliyKurokhtin>`__
- `voibit (@voibit) <https://github.com/voibit>`__
- `Xuming Feng (@voicevon) <https://github.com/voicevon>`__
- `vxider (@Vxider) <https://github.com/Vxider>`__
- `WallyCZ (@WallyCZ) <https://github.com/WallyCZ>`__
@ -824,17 +839,15 @@ Contributors
- `Rick van Hattem (@WoLpH) <https://github.com/WoLpH>`__
- `workingmanrob (@workingmanrob) <https://github.com/workingmanrob>`__
- `Wojtek Strzalka (@wstrzalka) <https://github.com/wstrzalka>`__
- `Wolfgang Tremmel (@wtremmel) <https://github.com/wtremmel>`__
- `Wumpf (@Wumpf) <https://github.com/Wumpf>`__
- `wysiwyng (@wysiwyng) <https://github.com/wysiwyng>`__
- `Mike (@xsnoopy) <https://github.com/xsnoopy>`__
- `Yaroslav (@Yarikx) <https://github.com/Yarikx>`__
- `Marcin Jaworski (@yawor) <https://github.com/yawor>`__
- `ychieux (@ychieux) <https://github.com/ychieux>`__
- `Pavel (@yekm) <https://github.com/yekm>`__
- `Atsuko Ito (@yottatsa) <https://github.com/yottatsa>`__
- `Nico B (@youknow0) <https://github.com/youknow0>`__
- `Yuval Aboulafia (@yuvalabou) <https://github.com/yuvalabou>`__
- `zaluthar (@zaluthar) <https://github.com/zaluthar>`__
- `david reid (@zathras777) <https://github.com/zathras777>`__
- `Zebble (@Zebble) <https://github.com/Zebble>`__
- `ZJY (@zhangjingye03) <https://github.com/zhangjingye03>`__
@ -843,4 +856,4 @@ Contributors
- `Michael Labuschke (@zigman79) <https://github.com/zigman79>`__
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
*This page was last updated May 24, 2022.*
*This page was last updated June 16, 2022.*

1
images/i2s_audio.svg Normal file
View File

@ -0,0 +1 @@
<svg width="527.266" height="25mm" viewBox="0 0 139.506 25" xmlns="http://www.w3.org/2000/svg"><path style="fill:#000;fill-opacity:1;stroke-width:.133497;stroke-miterlimit:4;stroke-dasharray:none" d="M5 0h129.506c2.77 0 5 2.23 5 5v15c0 2.77-2.23 5-5 5H5c-2.77 0-5-2.23-5-5V5c0-2.77 2.23-5 5-5Z"/><g aria-label="I2S AUDIO" style="font-size:10.5833px;line-height:1.25;letter-spacing:1.08479px;fill:#fffffc;stroke-width:.264583"><path d="M10.138 20.666H6.48V4.86h3.658ZM18.99 17.685h6.796v2.98H13.842v-2.37l6.096-5.757q.97-.926 1.31-1.58.338-.678.338-1.333 0-.948-.655-1.445-.632-.52-1.874-.52-1.038 0-1.874.407-.835.384-1.4 1.174L13.12 7.525q.926-1.377 2.552-2.144 1.625-.79 3.725-.79 1.761 0 3.07.586 1.333.565 2.055 1.626.745 1.039.745 2.46 0 1.288-.542 2.417-.542 1.129-2.1 2.574zM34.57 20.937q-1.875 0-3.636-.497-1.738-.52-2.8-1.332l1.242-2.755q1.016.745 2.416 1.197 1.4.452 2.8.452 1.558 0 2.303-.452.745-.474.745-1.242 0-.564-.452-.926-.429-.383-1.129-.61-.677-.225-1.85-.496-1.807-.429-2.959-.858-1.151-.429-1.986-1.377-.813-.948-.813-2.529 0-1.377.745-2.483.745-1.13 2.235-1.784 1.513-.655 3.68-.655 1.513 0 2.958.362 1.445.36 2.529 1.038l-1.13 2.777q-2.19-1.242-4.38-1.242-1.535 0-2.28.497-.722.497-.722 1.31 0 .812.835 1.219.858.384 2.597.767 1.806.43 2.957.858 1.152.43 1.965 1.355.835.926.835 2.506 0 1.355-.768 2.484-.745 1.106-2.257 1.76-1.513.656-3.68.656zM67.987 20.666h-3.839l-1.4-3.387h-7.337l-1.4 3.387h-3.748L57.307 4.86h3.613zM59.09 8.45l-2.506 6.051h5.012zM77.403 20.937q-3.387 0-5.284-1.874-1.874-1.874-1.874-5.351v-8.85h3.658v8.714q0 4.245 3.522 4.245 1.716 0 2.62-1.016.902-1.039.902-3.229V4.861h3.613v8.85q0 3.478-1.897 5.352-1.874 1.874-5.26 1.874zM89.257 20.666V4.86h7.18q2.574 0 4.538.994 1.987.97 3.07 2.754 1.107 1.784 1.107 4.154 0 2.371-1.107 4.155-1.083 1.783-3.07 2.777-1.964.97-4.538.97zm7-3.003q2.37 0 3.77-1.31 1.422-1.332 1.422-3.59 0-2.257-1.422-3.567-1.4-1.332-3.77-1.332h-3.342v9.799zM112.649 20.666h-3.658V4.86h3.658zM125.135 20.937q-2.46 0-4.448-1.062-1.964-1.06-3.093-2.912-1.106-1.874-1.106-4.2 0-2.325 1.106-4.176 1.13-1.874 3.093-2.936 1.987-1.06 4.448-1.06 2.461 0 4.426 1.06 1.964 1.062 3.093 2.936 1.129 1.851 1.129 4.176 0 2.326-1.13 4.2-1.128 1.851-3.092 2.912-1.965 1.062-4.426 1.062zm0-3.116q1.4 0 2.529-.632 1.129-.655 1.761-1.807.655-1.151.655-2.619 0-1.467-.655-2.619-.632-1.151-1.761-1.783-1.129-.655-2.529-.655t-2.528.655q-1.13.632-1.784 1.783-.632 1.152-.632 2.62 0 1.467.632 2.618.655 1.152 1.784 1.807 1.128.632 2.528.632z" style="font-weight:700;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat, Bold'"/></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.6 KiB

11
index.rst
View File

@ -195,7 +195,7 @@ Air Quality
SCD30, components/sensor/scd30, scd30.jpg, CO2 & Temperature & Humidity
SCD4X, components/sensor/scd4x, scd4x.jpg, CO2 & Temperature & Humidity
SGP30, components/sensor/sgp30, sgp30.jpg, CO2 & Volatile organics
SGP40, components/sensor/sgp40, sgp40.jpg, Volatile organics
SGP4x, components/sensor/sgp4x, sgp40.jpg, Volatile organics and NOx
SM300D2, components/sensor/sm300d2, sm300d2.jpg, Air quality
SPS30, components/sensor/sps30, sps30.jpg, Particulate
T6613/15, components/sensor/t6615, t6615.jpg, CO2
@ -620,6 +620,7 @@ Select Components
Select Core, components/select/index, folder-open.svg
Template Select, components/select/template, description.svg
Modbus Select, components/select/modbus_controller, modbus.png
Tuya Select, components/select/tuya, tuya.png
Lock Components
-----------------
@ -630,6 +631,14 @@ Lock Components
Generic Output Lock, components/lock/output, upload.svg
Template Lock, components/lock/template, description.svg
Media Player Components
-----------------------
.. imgtable::
Media Player Core, components/media_player/index, folder-open.svg
I2S Audio, components/media_player/i2s_audio, i2s_audio.svg
Misc Components
---------------