diff --git a/Doxygen b/Doxygen
index 0a46d698b..2bac0a704 100644
--- a/Doxygen
+++ b/Doxygen
@@ -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 = 2023.3.2
+PROJECT_NUMBER = 2023.4.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
diff --git a/Makefile b/Makefile
index bb91407df..3b07c9333 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2023.3.2
+ESPHOME_REF = 2023.4.0
.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
diff --git a/_static/changelog-2023.4.0.png b/_static/changelog-2023.4.0.png
new file mode 100644
index 000000000..38b113300
Binary files /dev/null and b/_static/changelog-2023.4.0.png differ
diff --git a/_static/version b/_static/version
index 745496025..b0db10dad 100644
--- a/_static/version
+++ b/_static/version
@@ -1 +1 @@
-2023.3.2
\ No newline at end of file
+2023.4.0
\ No newline at end of file
diff --git a/changelog/2023.4.0.rst b/changelog/2023.4.0.rst
new file mode 100644
index 000000000..d97260feb
--- /dev/null
+++ b/changelog/2023.4.0.rst
@@ -0,0 +1,241 @@
+ESPHome 2023.4.0 - 19th April 2023
+==================================
+
+.. seo::
+ :description: Changelog for ESPHome 2023.4.0.
+ :image: /_static/changelog-2023.4.0.png
+ :author: Jesse Hills
+ :author_twitter: @jesserockz
+
+.. imgtable::
+ :columns: 3
+
+ Voice Assistant, components/voice_assistant, voice-assistant.svg
+ Microphone Core, components/microphone/index, microphone.svg
+ I2S Microphone, components/microphone/i2s_audio, i2s_audio.svg
+ MMC5603, components/sensor/mmc5603, mmc5603.jpg
+ KSZ8081 Ethernet, components/ethernet, ethernet.svg
+
+
+Voice Assistant
+---------------
+
+This year is the Year of the Voice for Home Assistant, and ESPHome is charging ahead with this in mind.
+We've added a new :doc:`/components/voice_assistant` component that allows you to use ESPHome devices as an input
+for `assist `__ in Home Assistant.
+
+With this also comes preliminary :doc:`microphone ` support, which has been built in a way that multiple
+components, like ``voice_assistant`` can request start / stop of the microphone and get the data. We
+hope this leads to more interesting use cases for the microphone in the future.
+
+Home Assistant is hosting a live stream all about the Year of the Voice - Chapter 2.
+
+.. raw:: html
+
+
+
+
+Keith joins Nabu Casa
+---------------------
+
+Nabu Casa is pleased to annouce that long time contributor Keith Burzinski (:ghuser:`kbx81`) is joining the
+team as a full time developer to help out on ESPHome.
+
+Breaking Changes
+----------------
+
+I²S Media Player
+^^^^^^^^^^^^^^^^
+
+With the introduction of the :doc:`/components/microphone/i2s_audio`, the media player platform has some
+required breaking changes to the YAML configuration. This involves moving the ``i2s_lrclk_pin`` and
+``i2s_bclk_pin`` to a new :doc:`/components/i2s_audio` component.
+
+.. code-block:: yaml
+
+ # Before
+ media_player:
+ - platform: i2s_audio
+ name: ESPHome I2S Media Player
+ dac_type: external
+ i2s_lrclk_pin: GPIO33
+ i2s_bclk_pin: GPIO19
+ i2s_dout_pin: GPIO22
+ mode: mono
+
+ # After
+ i2s_audio:
+ i2s_lrclk_pin: GPIO33
+ i2s_bclk_pin: GPIO19
+
+ media_player:
+ - platform: i2s_audio
+ name: ESPHome I2S Media Player
+ dac_type: external
+ i2s_dout_pin: GPIO22
+ mode: mono
+
+Default restore mode for Switches, Fans and Lights
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The default ``restore_mode`` for switches, fans and lights has been changed
+from ``RESTORE_DEFAULT_OFF`` to ``ALWAYS_OFF`` with the intention that restoring values
+from flash should be manually specified by a user if desired in their YAML configuration.
+
+Number ``step``
+^^^^^^^^^^^^^^^
+
+The ``number`` components have always internally set a ``step`` required in config,
+but allowed it to be not specified at all. This caused issues on the Home Assistant side
+of things. This is only a breaking change for external components that have a ``number`` platform.
+
+UART ids
+^^^^^^^^
+
+Due to ``uart0`` / ``uart1`` / ``uart2`` being defined in some of the platform code ESPHome uses,
+ESPHome will now disallow these ids from being used in the config. You can simply change them to
+``uart_0`` to continue using.
+
+Full list of changes
+--------------------
+
+New Components
+^^^^^^^^^^^^^^
+
+- Added in mmc5603 code :esphomepr:`4175` by :ghuser:`benhoff` (new-integration)
+- Add push to talk voice assistant :esphomepr:`4648` by :ghuser:`jesserockz` (new-integration)
+
+Breaking Changes
+^^^^^^^^^^^^^^^^
+
+- Disallow uart0/1/2 as ids in config :esphomepr:`4446` by :ghuser:`jesserockz` (breaking-change)
+- Require step to be set when calling register_number :esphomepr:`4622` by :ghuser:`jesserockz` (breaking-change)
+- Fix restore :esphomepr:`4655` by :ghuser:`spacemanspiff2007` (breaking-change)
+
+Beta Changes
+^^^^^^^^^^^^
+
+- debug component, allow without debug logging :esphomepr:`4685` by :ghuser:`jesserockz`
+- Fixed dns2 for ethernet :esphomepr:`4698` by :ghuser:`HeMan`
+- Add timeout to i2c write error logs :esphomepr:`4697` by :ghuser:`Szewcson`
+- Add event triggers to voice_assistant :esphomepr:`4699` by :ghuser:`jesserockz`
+- Call on_error if no api client connected that handles voice :esphomepr:`4709` by :ghuser:`jesserockz`
+- Add ethernet powerdown (fixes esphome/issues#4420) :esphomepr:`4706` by :ghuser:`tracestep`
+- Bump arduino platform version to 5.3.0 :esphomepr:`4713` by :ghuser:`jesserockz`
+
+All changes
+^^^^^^^^^^^
+
+- Mark unique_id() virtual method as deprecated :esphomepr:`4538` by :ghuser:`oxan`
+- Drop deprecated entity property base methods :esphomepr:`4539` by :ghuser:`oxan`
+- Format test files :esphomepr:`4541` by :ghuser:`jesserockz`
+- EntityBase: Icon string can stay in flash. :esphomepr:`4566` by :ghuser:`Fabian-Schmidt`
+- Update the delta filter to be able to take a percentage change :esphomepr:`4391` by :ghuser:`TrentHouliston`
+- Added missing PM_1_0 and PM_10_0 for PMS5003T and PMS5003ST :esphomepr:`4560` by :ghuser:`genestealer`
+- Add an option to force SPI into software mode :esphomepr:`4556` by :ghuser:`wupeka`
+- allow using a binary output for the status led :esphomepr:`4532` by :ghuser:`ssieb`
+- Add option flip_x :esphomepr:`4555` by :ghuser:`rafal83`
+- Bump aioesphomeapi from 13.5.0 to 13.5.1 :esphomepr:`4572` by :ghuser:`dependabot[bot]`
+- Verbose output of define. :esphomepr:`4576` by :ghuser:`Fabian-Schmidt`
+- Add support for ESP32 CAM 3MP and 5MP resolutions and arbitrary camera clock. :esphomepr:`4580` by :ghuser:`peterhalicky`
+- Add a simple 'skip_initial' filter :esphomepr:`4582` by :ghuser:`sybrenstuvel`
+- Fix outdated filter string in platformio_api :esphomepr:`4587` by :ghuser:`LordMike`
+- Split test3.yaml :esphomepr:`4591` by :ghuser:`jesserockz`
+- Disallow uart0/1/2 as ids in config :esphomepr:`4446` by :ghuser:`jesserockz` (breaking-change)
+- Upgrade clang-format to v13 :esphomepr:`4535` by :ghuser:`oxan`
+- B/W support for GooDisplay GDEY029T94 (as used on Adafruit MagTag) :esphomepr:`4222` by :ghuser:`AaronJackson`
+- Fix negative sqrt root in ct_clamp_sensor.cpp :esphomepr:`4236` by :ghuser:`jerome992`
+- Wrap ipv6 code a bit more :esphomepr:`4574` by :ghuser:`jesserockz`
+- Remove EntityBase from sprinkler :esphomepr:`4606` by :ghuser:`jesserockz`
+- Fix wrong port multiplexer name in dump GPIO function of sx1509 :esphomepr:`4592` by :ghuser:`skaldo`
+- Bump zeroconf from 0.47.3 to 0.47.4 :esphomepr:`4597` by :ghuser:`dependabot[bot]`
+- Bump pytest-asyncio from 0.20.3 to 0.21.0 :esphomepr:`4599` by :ghuser:`dependabot[bot]`
+- Limit range on filter time period for remote_receiver :esphomepr:`4604` by :ghuser:`RoboMagus`
+- add select_schema to select component :esphomepr:`4545` by :ghuser:`regevbr`
+- Add ability to clear the gatt cache :esphomepr:`4621` by :ghuser:`bdraco`
+- Bump actions/stale from 7 to 8 :esphomepr:`4615` by :ghuser:`dependabot[bot]`
+- Require step to be set when calling register_number :esphomepr:`4622` by :ghuser:`jesserockz` (breaking-change)
+- Lower range of CONF_FREQUENCY :esphomepr:`4619` by :ghuser:`berendhaan`
+- Allow entity names to be set to None :esphomepr:`4607` by :ghuser:`jesserockz`
+- Fix platform restriction for bme680_bsec :esphomepr:`4616` by :ghuser:`jesserockz`
+- Fix EzoCommandType enum :esphomepr:`4593` by :ghuser:`alfredopironti`
+- `EntityBase` Name can stay in flash. :esphomepr:`4594` by :ghuser:`Fabian-Schmidt`
+- feat: Add support to unsubscribe from BLE advertisements :esphomepr:`4620` by :ghuser:`richardhopton`
+- EntityBase: Move ObjectId to Flash :esphomepr:`4569` by :ghuser:`Fabian-Schmidt`
+- Add workflow to sync device classes with HA dev :esphomepr:`4629` by :ghuser:`jesserockz`
+- Synchronise Device Classes from Home Assistant :esphomepr:`4633` by :ghuser:`github-actions[bot]`
+- Remove AUTO_LOAD from as3935 :esphomepr:`4630` by :ghuser:`jesserockz`
+- Add ifdef to new bt proxy unsubscribe :esphomepr:`4634` by :ghuser:`jesserockz`
+- add bluetooth mac address in dump_config() :esphomepr:`4628` by :ghuser:`felixlungu`
+- Binary map bugfixes :esphomepr:`4636` by :ghuser:`kahrendt`
+- entity_base avoid padding bytes. :esphomepr:`4637` by :ghuser:`Fabian-Schmidt`
+- Avoid sensor padding. :esphomepr:`4638` by :ghuser:`Fabian-Schmidt`
+- Support advanced UART customization :esphomepr:`4465` by :ghuser:`Fabian-Schmidt`
+- Log calibration results at level INFO :esphomepr:`4240` by :ghuser:`Duckle29`
+- Number step not optional :esphomepr:`4649` by :ghuser:`RoboMagus`
+- VSCode / devcontainer updates :esphomepr:`4647` by :ghuser:`jesserockz`
+- Retry PN532_COMMAND_VERSION_DATA on setup() (fixes esphome/issues#3823) :esphomepr:`4651` by :ghuser:`tracestep`
+- Bump pylint from 2.16.4 to 2.17.2 :esphomepr:`4650` by :ghuser:`dependabot[bot]`
+- Bump black from 23.1.0 to 23.3.0 :esphomepr:`4635` by :ghuser:`dependabot[bot]`
+- Added in mmc5603 code :esphomepr:`4175` by :ghuser:`benhoff` (new-integration)
+- fix compilation with latest esp-idf :esphomepr:`4671` by :ghuser:`Mic92`
+- Bump zeroconf from 0.47.4 to 0.56.0 :esphomepr:`4674` by :ghuser:`dependabot[bot]`
+- Bump pytest from 7.2.2 to 7.3.0 :esphomepr:`4673` by :ghuser:`dependabot[bot]`
+- Add push to talk voice assistant :esphomepr:`4648` by :ghuser:`jesserockz` (new-integration)
+- Fix ESP32 SPI hardware assignment in Arduino fw :esphomepr:`4669` by :ghuser:`kbx81`
+- Fix some NFC/PN532 crashes :esphomepr:`4678` by :ghuser:`kbx81`
+- Add support for SSD1306 72x40 displays :esphomepr:`4659` by :ghuser:`johnsto`
+- Fix pin schema for i2s microphone :esphomepr:`4680` by :ghuser:`jesserockz`
+- Fix BedJet setup priority [fixes esphome/issues#3807] :esphomepr:`4677` by :ghuser:`jhansche`
+- Add always trigger stop :esphomepr:`4249` by :ghuser:`X-Ryl669`
+- Fix graph limits for negative values and other corner cases :esphomepr:`4253` by :ghuser:`unhold`
+- Fix cut-off on 2.13" waveshare/ttgo epaper displays :esphomepr:`4255` by :ghuser:`unhold`
+- [Ethernet] Add PHY KSZ8081 support :esphomepr:`4668` by :ghuser:`Fabian-Schmidt`
+- Fix restore :esphomepr:`4655` by :ghuser:`spacemanspiff2007` (breaking-change)
+- debug component, allow without debug logging :esphomepr:`4685` by :ghuser:`jesserockz`
+- Fixed dns2 for ethernet :esphomepr:`4698` by :ghuser:`HeMan`
+- Add timeout to i2c write error logs :esphomepr:`4697` by :ghuser:`Szewcson`
+- Add event triggers to voice_assistant :esphomepr:`4699` by :ghuser:`jesserockz`
+- Call on_error if no api client connected that handles voice :esphomepr:`4709` by :ghuser:`jesserockz`
+- Add ethernet powerdown (fixes esphome/issues#4420) :esphomepr:`4706` by :ghuser:`tracestep`
+- Bump arduino platform version to 5.3.0 :esphomepr:`4713` by :ghuser:`jesserockz`
+
+Past Changelogs
+---------------
+
+- :doc:`2023.3.0`
+- :doc:`2023.2.0`
+- :doc:`2022.12.0`
+- :doc:`2022.11.0`
+- :doc:`2022.10.0`
+- :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`
diff --git a/changelog/index.rst b/changelog/index.rst
index 697efc4d3..432d05582 100644
--- a/changelog/index.rst
+++ b/changelog/index.rst
@@ -2,7 +2,7 @@ Changelog
=========
.. redirect::
- :url: /changelog/2023.3.0.html
+ :url: /changelog/2023.4.0.html
.. toctree::
:glob:
diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst
index 8dd0a8870..1f87eb7ea 100644
--- a/components/binary_sensor/index.rst
+++ b/components/binary_sensor/index.rst
@@ -27,6 +27,13 @@ you can always override it.
Configuration variables:
+- **name** (**Required**, string): The name for the binary sensor.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the binary sensor to use that name, you can set ``name: None``.
+
- **device_class** (*Optional*, string): The device class for the
sensor. See https://developers.home-assistant.io/docs/core/entity/binary-sensor/#available-device-classes
for a list of available options.
diff --git a/components/button/index.rst b/components/button/index.rst
index c91b1fac8..330ef4852 100644
--- a/components/button/index.rst
+++ b/components/button/index.rst
@@ -41,6 +41,12 @@ All buttons in ESPHome have a name and an optional icon.
Configuration variables:
- **name** (**Required**, string): The name for the button.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the button to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the button 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
diff --git a/components/climate/index.rst b/components/climate/index.rst
index 3b57936e3..ceebe2525 100644
--- a/components/climate/index.rst
+++ b/components/climate/index.rst
@@ -33,6 +33,13 @@ All climate platforms in ESPHome inherit from the climate configuration schema.
Configuration variables:
+- **name** (**Required**, string): The name of the climate device.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the climate to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the climate device in the frontend.
- **visual** (*Optional*): Visual settings for the climate device - these do not
affect operation and are solely for controlling how the climate device shows up in the
diff --git a/components/cover/index.rst b/components/cover/index.rst
index 4e1170faa..d6eaeff3b 100644
--- a/components/cover/index.rst
+++ b/components/cover/index.rst
@@ -28,6 +28,13 @@ All cover config schemas inherit from this schema - you can set these keys for c
Configuration variables:
+- **name** (**Required**, string): The name for the cover.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the cover to use that name, you can set ``name: None``.
+
- **device_class** (*Optional*, string): The device class for the
sensor. See https://www.home-assistant.io/components/cover/ for a list of available options.
- **icon** (*Optional*, icon): Manually set the icon to use for the cover in the frontend.
diff --git a/components/cover/time_based.rst b/components/cover/time_based.rst
index e5b321713..0f5e542dd 100644
--- a/components/cover/time_based.rst
+++ b/components/cover/time_based.rst
@@ -52,6 +52,13 @@ Configuration variables:
detectors. In this configuration the ``stop_action`` is not performed when the open or close
time is completed and if the cover is commanded to open or close the corresponding actions
will be performed without checking current state. Defaults to ``false``.
+- **manual_control** (*Optional*, boolean): For covers with manual external controls. With this
+ configuration if the cover is commanded to open or close the corresponding actions will be
+ performed even if the current state fully open or fully closed matches desired state, then
+ ``stop_action`` will be called after the full duration of the action elapses.
+ The current state will then be relearned upon completion.
+ It's recommended to set ``assumed_state`` to true so the cover control button aren't disabled
+ in the interface. Defaults to ``false``.
- **assumed_state** (*Optional*, boolean): Whether the true state of the cover is not known.
This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead
of hiding or disabling one of them. Defaults to ``true``.
diff --git a/components/display/max7219digit.rst b/components/display/max7219digit.rst
index dd4db5f13..2c7923c43 100644
--- a/components/display/max7219digit.rst
+++ b/components/display/max7219digit.rst
@@ -68,6 +68,7 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **num_chip_lines** (*Optional*, int): Number of lines if you want to use the displays in Multiline Mode. Defaults to ``1`` Example: https://github.com/esphome/esphome/pull/1622#issue-836179156
- **chip_lines_style** (*Optional*): How are the lines in Multiline Mode connected? Possible values are ``zigzag`` and ``snake``. Defaults to ``snake``
+- **flip_x** (*Optional*, boolean): Flip the horizontal axis on the screen. Defaults to ``false``.
.. _display-max7219digit_lambda:
diff --git a/components/display/ssd1306.rst b/components/display/ssd1306.rst
index 6733cceb6..6b322309e 100644
--- a/components/display/ssd1306.rst
+++ b/components/display/ssd1306.rst
@@ -51,6 +51,7 @@ Configuration variables:
- ``SSD1306 128x32`` - SSD1306 with 128 columns and 32 rows
- ``SSD1306 128x64``
- ``SSD1306 96x16``
+ - ``SSD1306 72x40``
- ``SSD1306 64x48``
- ``SH1106 128x32``
- ``SH1106 128x64``
@@ -130,6 +131,7 @@ Configuration variables:
- ``SSD1306 128x32`` (SSD1306 with 128 columns and 32 rows)
- ``SSD1306 128x64``
- ``SSD1306 96x16``
+ - ``SSD1306 72x40``
- ``SSD1306 64x48``
- ``SH1106 128x32``
- ``SH1106 128x64``
diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst
index b883d9e53..6eeb9d230 100644
--- a/components/display/waveshare_epaper.rst
+++ b/components/display/waveshare_epaper.rst
@@ -97,6 +97,7 @@ Configuration variables:
- ``7.50inV2`` - Can't use with an ESP8266 as it runs out of RAM
- ``7.50inV2alt`` (alternative version to the above ``7.50inV2``)
- ``7.50in-hd-b`` - Can't use with an ESP8266 as it runs out of RAM
+ - ``gdey029t94`` - GooDisplay GDEY029T94, as used on the AdaFruit MagTag
- **busy_pin** (*Optional*, :ref:`Pin Schema `): The BUSY pin. Defaults to not connected.
- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. Defaults to not connected.
diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst
index 73e402401..8361f0daf 100644
--- a/components/esp32_camera.rst
+++ b/components/esp32_camera.rst
@@ -53,8 +53,8 @@ Connection Options:
- **external_clock** (**Required**): The configuration of the external clock to drive the camera.
- **pin** (**Required**, pin): The pin the external clock line is connected to.
- - **frequency** (*Optional*, float): The frequency of the external clock, must be either 20MHz
- or 10MHz. Defaults to ``20MHz``.
+ - **frequency** (*Optional*, float): The frequency of the external clock, must be between 10
+ and 20MHz. Defaults to ``20MHz``.
- **i2c_pins** (**Required**): The I²C control pins of the camera.
@@ -90,6 +90,15 @@ Image Settings:
- ``1024x768`` (XGA)
- ``1280x1024`` (SXGA)
- ``1600x1200`` (UXGA)
+ - ``1920x1080`` (FHD)
+ - ``720x1280`` (Portrait HD)
+ - ``864x1536`` (Portrait 3MP)
+ - ``2048x1536`` (QXGA)
+ - ``2560x1440`` (QHD)
+ - ``2560x1600`` (WQXGA)
+ - ``1080x1920`` (Portrait FHD)
+ - ``2560x1920`` (QSXGA)
+
- **jpeg_quality** (*Optional*, int): The JPEG quality that the camera should encode images with.
From 10 (best) to 63 (worst). Defaults to ``10``.
diff --git a/components/ethernet.rst b/components/ethernet.rst
index cd49e1308..c6405d9fa 100644
--- a/components/ethernet.rst
+++ b/components/ethernet.rst
@@ -40,6 +40,7 @@ Configuration variables:
- ``DP83848``
- ``IP101``
- ``JL1101``
+ - ``KSZ8081``
- **mdc_pin** (**Required**, :ref:`config-pin`): The MDC pin of the board.
Usually this is ``GPIO23``.
diff --git a/components/fan/index.rst b/components/fan/index.rst
index 1fe4f2b51..c6ffb6493 100644
--- a/components/fan/index.rst
+++ b/components/fan/index.rst
@@ -27,15 +27,21 @@ Base Fan Configuration
Configuration variables:
- **name** (**Required**, string): The name of the fan.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the fan to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the fan in the frontend.
- **restore_mode** (*Optional*): Control how the fan attempts to restore state on boot.
- ``NO_RESTORE`` - Don't restore any state.
- - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore (default).
+ - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore.
- ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON.
- ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF.
- ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON.
- - ``ALWAYS_OFF`` - Always initialize the fan as OFF on bootup.
+ - ``ALWAYS_OFF`` (Default) - Always initialize the fan as OFF on bootup.
- ``ALWAYS_ON`` - Always initialize the fan as ON on bootup.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
diff --git a/components/i2s_audio.rst b/components/i2s_audio.rst
new file mode 100644
index 000000000..f7d59ea7a
--- /dev/null
+++ b/components/i2s_audio.rst
@@ -0,0 +1,29 @@
+I²S Audio Component
+===================
+
+.. seo::
+ :description: Instructions for setting up I²S based devices in ESPHome.
+ :image: i2s_audio.svg
+
+The ``i2s_audio`` component allows for sending and receiving audio via I²S.
+This component only works on ESP32 based chips.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ i2s_audio:
+ i2s_lrclk_pin: GPIO33
+ i2s_bclk_pin: GPIO19
+
+Configuration variables:
+------------------------
+
+- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S LRCLK (Word Select or Left/Right Clock) signal.
+- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S BCLK (Bit Clock) signal.
+
+See also
+--------
+
+- :doc:`microphone/i2s_audio`
+- :doc:`media_player/i2s_audio`
+- :ghedit:`Edit`
diff --git a/components/index.rst b/components/index.rst
index 1b2dd79a2..737a782af 100644
--- a/components/index.rst
+++ b/components/index.rst
@@ -23,5 +23,6 @@ Components
lock/index
display_menu/index
media_player/index
+ microphone/index
time/index
*
diff --git a/components/light/index.rst b/components/light/index.rst
index 6dd4506dd..7c71549c6 100644
--- a/components/light/index.rst
+++ b/components/light/index.rst
@@ -26,6 +26,13 @@ All light configuration schemas inherit these options.
Configuration variables:
+- **name** (**Required**, string): The name of the light.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the light to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the light in the frontend.
- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light.
- **gamma_correct** (*Optional*, float): Apply a `gamma correction
@@ -39,13 +46,13 @@ Configuration variables:
For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the
:doc:`esphome section `.
- - ``RESTORE_DEFAULT_OFF`` (Default) - Attempt to restore state and default to OFF if not possible to restore.
+ - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore.
- ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON.
- ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF.
- ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON.
- ``RESTORE_AND_OFF`` - Attempt to restore state but initialize the light as OFF.
- ``RESTORE_AND_ON`` - Attempt to restore state but initialize the light as ON.
- - ``ALWAYS_OFF`` - Always initialize the light as OFF on bootup.
+ - ``ALWAYS_OFF`` (Default) - Always initialize the light as OFF on bootup.
- ``ALWAYS_ON`` - Always initialize the light as ON on bootup.
- **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform
diff --git a/components/light/status_led.rst b/components/light/status_led.rst
index 93170d9f6..99d1fa52f 100644
--- a/components/light/status_led.rst
+++ b/components/light/status_led.rst
@@ -8,6 +8,7 @@ Status LED Light
The ``status_led`` light platform allows to share a single LED for indicating the status of
the device (when on error/warning state) or as binary light (when on OK state).
This is useful for devices with only one LED available.
+You can also use a binary :ref:`output`.
It provides the combined functionality of :doc:`status_led component ` and a
:doc:`binary light component ` over a single shared GPIO led.
@@ -33,9 +34,10 @@ When the device is in OK state, the LED will be restored to the state of the ``b
Configuration variables:
------------------------
-- **name** (**Required**, string): The name of the light.
-- **pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to operate the LED on.
+- **name** (*Optional*, string): The name of the light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **pin** (*Optional*, :ref:`Pin Schema `): The GPIO pin to operate the LED on.
+- **output** (*Optional*, :ref:`config-id`): The id of the binary :ref:`output` to use for this light.
- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light, though binary lights
only support very few of them.
- All other options from :ref:`Light `.
diff --git a/components/lock/index.rst b/components/lock/index.rst
index 2924e9cf2..0428510cb 100644
--- a/components/lock/index.rst
+++ b/components/lock/index.rst
@@ -6,7 +6,7 @@ Lock Component
:image: folder-open.svg
The ``lock`` domain includes all platforms that should function like a lock
-with lock/unlock actions.
+with lock/unlock actions.
.. note::
@@ -26,6 +26,12 @@ Base Lock Configuration
Configuration variables:
- **name** (**Required**, string): The name of the lock.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the lock to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the
lock in the frontend.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
diff --git a/components/media_player/i2s_audio.rst b/components/media_player/i2s_audio.rst
index 7d01e3bf3..68e8a846e 100644
--- a/components/media_player/i2s_audio.rst
+++ b/components/media_player/i2s_audio.rst
@@ -2,11 +2,11 @@ I2S Audio Media Player
======================
.. seo::
- :description: Instructions for setting up I2S based media players in ESPHome.
+ :description: Instructions for setting up I²S 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.
+via the :doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
.. code-block:: yaml
@@ -15,9 +15,7 @@ via the I2S bus. This platform only works on ESP32 based chips.
- 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:
@@ -33,10 +31,8 @@ Configuration variables:
External DAC
************
-- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S LRCLK (Word Select or Left/Right Clock) signal.
-- **i2s_dout_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S DOUT (Data Out) signal.
-- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S BCLK (Bit Clock) signal.
-- **mode** (*Optional*, string): The mode of the I2S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
+- **i2s_dout_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S DOUT (Data Out) signal.
+- **mode** (*Optional*, string): The mode of the I²S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
For best results, keep the wires as short as possible.
diff --git a/components/media_player/index.rst b/components/media_player/index.rst
index f5b288f84..01a33e595 100644
--- a/components/media_player/index.rst
+++ b/components/media_player/index.rst
@@ -26,6 +26,12 @@ Base Media Player Configuration
Configuration variables:
- **name** (**Required**, string): The name of the media player.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the media player to use that name, you can set ``name: None``.
+
- **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
diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst
new file mode 100644
index 000000000..255cb515a
--- /dev/null
+++ b/components/microphone/i2s_audio.rst
@@ -0,0 +1,29 @@
+I²S Audio Microphone
+====================
+
+.. seo::
+ :description: Instructions for setting up I²S based microphones in ESPHome.
+ :image: i2s_audio.svg
+
+The ``i2s_audio`` microphone platform allows you to receive audio via the the
+:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ microphone:
+ - platform: i2s_audio
+ i2s_din_pin: GPIO23
+
+Configuration variables:
+------------------------
+
+- **i2s_din_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S DIN (Data In) signal.
+
+- All other options from :ref:`Microphone `
+
+See also
+--------
+
+- :doc:`index`
+- :ghedit:`Edit`
diff --git a/components/microphone/index.rst b/components/microphone/index.rst
new file mode 100644
index 000000000..405e98c66
--- /dev/null
+++ b/components/microphone/index.rst
@@ -0,0 +1,109 @@
+Microphone Components
+=====================
+
+.. seo::
+ :description: Instructions for setting up microphones in ESPHome.
+ :image: folder-open.svg
+
+The ``microphone`` domain contains common functionality shared across the
+microphone platforms.
+
+.. _config-microphone:
+
+Base Microphone Configuration
+-----------------------------
+
+Configuration variables:
+
+- **on_data** (*Optional*, :ref:`Automation `): An automation to
+ perform when new data is received.
+
+.. _microphone-actions:
+
+Microphone Actions
+------------------
+
+All ``microphone`` actions can be used without specifying an ``id`` if you have only one ``microphone`` in
+your configuration YAML.
+
+Configuration variables:
+
+**id** (*Optional*, :ref:`config-id`): The microphone to control. Defaults to the only one in YAML.
+
+
+.. _microphone-capture:
+
+``microphone.capture`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will start capturing audio data from the microphone. The data will be passed to any components listening
+and will be available in the ``on_data`` trigger.
+
+.. _microphone-stop_capture:
+
+``microphone.stop_capture`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will stop capturing audio data from the microphone.
+
+
+.. _microphone-triggers:
+
+Microphone Triggers
+-------------------
+
+.. _microphone-on_data:
+
+``microphone.on_data`` Trigger
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This trigger will fire when new data is received from the microphone.
+The data is available as a ``std::vector`` in the variable ``x``.
+
+.. code-block:: yaml
+
+ microphone:
+ - platform: ...
+ on_data:
+ - logger.log:
+ format: "Received %d bytes"
+ args: ['x.size()']
+
+Configuration variables:
+
+- **id** (*Optional*, :ref:`config-id`): The microphone to check. Defaults to the only one in YAML.
+
+
+.. _microphone-conditions:
+
+Microphone Conditions
+---------------------
+
+All ``microphone`` conditions can be used without specifying an ``id`` if you have only one ``microphone`` in
+your configuration YAML.
+
+Configuration variables:
+
+**id** (*Optional*, :ref:`config-id`): The microphone to check. Defaults to the only one in YAML.
+
+.. _microphone-is_capturing:
+
+``microphone.is_capturing`` Condition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This condition will check if the microphone is currently capturing audio data.
+
+
+Platforms
+---------
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+See Also
+--------
+
+- :ghedit:`Edit`
diff --git a/components/number/index.rst b/components/number/index.rst
index 5a6edebe1..34e82cec9 100644
--- a/components/number/index.rst
+++ b/components/number/index.rst
@@ -31,6 +31,12 @@ All numbers in ESPHome have a name and an optional icon.
Configuration variables:
- **name** (**Required**, string): The name for the number.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the number to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the number 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
diff --git a/components/select/index.rst b/components/select/index.rst
index bc5e8dc5d..6d7e84bb8 100644
--- a/components/select/index.rst
+++ b/components/select/index.rst
@@ -31,6 +31,12 @@ All selects in ESPHome have a name and an optional icon.
Configuration variables:
- **name** (**Required**, string): The name for the select.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the select to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the select 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
@@ -334,8 +340,8 @@ advanced stuff (see the full API Reference for more info).
if (id(my_select).has_index(index)) {
ESP_LOGI("main", "Select has index offset %d", index);
}
-
-
+
+
Example
-------
@@ -347,13 +353,13 @@ Setting up three options and set component state to selected option value.
- platform: template
name: Mode
id: mode
- options:
+ options:
- "Option1"
- "Option2"
- "Option3"
initial_option: "OFF"
optimistic: true
- set_action:
+ set_action:
- logger.log:
format: "Chosen option: %s"
args: ["x.c_str()"]
diff --git a/components/sensor/index.rst b/components/sensor/index.rst
index 6ee6f5ded..3b15ff77e 100644
--- a/components/sensor/index.rst
+++ b/components/sensor/index.rst
@@ -40,6 +40,12 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name for the sensor. At least one of **id** and **name** must be specified.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the sensor to use that name, you can set ``name: None``.
+
- **unit_of_measurement** (*Optional*, string): Manually set the unit
of measurement the sensor should advertise its values with. This does
not actually do any maths (conversion between units).
@@ -406,6 +412,21 @@ Configuration variables:
published. With this parameter you can specify when the very first value is to be sent.
Defaults to ``1``.
+``skip_initial``
+****************
+
+A simple skip filter; `skip_initial: N` skips the first `N` sensor readings and passes on the
+rest. This can be used when the sensor needs a few readings to 'warm up'. After the initial
+readings have been skipped, this filter does nothing.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ - platform: wifi_signal
+ # ...
+ filters:
+ - skip_initial: 3
+
``throttle``
************
@@ -456,11 +477,28 @@ values.
``delta``
*********
-This filter stores the last value passed through this filter and only
-passes incoming values through if the absolute difference is greater than the configured
-value. For example if a value of 1.0 first comes in, it's passed on. If the delta filter
-is configured with a value of 5, it will now not pass on an incoming value of 2.0, only values
-that are at least 6.0 big or -4.0.
+This filter stores the last value passed through this filter and only passes incoming values through
+if incoming value is sufficiently different from the previously passed one.
+This difference can be calculated in two ways an absolute difference or a percentage difference.
+
+If a number is specified, it will be used as the absolute difference required.
+For example if the filter were configured with a value of 2 and the last value passed through was 10,
+only values greater than 12 or less than 8 would be passed through.
+
+.. code-block:: yaml
+
+ filters:
+ - delta: 2.0
+
+If a percentage is specified a percentage of the last value will be used as the required difference.
+For example if the filter were configured with a value of 20% and the last value passed through was 10,
+only values greater than 12 or less than 8 would be passed through.
+However, if the last value passed through was 100 only values greater than 120 or less than 80 would be passed through.
+
+.. code-block:: yaml
+
+ filters:
+ - delta: 20%
``or``
******
@@ -643,7 +681,7 @@ From :ref:`lambdas `, you can call several methods on all sensors
advanced stuff (see the full API Reference for more info).
- ``publish_state()``: Manually cause the sensor to push out a value. It will then
- be processed by the sensor filters, and once filtered will propagate though ESPHome and though the API to Home Assistant or out via MQTT if configured.
+ be processed by the sensor filters, and once filtered will propagate though ESPHome and though the API to Home Assistant or out via MQTT if configured.
.. code-block:: cpp
diff --git a/components/sensor/mmc5063.rst b/components/sensor/mmc5063.rst
new file mode 100644
index 000000000..5b18557ba
--- /dev/null
+++ b/components/sensor/mmc5063.rst
@@ -0,0 +1,63 @@
+.. _mmc5603:
+
+MMC5603 Magnetometer
+=====================
+
+.. seo::
+ :description: Instructions for setting up MMC5693 IMU compass sensors.
+ :image: mmc5603.jpg
+ :keywords: MMC5603
+
+The ``mmc5603`` allows you to use your MMC5603 triple-axis magnetometers
+(`datasheet `__,
+`Adafruit`_) with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration
+for this sensor to work.
+
+.. figure:: ../../images/mmc5603.jpg
+ :align: center
+ :width: 30.0%
+
+ MMC5603 Magnetometer.
+
+.. _Adafruit: https://www.adafruit.com/product/5579
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ sensor:
+ - platform: MMC5603
+ address: 0x30
+ field_strength_x:
+ name: "MMC5603 Field Strength X"
+ field_strength_y:
+ name: "MMC5603 Field Strength Y"
+ field_strength_z:
+ name: "MMC5603 Field Strength Z"
+ heading:
+ name: "MMC5603 Heading"
+ update_interval: 60s
+
+Configuration variables:
+------------------------
+
+- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x1E``.
+- **field_strength_x** (*Optional*): The field strength in microtesla along the X-Axis. All options from
+ :ref:`Sensor `.
+- **field_strength_y** (*Optional*): The field strength in microtesla along the Y-Axis. All options from
+ :ref:`Sensor `.
+- **field_strength_z** (*Optional*): The field strength in microtesla along the Z-Axis. All options from
+ :ref:`Sensor `.
+- **heading** (*Optional*): The heading of the sensor in degrees. All options from
+ :ref:`Sensor `.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`template`
+- :apiref:`mmc5603/mmc5603.h`
+- :ghedit:`Edit`
diff --git a/components/sensor/pmsx003.rst b/components/sensor/pmsx003.rst
index df879a418..0ecee8b54 100644
--- a/components/sensor/pmsx003.rst
+++ b/components/sensor/pmsx003.rst
@@ -5,7 +5,7 @@ PMSX003 Particulate Matter Sensor
:description: Instructions for setting up PMSX003 Particulate matter sensors
:image: pmsx003.svg
-The ``pmsx003`` sensor platform allows you to use your PMS5003, PMS7003, ... particulate matter
+The ``pmsx003`` sensor platform allows you to use your Plantower PMS5003, PMS7003, ... laser based particulate matter sensors
(`datasheet `__)
sensors with ESPHome.
@@ -18,9 +18,16 @@ value:
- ``PMSX003`` for generic PMS5003, PMS7003, ...; these sensors support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0`` output.
- ``PMS5003S`` for PMS5003S. These support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0`` and ``formaldehyde``.
-- ``PMS5003T`` for PMS5003T. These support ``pm_2_5``, ``temperature`` and ``humidity``.
+- ``PMS5003T`` for PMS5003T. These support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0``, ``temperature`` and ``humidity``.
- ``PMS5003ST`` for PMS5003ST. These support ``pm_2_5``, ``temperature``, ``humidity`` and ``formaldehyde``.
+Sensor Longevity
+------------------------
+The laser diode inside the PMSX003 has a lifetime of about 8000 hours, nearly one year.
+
+If you wish to use the optional ``update_interval`` ensure you have a ``tx_pin`` set in the UART configuration and connected to the RECEIVE/RX pin
+(may also be called the TX pin, depending on the model) of the PMS. Setting ``update_interval`` to 120 seconds or higher may help extend the life span of the sensor.
+
.. code-block:: yaml
# Example configuration entry
@@ -38,34 +45,34 @@ value:
name: "Particulate Matter <2.5µm Concentration"
pm_10_0:
name: "Particulate Matter <10.0µm Concentration"
- update_interval: 60000ms
+ update_interval: 120s
Configuration variables:
------------------------
-- **pm_1_0_std** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter at standard particle
+- **pm_1_0_std** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter at standard particle.
All options from :ref:`Sensor `.
-- **pm_2_5_std** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter at standard particle
+- **pm_2_5_std** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter at standard particle.
All options from :ref:`Sensor `.
-- **pm_10_0_std** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter at standard particle
+- **pm_10_0_std** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter at standard particle.
All options from :ref:`Sensor `.
-- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter under atmospheric environment
+- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter under atmospheric environment.
All options from :ref:`Sensor `.
-- **pm_2_5** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter under atmospheric environment
+- **pm_2_5** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter under atmospheric environment.
All options from :ref:`Sensor `.
-- **pm_10_0** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter under atmospheric environment
+- **pm_10_0** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter under atmospheric environment.
All options from :ref:`Sensor `.
-- **pm_0_3um** (*Optional*): Use the number of particles with diameter beyond 0.3um in 0.1L of air
+- **pm_0_3um** (*Optional*): Use the number of particles with diameter beyond 0.3um in 0.1L of air.
All options from :ref:`Sensor `.
-- **pm_0_5um** (*Optional*): Use the number of particles with diameter beyond 0.5um in 0.1L of air
+- **pm_0_5um** (*Optional*): Use the number of particles with diameter beyond 0.5um in 0.1L of air.
All options from :ref:`Sensor `.
-- **pm_1_0um** (*Optional*): Use the number of particles with diameter beyond 1.0um in 0.1L of air
+- **pm_1_0um** (*Optional*): Use the number of particles with diameter beyond 1.0um in 0.1L of air.
All options from :ref:`Sensor `.
-- **pm_2_5um** (*Optional*): Use the number of particles with diameter beyond 2.5um in 0.1L of air
+- **pm_2_5um** (*Optional*): Use the number of particles with diameter beyond 2.5um in 0.1L of air.
All options from :ref:`Sensor `.
-- **pm_5_0um** (*Optional*): Use the number of particles with diameter beyond 5.0um in 0.1L of air
+- **pm_5_0um** (*Optional*): Use the number of particles with diameter beyond 5.0um in 0.1L of air. Not supported by the ``PMS5003T`` type sensors.
All options from :ref:`Sensor `.
-- **pm_10_0um** (*Optional*): Use the number of particles with diameter beyond 10.0um in 0.1L of air
+- **pm_10_0um** (*Optional*): Use the number of particles with diameter beyond 10.0um in 0.1L of air. Not supported by the ``PMS5003T`` type sensors.
All options from :ref:`Sensor `.
- **temperature** (*Optional*): Use the temperature value in °C for the ``PMS5003T`` and ``PMS5003ST`` type sensors.
All options from :ref:`Sensor `.
diff --git a/components/spi.rst b/components/spi.rst
index d6a433ced..8cac04e9c 100644
--- a/components/spi.rst
+++ b/components/spi.rst
@@ -41,6 +41,7 @@ Configuration variables:
- **clk_pin** (**Required**, :ref:`Pin Schema `): The pin used for the clock line of the SPI bus.
- **mosi_pin** (*Optional*, :ref:`Pin Schema `): The pin used for the MOSI line of the SPI bus.
- **miso_pin** (*Optional*, :ref:`Pin Schema `): The pin used for the MISO line of the SPI bus.
+- **force_sw** (*Optional*, boolean): Whether software implementation should be used even if hardware one is available.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this SPI hub if you need multiple SPI hubs.
See Also
diff --git a/components/switch/index.rst b/components/switch/index.rst
index e14ddf99c..881e4e046 100644
--- a/components/switch/index.rst
+++ b/components/switch/index.rst
@@ -23,6 +23,12 @@ Base Switch Configuration
Configuration variables:
- **name** (**Required**, string): The name of the switch.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the switch to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the
sensor in the frontend.
- **inverted** (*Optional*, boolean): Whether to invert the binary
@@ -41,11 +47,11 @@ Configuration variables:
- ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON.
- ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF.
- ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON.
- - ``ALWAYS_OFF`` - Always initialize the switch as OFF on bootup.
+ - ``ALWAYS_OFF`` (Default) - Always initialize the switch as OFF on bootup.
- ``ALWAYS_ON`` - Always initialize the switch as ON on bootup.
- - ``DISABLED`` - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state.
+ - ``DISABLED`` - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state.
- Unless a specific platform defines another default value, the default is ``RESTORE_DEFAULT_OFF``.
+ Unless a specific platform defines another default value, the default is ``ALWAYS_OFF``.
- **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform
when the switch is turned on. See :ref:`switch-on_turn_on_off_trigger`.
diff --git a/components/text_sensor/index.rst b/components/text_sensor/index.rst
index d5379c67d..c91a0997d 100644
--- a/components/text_sensor/index.rst
+++ b/components/text_sensor/index.rst
@@ -25,6 +25,12 @@ Base Text Sensor Configuration
Configuration variables:
- **name** (**Required**, string): The name for the sensor.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the text sensor to use that name, you can set ``name: None``.
+
- **icon** (*Optional*, icon): Manually set the icon to use for the sensor 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
@@ -145,7 +151,7 @@ The arguments are a list of substitutions, each in the form ``TO_FIND -> REPLACE
``map``
*******
-Lookup the current value of the text sensor in a list, and return the matching item if found.
+Lookup the current value of the text sensor in a list, and return the matching item if found.
Does not change the value of the text sensor if the current value wasn't found.
diff --git a/components/voice_assistant.rst b/components/voice_assistant.rst
new file mode 100644
index 000000000..8bd5c1b18
--- /dev/null
+++ b/components/voice_assistant.rst
@@ -0,0 +1,79 @@
+Voice Assistant
+===============
+
+.. seo::
+ :description: Instructions for setting up a Voice Assistant in ESPHome.
+ :image: voice-assistant.svg
+
+ESPHome devices with a microphone are able to stream the audio to Home Assistant and be processed there by `assist `__.
+
+.. note::
+
+ Voice Assistant requires Home Assistant 2023.5 or later.
+
+Configuration:
+--------------
+
+.. code-block:: yaml
+
+ microphone:
+ - platform: ...
+ id: mic_id
+
+ voice_assistant:
+ microphone: mic_id
+
+- **microphone** (**Required**, :ref:`config-id`): The microphone to use for input.
+- **on_start** (*Optional*, :ref:`Automation `): An automation to
+ perform when the voice assistant starts listening.
+- **on_end** (*Optional*, :ref:`Automation `): An automation to perform
+ when the voice assistant is finished all tasks.
+- **on_stt_end** (*Optional*, :ref:`Automation `): An automation to perform
+ when the voice assistant has finished speech-to-text. The resulting text is
+ available to automations as the variable ``x``.
+- **on_tts_start** (*Optional*, :ref:`Automation `): An automation to perform
+ when the voice assistant has started text-to-speech. The text to be spoken is
+ available to automations as the variable ``x``.
+- **on_tts_end** (*Optional*, :ref:`Automation `): An automation to perform
+ when the voice assistant has finished text-to-speech. A URL containing the audio response
+ is available to automations as the variable ``x``.
+- **on_error** (*Optional*, :ref:`Automation `): An automation to perform
+ when the voice assistant has encountered an error. The error code and message are available to
+ automations as the variables ``code`` and ``message``.
+
+.. _voice_assistant-actions:
+
+Voice Assistant Actions
+-----------------------
+
+The following actions are available for use in automations:
+
+- ``voice_assistant.start`` - Start listening for voice commands.
+- ``voice_assistant.stop`` - Stop listening for voice commands.
+
+
+Push to Talk
+------------
+
+Here is an example offering Push to Talk with a :doc:`/components/binary_sensor/index`.
+
+.. code-block:: yaml
+
+ voice_assistant:
+ microphone: mic_id
+
+ binary_sensor:
+ - platform: gpio
+ pin: ...
+ on_press:
+ - voice_assistant.start:
+ on_release:
+ - voice_assistant.stop:
+
+
+See Also
+--------
+
+- :doc:`microphone/index`
+- :apiref:`voice_assistant/voice_assistant.h`
+- :ghedit:`Edit`
diff --git a/conf.py b/conf.py
index e2a34fce6..13647ccf8 100644
--- a/conf.py
+++ b/conf.py
@@ -67,9 +67,9 @@ author = "ESPHome"
# built documents.
#
# The short X.Y version.
-version = "2023.3"
+version = "2023.4"
# The full version, including alpha/beta/rc tags.
-release = "2023.3.2"
+release = "2023.4.0"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/guides/supporters.rst b/guides/supporters.rst
index 78fc2f687..4c0d6ef55 100644
--- a/guides/supporters.rst
+++ b/guides/supporters.rst
@@ -16,6 +16,7 @@ Contributors
(in alphabetical order)
+- `007hacky007 (@007hacky007) `__
- `0hax (@0hax) `__
- `0x0a11c0de (@0x0a11c0de) `__
- `Denis Bodor (aka Lefinnois) (@0xDRRB) `__
@@ -26,10 +27,12 @@ Contributors
- `Alessandro Campolo (@a13ssandr0) `__
- `Aalian Khan (@AalianKhan) `__
- `Adam Liddell (@aaliddell) `__
+- `Aaron Gamble (@aarongamble) `__
- `Aaron S. Jackson (@AaronJackson) `__
- `Abel Matser (@abelmatser) `__
- `Abílio Costa (@abmantis) `__
- `Antonio (@acarvajalperez) `__
+- `Avula Chandra Kiran Reddy (@ackr-8) `__
- `Zhenyu Wu (@Adam5Wu) `__
- `Chris Byrne (@adapt0) `__
- `Attila Darazs (@adarazs) `__
@@ -41,9 +44,12 @@ Contributors
- `Stefan Agner (@agners) `__
- `Anders (@ahd71) `__
- `Alexander Pohl (@ahpohl) `__
+- `aidbish (@aidbish) `__
- `Airy André (@airy10) `__
+- `Airyzz (@Airyzz) `__
- `Adam Jacques (@ajacques) `__
- `Andrej Friesen (@ajfriesen) `__
+- `akennerly (@akennerly) `__
- `akoivist (@akoivist) `__
- `Andrej Komelj (@akomelj) `__
- `Alex Konradi (@akonradi) `__
@@ -58,13 +64,17 @@ Contributors
- `Alex Iribarren (@alexiri) `__
- `Alex Mekkering (@AlexMekkering) `__
- `Alex (@alexyao2015) `__
+- `Alfredo (@alfredopironti) `__
- `Andreas Mandel (@amandel) `__
- `Amish Vishwakarma (@amishv) `__
+- `Amit Keret (@amitkeret) `__
- `Jason Nader (@ammgws) `__
- `Branden Cash (@ammmze) `__
- `Alexander Momchilov (@amomchilov) `__
- `anatoly-savchenkov (@anatoly-savchenkov) `__
- `andig (@andig) `__
+- `Andi Egli (@andilge) `__
+- `Kieren (@ando023) `__
- `András Bíró (@andrasbiro) `__
- `Andreas Hergert (@andreashergert1984) `__
- `Andrew J.Swan (@andrewjswan) `__
@@ -73,14 +83,17 @@ Contributors
- `Andrzej (@andriej) `__
- `Andreas (@anduchs) `__
- `Andy2No (@Andy2No) `__
+- `AndyRPH (@AndyRPH) `__
- `Vegetto (@angelnu) `__
- `Sergey Anisimov (@anisimovsergey) `__
- `Nikolay Vasilchuk (@Anonym-tsk) `__
- `Anthony Keane (@anthonykeane) `__
+- `Rémi K. (@antibill51) `__
- `Antonio Fiol (@antonio-fiol) `__
- `Adriaan Peeters (@apeeters) `__
- `apendley (@apendley) `__
- `Darius Ratkevičius (@aphex008) `__
+- `aquaticus (@aquaticus) `__
- `Andy Allsopp (@arallsopp) `__
- `arantius (@arantius) `__
- `arturo182 (@arturo182) `__
@@ -88,33 +101,45 @@ Contributors
- `Arya (@Arya11111) `__
- `Borys Pierov (@ashald) `__
- `Ash McKenzie (@ashmckenzie) `__
+- `ashp8i (@ashp8i) `__
- `Ashton Kemerling (@AshtonKem) `__
- `杨成锴 (@asjdf) `__
- `Pavel Pletenev (@ASMfreaK) `__
- `Andreas Soehlke (@asoehlke) `__
- `Mike Dunston (@atanisoft) `__
+- `Glenn Morrison (@atomicpapa) `__
- `Alexander Turlov (@aturlov) `__
+- `aus (@aus) `__
- `AustinMorris (@AustinMorris) `__
- `Avirsaam (@Avirsaam) `__
- `Arsène von Wyss (@avonwyss) `__
+- `Andrew Weddle (@aweddle2) `__
- `Achilleas Pipinellis (@axilleas) `__
- `Kamil Trzciński (@ayufan) `__
- `Nicholas Peters (@Azimath) `__
- `Daniel (@azrael783) `__
- `B48D81EFCC (@B48D81EFCC) `__
- `Florian Mösch (@badbadc0ffee) `__
+- `Baden (@baden03) `__
- `Marco Tombesi (@baggior) `__
- `balk77 (@balk77) `__
- `Paulus Schoutsen (@balloob) `__
- `Andrew Zaborowski (@balrog-kun) `__
- `BarryMar (@BarryMar) `__
+- `bartoszpierzchlewicz (@bartoszpierzchlewicz) `__
+- `BartoszPierzchlewiczMacrix (@BartoszPierzchlewiczMacrix) `__
- `Bascht74 (@Bascht74) `__
- `Viktr (@BbIKTOP) `__
- `J. Nick Koston (@bdraco) `__
- `Maxim Ocheretianko (@bearpawmaxim) `__
+- `beaudeanadams (@beaudeanadams) `__
- `Benjamin Freeman (@Beetix) `__
+- `beikeland (@beikeland) `__
+- `Ben-Schwabe (@Ben-Schwabe) `__
+- `Ben Hoff (@benhoff) `__
- `Benno Pütz (@bennop) `__
- `Benoit3 (@Benoit3) `__
+- `Ben Shaner (@bens545) `__
- `Ben Suffolk (@bensuffolk) `__
- `Berend Haan (@berendhaan) `__
- `Arturo Casal (@berfenger) `__
@@ -122,22 +147,29 @@ Contributors
- `Bert Hertogen (@berthertogen) `__
- `Ivan Bessarabov (@bessarabov) `__
- `Brandon (@bgulla) `__
+- `Benedikt Hübschen (@bhuebschen) `__
- `Bierchermuesli (@Bierchermuesli) `__
- `Bill Church (@billchurch) `__
- `Brian Kaufman (@bkaufx) `__
- `JDavid (@blackhack) `__
- `blakadder (@blakadder) `__
- `Branimir Lambov (@blambov) `__
+- `bleeisme (@bleeisme) `__
- `Jim Ekman (@blejdfist) `__
- `Scott Smith (@blurfl) `__
- `Bob (@Bmooij) `__
- `Benjamin Klotz (@bnw) `__
+- `Bob Kersten (@bobkersten) `__
- `Bodmer (@Bodmer) `__
+- `Anthony Todd (@bohregard) `__
+- `Bomaker (@Bomaker) `__
- `Mauricio Bonani (@bonanitech) `__
- `Casey Olson (@bookcasey) `__
+- `Borja Burgos (@borjaburgos) `__
- `BoukeHaarsma23 (@BoukeHaarsma23) `__
- `brambo123 (@brambo123) `__
- `Bram Kragten (@bramkragten) `__
+- `Brandan Cotton (@Brando47) `__
- `Brad Davidson (@brandond) `__
- `Daniel H Brown (@brauhausdc) `__
- `Jens Bretschneider (@breti) `__
@@ -147,36 +179,52 @@ Contributors
- `brianrjones69 (@brianrjones69) `__
- `Ben Brooks (@brooksben11) `__
- `buddydvd (@buddydvd) `__
+- `Matt Burke (@burkemw3) `__
- `Jon Little (@burundiocibu) `__
- `buxtronix (@buxtronix) `__
- `bvansambeek (@bvansambeek) `__
+- `c0ffeeca7 (@c0ffeeca7) `__
+- `Captain Haddock (@ca-haddock) `__
- `Cal Howard (@calhoward) `__
+- `callacomp (@callacomp) `__
+- `Callum Gare (@callumgare) `__
- `Carlos Gustavo Sarmiento (@carlos-sarmiento) `__
- `Carlos Garcia Saura (@CarlosGS) `__
- `Carlos Ruiz (@CarlosRDomin) `__
+- `carlywarly (@carlywarly) `__
- `carstenschroeder (@carstenschroeder) `__
- `Valentin Ochs (@Cat-Ion) `__
- `Stroe Andrei Catalin (@catalin2402) `__
- `cbialobos (@cbialobos) `__
+- `Cameron Bulock (@cbulock) `__
- `Ciprian Constantinescu (@cciprian5) `__
+- `cdmonk (@cdmonk) `__
+- `ceaswaran (@ceaswaran) `__
- `Cellie (@CelliesProjects) `__
- `Chris Feenstra (@cfeenstra1024) `__
+- `cg089 (@cg089) `__
- `Kostas Chatzikokolakis (@chatziko) `__
+- `Audric Schiltknecht (@chemicalstorm) `__
- `chris-jennings (@chris-jennings) `__
- `Chris (@chrismaki) `__
- `Christoph Wagner (@Christoph-Wagner) `__
- `Christian Taedcke (@chrta) `__
- `Pavel Skuratovich (@Chupaka) `__
- `Chris Johnson (@ciband) `__
+- `CircuitGuy (@CircuitGuy) `__
- `John (@CircuitSetup) `__
- `Colby Rome (@cisasteelersfan) `__
- `Chris Debenham (@cjd) `__
- `Chester (@clowrey) `__
+- `Colin McCambridge (@cmccambridge) `__
- `Clifford Roche (@cmroche) `__
- `Casey Burnett (@codeangler) `__
- `CODeRUS (@CODeRUS) `__
+- `Alex Miller (@Codex-) `__
- `Cody James (@codyjamestechnical) `__
+- `Ashton Lafferty (@cogneato) `__
- `Colin Leroy-Mira (@colinleroy) `__
+- `Max (@coltoncat) `__
- `Conclusio (@Conclusio) `__
- `John Coggeshall (@coogle) `__
- `James Crook (@cooljimy84) `__
@@ -189,20 +237,28 @@ Contributors
- `Connor Prussin (@cprussin) `__
- `Corey Rice (@crice009) `__
- `cryptelli (@cryptelli) `__
+- `Christian Schwarzgruber (@cslux)