diff --git a/Doxygen b/Doxygen
index 772762385..2d9ae972a 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 = 2024.2.2
+PROJECT_NUMBER = 2024.3.1
# 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 5838a1ddd..9091dc700 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2024.2.2
+ESPHOME_REF = 2024.3.1
.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-2024.3.0.png b/_static/changelog-2024.3.0.png
new file mode 100644
index 000000000..831a16088
Binary files /dev/null and b/_static/changelog-2024.3.0.png differ
diff --git a/_static/version b/_static/version
index 11eca20ea..4bb304eda 100644
--- a/_static/version
+++ b/_static/version
@@ -1 +1 @@
-2024.2.2
\ No newline at end of file
+2024.3.1
\ No newline at end of file
diff --git a/changelog/2024.3.0.rst b/changelog/2024.3.0.rst
new file mode 100644
index 000000000..59d22ca00
--- /dev/null
+++ b/changelog/2024.3.0.rst
@@ -0,0 +1,305 @@
+ESPHome 2024.3.0 - 20th March 2024
+==================================
+
+.. seo::
+ :description: Changelog for ESPHome 2024.3.0.
+ :image: /_static/changelog-2024.3.0.png
+ :author: Jesse Hills
+ :author_twitter: @jesserockz
+
+.. imgtable::
+ :columns: 5
+
+ Datetime Core, components/datetime/index, clock-outline.svg, dark-invert
+ Template Datetime, components/datetime/template, description.svg, dark-invert
+
+ AM2315C, components/sensor/am2315c, am2315c.jpg
+ HTU31D, components/sensor/htu31d, htu31d.jpg,
+ MS8607, components/sensor/ms8607, ms8607.jpg
+
+ AGS10, components/sensor/ags10, ags10.jpg
+ VEML6030, components/sensor/veml7700, veml6030.jpg
+ VEML7700, components/sensor/veml7700, veml7700.jpg
+
+ MR24HPC1 mmWave, components/seeed_mr24hpc1, seeed-mr24hpc1.jpg
+
+ ADS1118, components/sensor/ads1118, ads1118.jpg
+
+ CST816, components/touchscreen/cst816, cst816.jpg
+ CST226, components/touchscreen/cst226, t4-s3.jpg
+
+ RPI_DPI_RGB, components/display/rpi_dpi_rgb, waveshare_touch-s3.jpg
+ Quad SPI AMOLED, components/display/qspi_amoled, t4-s3.jpg
+ ST7701S, components/display/st7701s, indicator.jpg
+
+ ADE7880, components/sensor/ade7880, ade7880.svg
+ Emmeti, components/climate/climate_ir, air-conditioner-ir.svg, dark-invert
+ Uponor Smatrix, components/uponor_smatrix, uponor.svg
+ Kamstrup KMP, components/sensor/kamstrup_kmp, kamstrup_kmp.jpg
+ Template Fan, components/fan/template, description.svg, dark-invert
+
+
+Dates
+-----
+
+ESPHome now has support for ``date`` entities that can be set from the frontend (like Home Assistant) for you to check against and execute
+automations in the future.
+
+ESPHome Dates require Home Assistant 2024.4 or later.
+
+
+IPv6
+----
+
+ESPHome is now prepared for the future! The future that is the old IPv6 that is.
+Dualstack is added and it could now have up to 5 ip addresses of any type, and communication with Home assistant,
+MQTT and NTP works with IPv6. ESPHome still depends on IPv4, but the crystal ball shows sign of IPv6-only networks.
+
+If you are building an :doc:`/components/external_components` or you use
+``network::get_ip_address()``, ``wifi::global_wifi_component->get_ip_address()`` or ``ethernet::global_eth_component->get_ip_address()``,
+these functions have been renamed to ``::get_ip_addresses()`` respectively and now return a list of all IP addresses.
+
+
+Release 2024.3.1 - March 27
+---------------------------
+
+- AHT10: Fix bug :esphomepr:`6409` by :ghuser:`clydebarrow`
+- microWakeWord: Fix model path joining :esphomepr:`6426` by :ghuser:`ebw44`
+- Don't compile strptime unless its required :esphomepr:`6424` by :ghuser:`gabest11`
+- Fix editor live validation :esphomepr:`6431` by :ghuser:`bdraco`
+
+
+Thank you for your support
+--------------------------
+
+We would like to thank all Home Assistant Cloud subscribers for their support. It allows `Nabu Casa `__ to
+employ two developers to maintain and further develop the ESPHome project.
+
+Full list of changes
+--------------------
+
+New Components
+^^^^^^^^^^^^^^
+
+- New component: ADE7880 voltage/current/power/energy sensor :esphomepr:`5242` by :ghuser:`kpfleming` (new-integration)
+- Add Uponor Smatrix component :esphomepr:`5769` by :ghuser:`kroimon` (new-integration)
+- Support for MS8607 PHT (Pressure Humidity Temperature) sensor :esphomepr:`3307` by :ghuser:`e28eta` (new-integration)
+- Add datetime date entities :esphomepr:`6191` by :ghuser:`RFDarter` (new-integration)
+- Add AGS10 Sensor :esphomepr:`6070` by :ghuser:`mak-42` (new-integration)
+- ads1118 component :esphomepr:`5711` by :ghuser:`solomondg1` (new-integration)
+- Add CST816 touchscreen driver :esphomepr:`5941` by :ghuser:`clydebarrow` (new-integration)
+- AM2315C Temperature + Humidity Sensor :esphomepr:`6266` by :ghuser:`swoboda1337` (new-integration)
+- Touchscreen: add support for CST226 controller chip :esphomepr:`6151` by :ghuser:`clydebarrow` (new-integration)
+- Drivers for RGB 16 bit parallel displays :esphomepr:`5872` by :ghuser:`clydebarrow` (new-integration)
+- VEML7700 and VEML6030 light sensors :esphomepr:`6067` by :ghuser:`latonita` (new-integration)
+- Add Seeed Studio mmWave Kit MR24HPC1 :esphomepr:`5761` by :ghuser:`limengdu` (new-integration)
+- Add driver for quad SPI AMOLED displays :esphomepr:`6354` by :ghuser:`clydebarrow` (new-integration)
+- feat: Add HTU31D Support :esphomepr:`5805` by :ghuser:`betterengineering` (new-integration)
+- Emmeti infrared climate support :esphomepr:`5197` by :ghuser:`E440QF` (new-integration)
+- Added Kamstrup Multical 40x component :esphomepr:`4200` by :ghuser:`cfeenstra1024` (new-integration)
+
+New Platforms
+^^^^^^^^^^^^^
+
+- Additional sensors and binary sensors support for Haier Climate :esphomepr:`6257` by :ghuser:`paveldn` (breaking-change) (new-platform)
+- add template fan :esphomepr:`6310` by :ghuser:`ssieb` (breaking-change) (new-platform)
+
+Breaking Changes
+^^^^^^^^^^^^^^^^
+
+- LTR390 - Multiple bugfixes :esphomepr:`6161` by :ghuser:`sjtrny` (breaking-change)
+- Touchscreen component and driver fixes :esphomepr:`5997` by :ghuser:`nielsnl68` (breaking-change)
+- Additional sensors and binary sensors support for Haier Climate :esphomepr:`6257` by :ghuser:`paveldn` (breaking-change) (new-platform)
+- add template fan :esphomepr:`6310` by :ghuser:`ssieb` (breaking-change) (new-platform)
+
+Beta Changes
+^^^^^^^^^^^^
+
+- SPI: Revert clk_pin to standard output pin schema :esphomepr:`6368` by :ghuser:`clydebarrow`
+- Allow actions in web_server to be executed via GET method :esphomepr:`5938` by :ghuser:`afarago`
+- fix servo restore :esphomepr:`6370` by :ghuser:`ssieb`
+- Don't try to get IPv6 addresses when disabled :esphomepr:`6366` by :ghuser:`HeMan`
+- Use AQI device class :esphomepr:`6376` by :ghuser:`fgsch`
+- Fix list-components when PR is not targeting dev :esphomepr:`6375` by :ghuser:`jesserockz`
+- allow negative ppm for sensair :esphomepr:`6385` by :ghuser:`ssieb`
+- microWakeWord - add new ops and small improvements :esphomepr:`6360` by :ghuser:`kahrendt`
+- Fix compilation for uponor_smatrix without time component :esphomepr:`6389` by :ghuser:`kroimon`
+- Shows component operation time in ``ms`` :esphomepr:`6388` by :ghuser:`edwardtfn`
+- IPv6 can't be enabled for libretiny :esphomepr:`6387` by :ghuser:`HeMan`
+- Replace name and friendly name in full adopted configs :esphomepr:`4456` by :ghuser:`jesserockz`
+- Fix bug in ``remote_base`` conditional :esphomepr:`6281` by :ghuser:`swoboda1337`
+- Fix sending packets to uponor_smatrix devices :esphomepr:`6392` by :ghuser:`kroimon`
+- Fix wrong initialization of vectors in ade7953_i2c :esphomepr:`6393` by :ghuser:`kroimon`
+- ld2420: Firmware v1.5.4+ bug workaround :esphomepr:`6168` by :ghuser:`descipher`
+- Require xsrf/csrf when using a password :esphomepr:`6396` by :ghuser:`jesserockz`
+- AHT10: Use state machine to avoid blocking delay :esphomepr:`6401` by :ghuser:`clydebarrow`
+- Show component warnings and errors in the log; :esphomepr:`6400` by :ghuser:`clydebarrow`
+- web_server support for v3 :esphomepr:`6203` by :ghuser:`RFDarter`
+
+All changes
+^^^^^^^^^^^
+
+- Bump openssh-client to 1:9.2p1-2+deb12u2 :esphomepr:`6216` by :ghuser:`jesserockz`
+- Add support for 1.8V-powered devices :esphomepr:`6234` by :ghuser:`bisbastuner`
+- Adjust HeatpumpIR dependency :esphomepr:`6222` by :ghuser:`ivankravets`
+- INA226 - fixed improper work with signed values, added configurable ADC parameters :esphomepr:`6172` by :ghuser:`latonita`
+- Prevent network config on rpipico board :esphomepr:`5832` by :ghuser:`carlosV2`
+- Bump pytest-asyncio from 0.23.3 to 0.23.5 :esphomepr:`6201` by :ghuser:`dependabot[bot]`
+- New component: ADE7880 voltage/current/power/energy sensor :esphomepr:`5242` by :ghuser:`kpfleming` (new-integration)
+- Add some components to the new testing framework (D) :esphomepr:`6175` by :ghuser:`kbx81`
+- Provide example devcontainer config for mdns and USB passthrough :esphomepr:`6094` by :ghuser:`linkedupbits`
+- Bump black from 23.12.1 to 24.2.0 :esphomepr:`6221` by :ghuser:`dependabot[bot]`
+- Bump pytest from 7.4.4 to 8.0.1 :esphomepr:`6246` by :ghuser:`dependabot[bot]`
+- Bump codecov/codecov-action from 3 to 4 :esphomepr:`6160` by :ghuser:`dependabot[bot]`
+- Bump peter-evans/create-pull-request from 5.0.2 to 6.0.0 :esphomepr:`6159` by :ghuser:`dependabot[bot]`
+- Bump frenck/action-yamllint from 1.4.2 to 1.5.0 :esphomepr:`6236` by :ghuser:`dependabot[bot]`
+- Bump voluptuous from 0.14.1 to 0.14.2 :esphomepr:`6181` by :ghuser:`dependabot[bot]`
+- Bump pyupgrade from 3.15.0 to 3.15.1 :esphomepr:`6247` by :ghuser:`dependabot[bot]`
+- LTR390 - Multiple bugfixes :esphomepr:`6161` by :ghuser:`sjtrny` (breaking-change)
+- Fix yamllint :esphomepr:`6253` by :ghuser:`jesserockz`
+- Improve the error message on OTA version mismatch :esphomepr:`6259` by :ghuser:`sybrenstuvel`
+- Bump aioesphomeapi from 21.0.2 to 22.0.0 :esphomepr:`6263` by :ghuser:`dependabot[bot]`
+- Allow ESP8266 to use multiple i2c busses :esphomepr:`6145` by :ghuser:`LouDou`
+- Add Uponor Smatrix component :esphomepr:`5769` by :ghuser:`kroimon` (new-integration)
+- Fix test_build_components for macOS sed :esphomepr:`6278` by :ghuser:`kbx81`
+- Allow to specify global build directory :esphomepr:`6276` by :ghuser:`werwolfby`
+- Add device class support to text sensor :esphomepr:`6202` by :ghuser:`dougiteixeira`
+- Bump pytest from 8.0.1 to 8.0.2 :esphomepr:`6288` by :ghuser:`dependabot[bot]`
+- Improve dualstack and IPv6 support :esphomepr:`5449` by :ghuser:`HeMan`
+- Waveshare e-ink 2IN9_V2 - fix full and partial update based on vendor… :esphomepr:`5481` by :ghuser:`darianndd`
+- Add RTTTL volume control. :esphomepr:`5968` by :ghuser:`nielsnl68`
+- Touchscreen component and driver fixes :esphomepr:`5997` by :ghuser:`nielsnl68` (breaking-change)
+- Add `on_update` trigger for Project versions :esphomepr:`6298` by :ghuser:`jesserockz`
+- Bump peter-evans/create-pull-request from 6.0.0 to 6.0.1 :esphomepr:`6302` by :ghuser:`dependabot[bot]`
+- CSE7766 Apparent Power & Power Factor calculations :esphomepr:`6292` by :ghuser:`DAVe3283`
+- Adding W5500 support to ethernet component :esphomepr:`4424` by :ghuser:`JeroenVanOort`
+- Fix numbering of ip_address sensors :esphomepr:`6305` by :ghuser:`HeMan`
+- Bump aioesphomeapi from 22.0.0 to 23.0.0 :esphomepr:`6293` by :ghuser:`dependabot[bot]`
+- Add regular polygon shapes to display component :esphomepr:`6108` by :ghuser:`mathieu-mp`
+- Fix return value in `core/automation.h` :esphomepr:`6314` by :ghuser:`FlyingFeng2021`
+- aht10: Added new CMD and renamed existing CMD to match datasheet :esphomepr:`6303` by :ghuser:`cptskippy`
+- handling with the negative temperature in the sensor tmp102 :esphomepr:`6316` by :ghuser:`FlyingFeng2021`
+- x9c: fix off by 1 error :esphomepr:`6318` by :ghuser:`andynumber2`
+- Support for MS8607 PHT (Pressure Humidity Temperature) sensor :esphomepr:`3307` by :ghuser:`e28eta` (new-integration)
+- Separate logger implementations for each hardware platform into different files :esphomepr:`6167` by :ghuser:`tomaszduda23`
+- Additional sensors and binary sensors support for Haier Climate :esphomepr:`6257` by :ghuser:`paveldn` (breaking-change) (new-platform)
+- Add toggle command to cover web_server endpoint :esphomepr:`6319` by :ghuser:`heythisisnate`
+- Improv: support connecting to hidden networks :esphomepr:`6322` by :ghuser:`jesserockz`
+- Update mDNS for IDF >= 5.0 :esphomepr:`6328` by :ghuser:`HeMan`
+- DFPlayer: refix Bug created with PR 4758 :esphomepr:`5861` by :ghuser:`sandronidi`
+- Fix build failures on host platform caused by #6167 :esphomepr:`6338` by :ghuser:`clydebarrow`
+- Update bang_bang to log two decimal places in config dump :esphomepr:`6304` by :ghuser:`rafalw1277`
+- Add datetime date entities :esphomepr:`6191` by :ghuser:`RFDarter` (new-integration)
+- Add AGS10 Sensor :esphomepr:`6070` by :ghuser:`mak-42` (new-integration)
+- Bump aioesphomeapi from 23.0.0 to 23.1.0 :esphomepr:`6332` by :ghuser:`dependabot[bot]`
+- Bump pytest-asyncio from 0.23.5 to 0.23.5.post1 :esphomepr:`6334` by :ghuser:`dependabot[bot]`
+- Bump docker/setup-buildx-action from 3.0.0 to 3.1.0 :esphomepr:`6295` by :ghuser:`dependabot[bot]`
+- Set dependabot to look at composite actions versions :esphomepr:`6343` by :ghuser:`jesserockz`
+- ads1118 component :esphomepr:`5711` by :ghuser:`solomondg1` (new-integration)
+- Bump actions/cache from 4.0.0 to 4.0.1 :esphomepr:`6306` by :ghuser:`dependabot[bot]`
+- Bump docker/build-push-action from 5.0.0 to 5.2.0 in /.github/actions/build-image :esphomepr:`6347` by :ghuser:`dependabot[bot]`
+- fix: modbus_textsensor response is too long in some cases :esphomepr:`6333` by :ghuser:`NewoPL`
+- add template fan :esphomepr:`6310` by :ghuser:`ssieb` (breaking-change) (new-platform)
+- dump config after logging CDC port is opened by host :esphomepr:`6169` by :ghuser:`tomaszduda23`
+- Add IRK support to allow tracking of devices with random MAC addresses :esphomepr:`6335` by :ghuser:`chbmuc`
+- [Fingerprint_grow] Implements Sleep Mode feature :esphomepr:`6116` by :ghuser:`alexborro`
+- cleanup ili9xxx component by removing data rate define :esphomepr:`6350` by :ghuser:`nielsnl68`
+- web_server_idf: support x-www-form-urlencoded POST requests :esphomepr:`6037` by :ghuser:`dentra`
+- feat(MQTT): Add QoS option for each MQTT component :esphomepr:`6279` by :ghuser:`Rapsssito`
+- Check permissions :esphomepr:`6255` by :ghuser:`OdileVidrine`
+- Add CST816 touchscreen driver :esphomepr:`5941` by :ghuser:`clydebarrow` (new-integration)
+- ILI9XXX: Lazily allocate buffer :esphomepr:`6352` by :ghuser:`clydebarrow`
+- AM2315C Temperature + Humidity Sensor :esphomepr:`6266` by :ghuser:`swoboda1337` (new-integration)
+- Add ble_presence binary sensor timeout config value. :esphomepr:`6024` by :ghuser:`clydebarrow`
+- Add state listeners to `rotary_encoder` :esphomepr:`6035` by :ghuser:`clydebarrow`
+- ili9xxx: Add support for GC9A01A display :esphomepr:`6351` by :ghuser:`clydebarrow`
+- Touchscreen: add support for CST226 controller chip :esphomepr:`6151` by :ghuser:`clydebarrow` (new-integration)
+- font: add anti-aliasing and other features :esphomepr:`6198` by :ghuser:`clydebarrow`
+- Mhz19 warmup :esphomepr:`6214` by :ghuser:`fornellas`
+- Refactor ATM90E32 to reduce blocking time and improve accuracy. :esphomepr:`5670` by :ghuser:`descipher`
+- Bump aioesphomeapi from 23.1.0 to 23.1.1 :esphomepr:`6348` by :ghuser:`dependabot[bot]`
+- Bump pytest from 8.0.2 to 8.1.1 :esphomepr:`6346` by :ghuser:`dependabot[bot]`
+- Add support for Waveshare 2.13" V2 display :esphomepr:`6337` by :ghuser:`manuelkasper`
+- Mitsubishi Climate updates :esphomepr:`3886` by :ghuser:`RubyBailey`
+- Drivers for RGB 16 bit parallel displays :esphomepr:`5872` by :ghuser:`clydebarrow` (new-integration)
+- hydreon_rgxx - add resolution option :esphomepr:`6077` by :ghuser:`mrtoy-me`
+- SPI schema now uses typed_schema with `type` key :esphomepr:`6353` by :ghuser:`clydebarrow`
+- VEML7700 and VEML6030 light sensors :esphomepr:`6067` by :ghuser:`latonita` (new-integration)
+- Add Seeed Studio mmWave Kit MR24HPC1 :esphomepr:`5761` by :ghuser:`limengdu` (new-integration)
+- Add getter for font glyph data :esphomepr:`6355` by :ghuser:`clydebarrow`
+- Require reset_pin for certain waveshare_epaper models in YAML validation :esphomepr:`6357` by :ghuser:`manuelkasper`
+- touchscreen driver fixes :esphomepr:`6356` by :ghuser:`clydebarrow`
+- Make USE_HOST compilable on msys2 :esphomepr:`6359` by :ghuser:`maruel`
+- download font from url on build :esphomepr:`5254` by :ghuser:`landonr`
+- Add driver for quad SPI AMOLED displays :esphomepr:`6354` by :ghuser:`clydebarrow` (new-integration)
+- ADE7953: Add the ability to use accumulating energy registers, more precise power reporting :esphomepr:`6311` by :ghuser:`isorin`
+- feat: Add HTU31D Support :esphomepr:`5805` by :ghuser:`betterengineering` (new-integration)
+- Emmeti infrared climate support :esphomepr:`5197` by :ghuser:`E440QF` (new-integration)
+- Added Kamstrup Multical 40x component :esphomepr:`4200` by :ghuser:`cfeenstra1024` (new-integration)
+- add possibility to provide different conversion times for Bus Voltage… :esphomepr:`6327` by :ghuser:`kev300`
+- SPI: Revert clk_pin to standard output pin schema :esphomepr:`6368` by :ghuser:`clydebarrow`
+- Allow actions in web_server to be executed via GET method :esphomepr:`5938` by :ghuser:`afarago`
+- fix servo restore :esphomepr:`6370` by :ghuser:`ssieb`
+- Don't try to get IPv6 addresses when disabled :esphomepr:`6366` by :ghuser:`HeMan`
+- Use AQI device class :esphomepr:`6376` by :ghuser:`fgsch`
+- Fix list-components when PR is not targeting dev :esphomepr:`6375` by :ghuser:`jesserockz`
+- allow negative ppm for sensair :esphomepr:`6385` by :ghuser:`ssieb`
+- microWakeWord - add new ops and small improvements :esphomepr:`6360` by :ghuser:`kahrendt`
+- Fix compilation for uponor_smatrix without time component :esphomepr:`6389` by :ghuser:`kroimon`
+- Shows component operation time in ``ms`` :esphomepr:`6388` by :ghuser:`edwardtfn`
+- IPv6 can't be enabled for libretiny :esphomepr:`6387` by :ghuser:`HeMan`
+- Replace name and friendly name in full adopted configs :esphomepr:`4456` by :ghuser:`jesserockz`
+- Fix bug in ``remote_base`` conditional :esphomepr:`6281` by :ghuser:`swoboda1337`
+- Fix sending packets to uponor_smatrix devices :esphomepr:`6392` by :ghuser:`kroimon`
+- Fix wrong initialization of vectors in ade7953_i2c :esphomepr:`6393` by :ghuser:`kroimon`
+- ld2420: Firmware v1.5.4+ bug workaround :esphomepr:`6168` by :ghuser:`descipher`
+- Require xsrf/csrf when using a password :esphomepr:`6396` by :ghuser:`jesserockz`
+- AHT10: Use state machine to avoid blocking delay :esphomepr:`6401` by :ghuser:`clydebarrow`
+- Show component warnings and errors in the log; :esphomepr:`6400` by :ghuser:`clydebarrow`
+- web_server support for v3 :esphomepr:`6203` by :ghuser:`RFDarter`
+
+Past Changelogs
+---------------
+
+- :doc:`2024.2.0`
+- :doc:`2023.12.0`
+- :doc:`2023.11.0`
+- :doc:`2023.10.0`
+- :doc:`2023.9.0`
+- :doc:`2023.8.0`
+- :doc:`2023.7.0`
+- :doc:`2023.6.0`
+- :doc:`2023.5.0`
+- :doc:`2023.4.0`
+- :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 f5beccf61..b69188536 100644
--- a/changelog/index.rst
+++ b/changelog/index.rst
@@ -2,7 +2,7 @@ Changelog
=========
.. redirect::
- :url: /changelog/2024.2.0.html
+ :url: /changelog/2024.3.0.html
.. toctree::
:glob:
diff --git a/components/binary_sensor/ble_presence.rst b/components/binary_sensor/ble_presence.rst
index 0328ebe68..b9fdd1f00 100644
--- a/components/binary_sensor/ble_presence.rst
+++ b/components/binary_sensor/ble_presence.rst
@@ -30,10 +30,15 @@ The ``ble_presence`` binary sensor platform lets you track the presence of a Blu
mac_address: AC:37:43:77:5F:4C
name: "ESP32 BLE Tracker Google Home Mini"
min_rssi: -80dB
+ # Presence based on Identity Resolving Key (IRK)
+ - platform: ble_presence
+ irk: 1234567890abcdef1234567890abcdef
+ name: "ESP32 BLE Tracker iPhone"
# Presence based on BLE Service UUID
- platform: ble_presence
service_uuid: '11aa'
name: "ESP32 BLE Tracker Test Service 16 bit"
+ timeout: 45s
# Presence based on iBeacon UUID
- platform: ble_presence
ibeacon_uuid: '68586f1e-89c2-11eb-8dcd-0242ac130003'
@@ -51,14 +56,17 @@ Configuration variables:
- **name** (**Required**, string): The name of the binary sensor.
- **mac_address** (*Optional*, MAC Address): The MAC address to track for this
- binary sensor. Note that exactly one of ``mac_address``, ``service_uuid`` or ``ibeacon_uuid``
+ binary sensor. Note that exactly one of ``mac_address``, ``irk``, ``service_uuid`` or ``ibeacon_uuid``
+ must be present.
+- **irk** (*Optional*, 16 byte hex string): The Identity Resolving Key (IRK) to track for this
+ binary sensor. Note that exactly one of ``mac_address``, ``irk``, ``service_uuid`` or ``ibeacon_uuid``
must be present.
- **service_uuid** (*Optional*, string): 16 bit, 32 bit, or 128 bit BLE Service UUID
which can be tracked if the device randomizes the MAC address. Note that exactly one of
- ``mac_address``, ``service_uuid`` or ``ibeacon_uuid`` must be present.
+ ``mac_address``, ``irk``, ``service_uuid`` or ``ibeacon_uuid`` must be present.
- **ibeacon_uuid** (*Optional*, string): The `universally unique identifier `__
to identify the beacon that needs to be tracked. Note that exactly one of ``mac_address``,
- ``service_uuid`` or ``ibeacon_uuid`` must be present.
+ ``irk``, ``service_uuid`` or ``ibeacon_uuid`` must be present.
- **ibeacon_major** (*Optional*, int): The iBeacon major identifier of the beacon that needs
to be tracked. Usually used to group beacons, for example for grouping all beacons in the
same building.
@@ -67,6 +75,8 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify
the ID used for code generation.
- **min_rssi** (*Optional*, int): at which minimum RSSI level would the component report the device be present.
+- **timeout** (*Optional*, :ref:`config-time`): The delay after last detecting the device before publishing not present state.
+ The default is 5 minutes.
- All other options from :ref:`Binary Sensor `.
.. _esp32_ble_tracker-setting_up_devices:
@@ -105,8 +115,15 @@ iBeacon major and minor identifiers, BLE manufacturer data, RSSI and other data
debugging purposes. Note that this is useful only during set-up and a less verbose log level
should be specified afterwards.
-Please note that devices that show a ``RANDOM`` address type in the logs cannot be used for
-MAC address based tracking, since their MAC-address periodically changes. Instead you can:
+Please note that devices that show a ``RANDOM`` address type in the logs probably use a privacy
+feature called Resolvable Private Addresses to avoid BLE tracking. Since their MAC-address periodically
+changes, they can't be tracked by the MAC address. However, if you know the devices "Identity Resolving
+Key" (IRK), you can check if the generated private MAC address belongs to the device with the IRK.
+
+There is no support to obtain the key with ESPHome. For now you will have to use one of the options
+described in the ESPresense project: https://espresense.com/beacons
+
+Alternatively you can:
- Create a BLE beacon, set a unique 16 bit, 32 bit or 128 bit Service UUID and track your device
based on that. Make sure you don't pick a `GATT Service UUID
diff --git a/components/binary_sensor/haier.rst b/components/binary_sensor/haier.rst
new file mode 100644
index 000000000..29e5445f5
--- /dev/null
+++ b/components/binary_sensor/haier.rst
@@ -0,0 +1,68 @@
+Haier Climate Binary Sensors
+============================
+
+.. seo::
+ :description: Instructions for setting up additional binary sensors for Haier climate devices.
+ :image: haier.svg
+
+Additional sensors for Haier Climate device. **These sensors are supported only by the hOn protocol**.
+
+
+.. figure:: images/haier-climate.jpg
+ :align: center
+ :width: 50.0%
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ uart:
+ baud_rate: 9600
+ tx_pin: 17
+ rx_pin: 16
+ id: ac_port
+
+ climate:
+ - platform: haier
+ id: haier_ac
+ protocol: hOn
+ name: Haier AC
+ uart_id: ac_port
+
+ binary_sensor:
+ - platform: haier
+ haier_id: haier_ac
+ compressor_status:
+ name: Haier Outdoor Compressor Status
+ defrost_status:
+ name: Haier Defrost Status
+ four_way_valve_status:
+ name: Haier Four Way Valve Status
+ indoor_electric_heating_status:
+ name: Haier Indoor Electric Heating Status
+ indoor_fan_status:
+ name: Haier Indoor Fan Status
+ outdoor_fan_status:
+ name: Haier Outdoor Fan Status
+
+Configuration variables:
+------------------------
+
+- **haier_id** (**Required**, :ref:`config-id`): The id of haier climate component
+- **compressor_status** (*Optional*): A binary sensor that indicates Haier climate compressor activity.
+ All options from :ref:`Binary Sensor `.
+- **defrost_status** (*Optional*): A binary sensor that indicates defrost procedure activity.
+ All options from :ref:`Binary Sensor `.
+- **four_way_valve_status** (*Optional*): A binary sensor that indicates four way valve status.
+ All options from :ref:`Binary Sensor `.
+- **indoor_electric_heating_status** (*Optional*): A binary sensor that indicates electrical heating system activity.
+ All options from :ref:`Binary Sensor `.
+- **indoor_fan_status** (*Optional*): A binary sensor that indicates indoor fan activity.
+ All options from :ref:`Binary Sensor `.
+- **outdoor_fan_status** (*Optional*): A binary sensor that indicates outdoor fan activity.
+ All options from :ref:`Binary Sensor `.
+
+See Also
+--------
+
+- :doc:`Haier Climate `
+- :ghedit:`Edit`
diff --git a/components/binary_sensor/images/haier-climate.jpg b/components/binary_sensor/images/haier-climate.jpg
new file mode 100644
index 000000000..81c68df78
Binary files /dev/null and b/components/binary_sensor/images/haier-climate.jpg differ
diff --git a/components/climate/climate_ir.rst b/components/climate/climate_ir.rst
index 8a665ddba..fc392c452 100644
--- a/components/climate/climate_ir.rst
+++ b/components/climate/climate_ir.rst
@@ -31,6 +31,8 @@ submit a feature request (see FAQ).
+---------------------------------------+---------------------+----------------------+
| :ref:`Delonghi` | ``delonghi`` | yes |
+---------------------------------------+---------------------+----------------------+
+| Emmeti | ``emmeti`` | yes |
++---------------------------------------+---------------------+----------------------+
| Fujitsu General | ``fujitsu_general`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`GREE` | ``gree`` | |
@@ -42,7 +44,7 @@ submit a feature request (see FAQ).
+---------------------------------------+---------------------+----------------------+
| Midea | ``midea_ir`` | yes |
+---------------------------------------+---------------------+----------------------+
-| Mitsubishi | ``mitsubishi`` | |
+| :ref:`Mitsubishi` | ``mitsubishi`` | yes |
+---------------------------------------+---------------------+----------------------+
| Noblex | ``noblex`` | yes |
+---------------------------------------+---------------------+----------------------+
@@ -253,6 +255,48 @@ Known working with:
- Delonghi PAC WE 120HP
+.. _mitsubishi:
+
+``mitsubishi`` Climate
+------------------------
+
+Additonal configurations available for this platform.
+
+Configuration variables:
+
+- **set_fan_mode** (*Optional*, string): Select the fan modes desired or that are supported on your remote. Defaults to ``3levels``
+
+ - Options are: ``3levels`` , ``4levels``, ``quiet_4levels``.
+
+ - ``3levels``; Low [fan speed 1], Medium [2], High [3]
+ - ``4levels``; Low [1], Middle [2], Medium [3], High [4]
+ - ``quiet_4levels``; Low [1], Middle [2], Medium [3], High [4], Quiet [5]
+
+- **supports_dry** (*Optional*, boolean): Enables setting dry mode for this unit. Defaults to ``false``.
+- **supports_fan_only** (*Optional*, boolean): Enables setting fan only mode for this unit. Confirm that mode is supported on your remote. Defaults to ``false``.
+
+- **horizontal_default** (*Optional*, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Defaults to ``middle``.
+
+ - Options are: ``left``, ``middle-left``, ``middle``, ``middle-right``, ``right``, ``auto``
+- **vertical_default** (*Optional*, string): What to default to when the AC unit's vertical direction is *not* set to swing. Defaults to ``middle``.
+
+ - Options are: ``down``, ``middle-down``, ``middle``, ``middle-up``, ``up``, ``auto``
+
+.. note::
+
+ - This climate IR component is also known to work with some Stiebel Eltron Units. It has been tested with Stiebel Eltron IR-Remote ``KM07F`` and unit ``ACW 25 i``
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ climate:
+ - platform: mitsubishi
+ name: "Heatpump"
+ set_fan_mode: "quiet_4levels"
+ supports_dry: "true"
+ supports_fan_only: "true"
+ horizontal_default: "left"
+ vertical_default: "down"
.. _toshiba:
@@ -284,7 +328,7 @@ Configuration variables:
``update_interval`` must be less than seven minutes or the ``RAC-PT1411HWRU`` will revert to using its own
internal temperature sensor; a value of 30 seconds seems to work well. See :doc:`/components/sensor/index`
for more information.
-
+
- This climate IR component is also known to work with Midea model MAP14HS1TBL and may work with other similar
models, as well. (Midea acquired Toshiba's product line and re-branded it.)
diff --git a/components/climate/haier.rst b/components/climate/haier.rst
index 775161519..caf04d18e 100644
--- a/components/climate/haier.rst
+++ b/components/climate/haier.rst
@@ -74,8 +74,6 @@ This component requires a :ref:`uart` to be setup.
wifi_signal: true
beeper: true
display: true
- outdoor_temperature:
- name: Haier AC outdoor temperature
visual:
min_temperature: 16 °C
max_temperature: 30 °C
@@ -125,16 +123,11 @@ Configuration variables:
- **control_method** (*Optional*, list): (supported only by hOn) Defines control method (should be supported by AC). Supported values: MONITOR_ONLY - no control, just monitor status, SET_GROUP_PARAMETERS - set all AC parameters with one command (default method), SET_SINGLE_PARAMETER - set each parameter individually (this method is supported by some new ceiling ACs like AD71S2SM3FA)
- **display** (*Optional*, boolean): Can be used to set the AC display off.
- **beeper** (*Optional*, boolean): Can be used to disable beeping on commands from AC. Supported only by hOn protocol.
-- **outdoor_temperature** (*Optional*): Temperature sensor for outdoor temperature. Supported only by hOn protocol.
-
- - **name** (**Required**, string): The name of the sensor.
- - **id** (*Optional*, :ref:`config-id`): ID of the sensor, can be used for code generation
- - All other options from :ref:`Sensor `.
- **supported_modes** (*Optional*, list): Can be used to disable some of AC modes. Possible values: 'OFF', HEAT_COOL, COOL, HEAT, DRY, FAN_ONLY
- **supported_swing_modes** (*Optional*, list): Can be used to disable some swing modes if your AC does not support it. Possible values: 'OFF', VERTICAL, HORIZONTAL, BOTH
- **supported_presets** (*Optional*, list): Can be used to disable some presets. Possible values for smartair2 are: AWAY, BOOST, COMFORT. Possible values for hOn are: AWAY, ECO, BOOST, SLEEP. AWAY preset can be enabled only in HEAT mode, it is disabled by default
-- **on_alarm_start (Optional, :ref:`Automation `):** (supported only by hOn) Automation to perform when AC activates a new alarm. See :ref:`haier-on_alarm_start`
-- **on_alarm_end (Optional, :ref:`Automation `):** (supported only by hOn) Automation to perform when AC deactivates a new alarm. See :ref:`haier-on_alarm_end`
+- **on_alarm_start** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC activates a new alarm. See :ref:`haier-on_alarm_start`
+- **on_alarm_end** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC deactivates a new alarm. See :ref:`haier-on_alarm_end`
- All other options from :ref:`Climate `.
Automations
@@ -327,6 +320,8 @@ See Also
--------
- `haier-esphome `__
+- :doc:`Haier Climate Sensors `
+- :doc:`Haier Climate Binary Sensors `
- :doc:`/components/climate/index`
- :apiref:`haier/climate/haier.h`
- :ghedit:`Edit`
diff --git a/components/datetime/index.rst b/components/datetime/index.rst
new file mode 100644
index 000000000..2b0713d41
--- /dev/null
+++ b/components/datetime/index.rst
@@ -0,0 +1,166 @@
+Datetime Component
+==================
+
+.. seo::
+ :description: Instructions for setting up datetime components in ESPHome.
+ :image: folder-open.svg
+
+ESPHome has support for components to create a datetime entity. A datetime entity
+currently represents a date that can be set by the user/frontend.
+
+.. note::
+
+ Requires Home Assistant 2024.4 or newer.
+
+.. _config-datetime:
+
+Base Datetime Configuration
+---------------------------
+
+All datetime in ESPHome have a name and an optional icon.
+
+.. code-block:: yaml
+
+ # Example datetime configuration
+ name: Date to check
+
+ # Optional variables:
+ icon: "mdi:calendar-alert"
+
+Configuration variables:
+
+- **name** (**Required**, string): The name for the datetime.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` set for your device and
+ you want the datetime to use that name, you can set ``name: None``.
+
+- **icon** (*Optional*, icon): Manually set the icon to use for the datetime 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).
+ Requires Home Assistant 2021.9 or newer. 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. Requires Home Assistant 2021.11 or newer.
+ Set to ``""`` to remove the default entity category.
+
+MQTT Options:
+
+- All other options from :ref:`MQTT Component `.
+
+Datetime Automation
+-------------------
+
+You can access the most recent state as a string of the datetime in :ref:`lambdas ` using
+``id(datetime_id).state``.
+You can also access it as a ``ESPTime`` object by ``id(datetime_id).state_as_time``
+
+.. _datetime-on_value:
+
+``on_value``
+************
+
+This automation will be triggered when a new value is published. In :ref:`Lambdas `
+you can get the value as a ESPTime object from the trigger with ``x``.
+
+.. code-block:: yaml
+
+ datetime:
+ - platform: template
+ # ...
+ on_value:
+ then:
+ - lambda: |-
+ if(x.hour >= 12) {
+ ESP_LOGD("main", "Updated hour is later or equal to 12");
+ } else {
+ ESP_LOGD("main", "Updated hour is earlier than 12");
+ }
+
+Configuration variables: See :ref:`Automation `.
+
+.. _datetime-date_set_action:
+
+``datetime.date.set`` Action
+****************************
+
+This is an :ref:`Action ` for setting a datetime date state.
+The ``date`` provided can be in one of 3 formats:
+
+.. code-block:: yaml
+
+ # String date
+ - datetime.date.set:
+ id: my_date
+ date: "2023-12-04"
+
+ # Individual date parts
+ - datetime.date.set:
+ id: my_date
+ date:
+ year: 2023
+ month: 12
+ day: 4
+
+ # Using a lambda
+ - datetime.date.set:
+ id: my_date
+ date: !lambda |-
+ // Return an ESPTime struct
+ return {.day_of_month: 4, .month: 12, .year: 2023};
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the datetime to set.
+- **date** (**Required**, string, date parts, :ref:`templatable `):
+ The value to set the datetime to.
+
+
+
+.. _datetime-lambda_calls:
+
+lambda calls
+************
+
+From :ref:`lambdas `, you can call several methods on all datetimes to do some
+advanced stuff (see the full API Reference for more info).
+
+- ``.make_call()``: Make a call for updating the datetime value.
+
+ .. code-block:: cpp
+
+ // Within lambda, set the date to 2024-02-25
+ auto call = id(my_date).make_call();
+ call.set_date("2024-02-25");
+ call.perform();
+
+ Check the API reference for information on the methods that are available for
+ the ``DateCall`` object.
+
+- ``.year``: Retrieve the current year of the ``date``. It will be ``0`` if no value has been set.
+- ``.month``: Retrieve the current month of the ``date``. It will be ``0`` if no value has been set.
+- ``.day``: Retrieve the current day of the ``date``. It will be ``0`` if no value has been set.
+- ``.state_as_esptime()``: Retrieve the current value of the datetime as a :apistruct:`ESPTime` object.
+
+ .. code-block:: cpp
+
+ // For example, create a custom log message when a value is received:
+ ESP_LOGI("main", "Value of my datetime: %04d-%02d-%02d", id(my_date).year, id(my_date).month, id(my_date).day);
+
+See Also
+--------
+
+- :apiref:`DateTimeBase `
+- :apiref:`DateEntity `
+- :apiref:`DateCall `
+- :ghedit:`Edit`
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
diff --git a/components/datetime/template.rst b/components/datetime/template.rst
new file mode 100644
index 000000000..b2eca7772
--- /dev/null
+++ b/components/datetime/template.rst
@@ -0,0 +1,59 @@
+Template Datetime
+=================
+
+.. seo::
+ :description: Instructions for setting up template datetime with ESPHome.
+ :image: description.svg
+
+The ``template`` datetime platform allows you to create a datetime with templated values
+using :ref:`lambdas `.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ datetime:
+ - platform: template
+ id: my_date
+ type: date
+ name: Pick a Date
+ optimistic: yes
+ initial_value: "2024-01-30"
+ restore_value: true
+
+Configuration variables:
+------------------------
+
+- **type** (*Required*, enum): The type of the datetime. Can only be ``date``.
+- **lambda** (*Optional*, :ref:`lambda `):
+ Lambda to be evaluated every update interval to get the current value of the datetime.
+- **set_action** (*Optional*, :ref:`Action `): The action that should
+ be performed when the remote (like Home Assistant's frontend) requests to set the
+ dateime value. The new value is available to lambdas in the ``x`` variable.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval on which to update the datetime
+ by executing the ``lambda``. Defaults to ``60s``.
+- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
+ any command sent to the template datetime will immediately update the reported state.
+ Cannot be used with ``lambda``. Defaults to ``false``.
+- **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash.
+ Cannot be used with ``lambda``. Defaults to ``false``.
+- **initial_value** (*Optional*, string): The value to set the state to on setup if not
+ restored with ``restore_value``. Can be one of:
+
+ - A string in the format ``%Y-%m-%d``, eg: ``"2023-12-04"``.
+ - An object including ``year``, ``month``, ``day``.
+
+ .. code-block:: yaml
+
+ initial_value:
+ year: 2023
+ month: 12
+ day: 4
+
+- All other options from :ref:`Datetime `.
+
+See Also
+--------
+
+- :ref:`automation`
+- :apiref:`template/datetime/template_date.h`
+- :ghedit:`Edit`
diff --git a/components/display/fonts.rst b/components/display/fonts.rst
new file mode 100644
index 000000000..47ab89461
--- /dev/null
+++ b/components/display/fonts.rst
@@ -0,0 +1,160 @@
+.. _display-fonts:
+
+Font Renderer Component
+=======================
+
+.. seo::
+ :description: Instructions for setting up fonts in ESPHome.
+ :image: format-font.svg
+
+ESPHome's graphical rendering engine also has a powerful font drawer which integrates seamlessly into the system. You have the option to use **any** OpenType/TrueType (``.ttf``, ``.otf``, ``.woff``) font file at **any** size, as well as fixed-size `PCF `_ and `BDF `_ bitmap fonts.
+
+These fonts can be used in ESPHome's :ref:`own rendering engine `.
+
+To use fonts you can either
+ - Just grab a ``.ttf``, ``.otf``, ``.woff``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example, inside a ``fonts`` folder next to your configuration file.
+ - Use the ``gfonts://`` short form to use Google Fonts directly.
+ - Load a font from a URL directly on build.
+
+Next, create a ``font:`` section in your configuration:
+
+.. code-block:: yaml
+
+ # Various ways to configure fonts
+ font:
+ - file: "fonts/Comic Sans MS.ttf"
+ id: my_font
+ size: 20
+ bpp: 2
+
+ - file: "fonts/tom-thumb.bdf"
+ id: tomthumb
+
+ # gfonts://family[@weight]
+ - file: "gfonts://Roboto"
+ id: roboto_20
+ size: 20
+
+ - file:
+ type: gfonts
+ family: Roboto
+ weight: 900
+ id: roboto_16
+ size: 16
+
+ - file: "gfonts://Material+Symbols+Outlined"
+ id: icons_50
+ size: 50
+ glyphs: ["\U0000e425"] # mdi-timer
+
+ - file: "fonts/RobotoCondensed-Regular.ttf"
+ id: roboto_special_28
+ size: 28
+ bpp: 4
+ glyphs: [
+ a,A,á,Á,e,E,é,É,
+ (,),+,-,_,.,°,•,µ,
+ "\u0020", #space
+ "\u0021", #!
+ "\u0022", #"
+ "\u0027", #'
+ ]
+
+ - file: "fonts/RobotoCondensed-Regular.ttf"
+ id: my_font_with_icons
+ size: 20
+ bpp: 4
+ extras:
+ - file: "fonts/materialdesignicons-webfont.ttf"
+ glyphs: [
+ "\U000F02D1", # mdi-heart
+ "\U000F05D4", # mdi-airplane-landing
+ ]
+
+ - file: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf"
+ id: web_font
+ size: 20
+ - file:
+ url: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf"
+ type: web
+ id: web_font2
+ size: 24
+
+ display:
+ # ...
+
+Configuration variables:
+------------------------
+
+- **file** (**Required**, string): The path (relative to where the .yaml file is) of the font
+ file. You can also use the ``gfonts://`` short form to use Google Fonts, or use the below structure:
+
+ - **type** (**Required**, string): Can be ``local``, ``gfonts`` or ``web``.
+
+ **Local Fonts**:
+
+ - **path** (**Required**, string): The path (relative to where the .yaml file is) of the OpenType/TrueType or bitmap font file.
+
+ **Google Fonts**:
+
+ Each Google Font will be downloaded once and cached for future use. This can also be used to download Material
+ Symbols or Icons as in the example above.
+
+ - **family** (**Required**, string): The name of the Google Font family.
+ - **italic** (*Optional*, boolean): Whether the font should be italic.
+ - **weight** (*Optional*, enum): The weight of the font. Can be either the text name or the integer value:
+ - **thin**: 100
+ - **extra-light**: 200
+ - **light**: 300
+ - **regular**: 400 (**default**)
+ - **medium**: 500
+ - **semi-bold**: 600
+ - **bold**: 700
+ - **extra-bold**: 800
+ - **black**: 900
+
+ **Web Fonts**:
+
+ - **url** (**Required**, string): The URL of the TrueType or bitmap font file.
+
+- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the font later
+ in your display code.
+- **size** (*Optional*, int): The size of the font in pt (not pixel!).
+ If you want to use the same font in different sizes, create two font objects. Note: *size* is ignored
+ by bitmap fonts. Defaults to ``20``.
+- **bpp** (*Optional*, int): The bit depth of the rendered font from OpenType/TrueType, for anti-aliasing. Can be ``1``, ``2``, ``4``, ``8``. Defaults to ``1``.
+- **glyphs** (*Optional*, list): A list of characters you plan to use. Only the characters you specify
+ here will be compiled into the binary. Adjust this if you need some special characters or want to
+ reduce the size of the binary if you don't plan to use some glyphs. You can also specify glyphs by their codepoint (see below). Defaults to ``!"%()+=,-_.:°/?0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz``.
+- **extras** (*Optional*, enum): A list of font glyph configurations you'd like to include within this font, from other OpenType/TrueType files (eg. icons from other font, but at the same size as the main font):
+
+ - **file** (**Required**, string): The path of the font file with the extra glyphs.
+ - **glyphs** (**Required**, list): A list of glyphs you want to include. Can't repeat the same glyph codepoint if it was declared in the level above.
+
+.. note::
+
+ OpenType/TrueType font files offer icons at codepoints far from what's reachable on a standard keyboard, for these it's needed
+ to specify the unicode codepoint of the glyph as a hex address escaped with ``\u`` or ``\U``.
+
+ - Code points up to ``0xFFFF`` are encoded like ``\uE6E8``. Lowercase ``\u`` and exactly 4 hexadecimal digits.
+ - Code points above ``0xFFFF`` are encoded like ``\U0001F5E9``. Capital ``\U`` and exactly 8 hexadecimal digits.
+
+ The ``extras`` section only supports OpenType/TrueType files, ``size`` and ``bpp`` will be the same as the above level. This will allow printing icons alongside the characters in the same string, like ``I \uF004 You \uF001``.
+
+ Many font sizes with multiple glyphs at high bit depths will increase the binary size considerably. Make your choices carefully.
+
+
+.. note::
+
+ To use fonts you will need to have the python ``pillow`` package installed, as ESPHome uses that package
+ to translate the OpenType/TrueType and bitmap font files into an internal format. If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed. Otherwise you need
+ to install it using ``pip install "pillow==10.2.0"``.
+
+See Also
+--------
+
+- :apiref:`display/display_buffer.h`
+- :ref:`display-engine`
+- `MDI cheatsheet `_
+- `MDI font repository `_
+- :ghedit:`Edit`
diff --git a/components/display/ili9xxx.rst b/components/display/ili9xxx.rst
index c1fff3d22..f734b2a13 100644
--- a/components/display/ili9xxx.rst
+++ b/components/display/ili9xxx.rst
@@ -10,6 +10,7 @@ ILI9xxx TFT LCD Series
Models
------
With this display driver you can control the following displays:
+ - GC9A01A
- ILI9341
- ILI9342
- ILI9481
@@ -69,6 +70,7 @@ Configuration variables:
- ``ILI9341``, ``ILI9342``, ``ILI9486``, ``ILI9488``, ``ILI9488_A`` (alternative gamma configuration for ILI9488)
- ``ILI9481``, ``ILI9481-18`` (18 bit mode)
- ``ST7789V``, ``ST7796``
+ - ``GC9A01A``
- **dc_pin** (**Required**, :ref:`Pin Schema `): The DC pin.
- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin.
diff --git a/components/display/images/indicator.jpg b/components/display/images/indicator.jpg
new file mode 100644
index 000000000..57397d6f5
Binary files /dev/null and b/components/display/images/indicator.jpg differ
diff --git a/components/display/images/t-display-amoled.jpg b/components/display/images/t-display-amoled.jpg
new file mode 100644
index 000000000..a5ac40559
Binary files /dev/null and b/components/display/images/t-display-amoled.jpg differ
diff --git a/components/display/images/t4-s3.jpg b/components/display/images/t4-s3.jpg
new file mode 100644
index 000000000..16d997b22
Binary files /dev/null and b/components/display/images/t4-s3.jpg differ
diff --git a/components/display/images/waveshare_touch-s3.jpg b/components/display/images/waveshare_touch-s3.jpg
new file mode 100644
index 000000000..ac719bb54
Binary files /dev/null and b/components/display/images/waveshare_touch-s3.jpg differ
diff --git a/components/display/index.rst b/components/display/index.rst
index a8a9b12f0..55b38afc6 100644
--- a/components/display/index.rst
+++ b/components/display/index.rst
@@ -9,10 +9,10 @@ The ``display`` component houses ESPHome's powerful rendering and display
engine. Fundamentally, there are these types of displays:
- Text based displays like :doc:`7-Segment displays ` or
- :doc:`some LCD displays `.
-- Displays like the :doc:`nextion` that have their own processors for rendering.
-- Binary displays which can toggle ON/OFF any pixel, like :doc:`E-Paper displays ` or
- :doc:`OLED displays `.
+ :doc:`LCD displays `.
+- Graphical serial displays like :doc:`nextion` that have their own processors for rendering.
+- Graphical binary displays which can toggle ON/OFF any pixel, like :doc:`E-Paper `,
+ :doc:`OLED ` or :doc:`TFT ` displays.
For the last type, ESPHome has a powerful rendering engine that can do
many things like draw some basic shapes, print text with any font you want, or even show images.
@@ -24,11 +24,6 @@ using an API that is designed to
- be simple and to be used without programming experience
- but also be flexible enough to work with more complex tasks like displaying an analog clock.
-.. note::
-
- Display hardware is complex and sometimes doesn't behave as expected. If you're having trouble with your display,
- please see :ref:`troubleshooting` below.
-
.. _display-engine:
Display Rendering Engine
@@ -38,6 +33,11 @@ In this section we will be discussing how to use ESPHome's display rendering eng
and some basic commands. Please note that this only applies to displays that can control each pixel
individually.
+.. note::
+
+ Display hardware is complex and sometimes doesn't behave as expected. If you're having trouble with your display,
+ please see :ref:`troubleshooting` below.
+
So, first a few basics: When setting up a display platform in ESPHome there will be a configuration
option called ``lambda:`` which will be called every time ESPHome wants to re-render the display.
In each cycle, the display is automatically cleared before the lambda is executed. You can disable
@@ -72,7 +72,7 @@ x always represents the horizontal axis (width) and y the vertical axis (height)
the rendering engine is always first specify the ``x`` coordinate and then the ``y`` coordinate.
Basic Shapes
-************
+------------
Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles
and circles:
@@ -101,6 +101,13 @@ and circles:
// and a filled triangle !
it.filled_triangle(125, 5, 105, 25, 150, 50);
+ // Regular Polygons? Let's draw the outline of a pointy-topped hexagon inscribed in a circle
+ // centered on [x1=100,y1=100] with a radius of 50
+ it.regular_polygon(100, 100, 50, EDGES_HEXAGON);
+ // and a filled flat-topped octagon!
+ it.filled_regular_polygon(200, 200, 50, EDGES_OCTAGON, VARIATION_FLAT_TOP);
+ // Need to rotate the polygon, or retrieve the coordinates of its vertices? Check the API!
+
All the above methods can optionally also be called with an argument at the end which specifies in which
color to draw. For monochrome displays, only ``COLOR_ON`` (the default if color is not given) and ``COLOR_OFF`` are supported.
@@ -152,110 +159,14 @@ Additionally, you have access to two helper methods which will fetch the width a
You can view the full API documentation for the rendering engine in the "API Reference" in the See Also section.
-.. _display-fonts:
-
-Fonts
-*****
-
-The rendering engine also has a powerful font drawer which integrates seamlessly into ESPHome.
-Whereas in most Arduino display projects you have to use one of a few pre-defined fonts in very
-specific sizes, with ESPHome you have the option to use **any** TrueType (``.ttf``) font file
-at **any** size, as well as fixed-size `PCF `_ and `BDF `_ bitmap fonts! Granted the reason for it is
-actually not having to worry about the licensing of font files :)
-
-To use fonts you first have to define a font object in your ESPHome configuration file. Just grab
-a ``.ttf``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example,
-inside a ``fonts`` folder next to your configuration file.
-
-Next, create a ``font:`` section in your configuration:
-
-.. code-block:: yaml
-
- font:
- - file: "fonts/Comic Sans MS.ttf"
- id: my_font
- size: 20
-
- # gfonts://family[@weight]
- - file: "gfonts://Roboto"
- id: roboto
- size: 20
-
- - file:
- type: gfonts
- family: Roboto
- weight: 900
- id: font2
- size: 16
-
- - file: "fonts/tom-thumb.bdf"
- id: tomthumb
-
- - file: 'gfonts://Material+Symbols+Outlined'
- id: icon_font_50
- size: 50
- glyphs: ["\U0000e425"] # mdi-timer
-
- display:
- # ...
-
-Configuration variables:
-
-- **file** (**Required**): The path (relative to where the .yaml file is) of the font
- file. You can use the ``gfonts://`` short form to use Google Fonts, or use the below structure:
-
- - **type** (**Required**, string): Can be ``gfonts`` or ``local``.
-
- **Google Fonts**:
-
- Each Google Font will be downloaded once and cached for future use. This can also be used to download Material
- Symbols or Icons as in the example above.
-
- - **family** (**Required**, string): The name of the Google Font family.
- - **weight** (*Optional*, enum): The weight of the font. Can be either the text name or the integer value:
-
- - **thin**: 100
- - **extra-light**: 200
- - **light**: 300
- - **regular**: 400 (**default**)
- - **medium**: 500
- - **semi-bold**: 600
- - **bold**: 700
- - **extra-bold**: 800
- - **black**: 900
-
- - **italic** (*Optional*, boolean): Whether the font should be italic.
-
- **Local Fonts**:
-
- - **path** (**Required**, string): The path (relative to where the .yaml file is) of the TrueType or bitmap font file.
-
-- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the font later
- in your display code.
-- **size** (*Optional*, int): The size of the font in pt (not pixel!).
- If you want to use the same font in different sizes, create two font objects. Note: *size* is ignored
- by bitmap fonts. Defaults to ``20``.
-- **glyphs** (*Optional*, list): A list of characters you plan to use. Only the characters you specify
- here will be compiled into the binary. Adjust this if you need some special characters or want to
- reduce the size of the binary if you don't plan to use some glyphs. The items in the list can also
- be more than one character long if you for example want to use font ligatures. Defaults to
- ``!"%()+=,-_.:°/?0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz``.
-
-
-.. note::
-
- To use fonts you will need to have the python ``pillow`` package installed, as ESPHome uses that package
- to translate the TrueType and bitmap font files into an internal format. If you're running this as a Home Assistant
- add-on or with the official ESPHome docker image, it should already be installed. Otherwise you need
- to install it using
- ``pip install "pillow==10.1.0"``.
-
.. _display-static_text:
Drawing Static Text
-*******************
+-------------------
-In your display code, you can render static text by referencing the font and just entering your string:
+To be able to display text, you need to prepare some fonts. ESPHome's :ref:`font renderer ` allows you to use OpenType/TrueType/Bitmap fonts for your texts. This is very flexiblle because you can prepare various sets of fonts at different sizes with a different number of glyphs which is extremely convenient when we're talking about flash space.
+
+In your display code, you can render static text by referencing the font and just entering your string enclosed in double quotes:
.. code-block:: yaml
@@ -296,11 +207,21 @@ As with basic shapes, you can also specify a color for the text:
// Syntax is always: it.print(, , , [color=COLOR_ON], [align=TextAlign::TOP_LEFT], );
it.print(0, 0, id(my_font), COLOR_ON, "Left aligned");
+In case of fonts rendered at higher bit depths, the background color has to be specified after the text in order for antialiasing to work:
+
+.. code-block:: yaml
+
+ display:
+ - platform: ...
+ # ...
+ lambda: |-
+ // Syntax is always: it.print(, , , [color=COLOR_ON], [align], , [color=COLOR_OFF]);
+ it.print(0, 0, id(my_font_with_icons), COLOR_ON, TextAlign::CENTER, "Just\U000f05d4here. Already\U000F02D1this.", COLOR_OFF);
.. _display-printf:
Formatted Text
-**************
+--------------
Static text by itself is not too impressive. What we really want is to display *dynamic* content like sensor values
on the display!. That's where ``printf`` comes in. ``printf`` is a formatting engine from the C era and ESPHome
@@ -350,7 +271,7 @@ Another interesting format string is ``%7.2f``, which would become the right-jus
- ``.2`` - round the decimal number to ``2`` digits after the decimal point.
- ``f`` - specifier: f(loat).
-You can even have as many format strings as you want in a single printf call. Just make sure the put the
+You can even have as many formatted items as you want in a single printf call. Just make sure the put the
arguments after the format string in the right order.
.. code-block:: yaml
@@ -372,6 +293,19 @@ To display a text string from a ``text_sensor``, append ``.c_str()`` to the end
lambda: |-
it.printf(0, 0, id(my_font), "Text to follow: %s", id(template_text).state.c_str());
+
+When using anti-aliased fonts you will probably need to specify the color to draw the characters, and the background
+color to mix in for anti-aliasing. This requires the full version of `printf`, e.g.:
+
+.. code-block:: yaml
+
+ display:
+ - platform: ...
+ # ...
+ lambda: |-
+ it.printf(10, 100, id(roboto), Color(0x123456), COLOR_OFF, display::TextAlign::BASELINE, "%f", id(heap_free).state);
+
+
The last printf tip for use in displays I will discuss here is how to display binary sensor values. You
*could* of course just check the state with an ``if`` statement as the first few lines in the example below, but if
you want to be efficient you can use an *inline if* too. With the ``%s`` print specifier you can tell it to
@@ -404,14 +338,14 @@ use any string you pass it, like ``"ON"`` or ``"OFF"``.
.. _display-strftime:
Displaying Time
-***************
+---------------
You can display current time using a time component. Please see the example :ref:`here `.
.. _clipping:
Screen Clipping
-***************
+---------------
Screen clipping is a new set of methods since version 2023.2.0 of esphome. It could be useful when you just want to show
a part of an image or make sure that what you draw on the screen does not go outside a specific region on the screen.
@@ -463,12 +397,10 @@ With ``get_clipping();`` you get a ``Rect`` object back with the latest set clip
With ``is_clipping();`` tells you if clipping is activated.
-
-
.. _config-color:
Color
-*****
+-----
When using RGB-capable displays in ESPHome you may wish to use custom colors.
A ``color`` component exists for just this purpose:
@@ -518,7 +450,7 @@ RGB displays use red, green, and blue, while grayscale displays may use white.
.. _display-graphs:
Graph Component
-***************
+---------------
You can display a graph of a sensor value(s) using this component. The states used for the graph are stored in
memory at the time the sensor updates and will be lost when the device reboots.
@@ -631,8 +563,11 @@ And then later in code:
- Axis labels are currently not possible without manually placing them.
- The grid and border color is set with it.graph(), while the traces are defined separately.
+
+.. _display-qrcode:
+
QR Code Component
-*****************
+-----------------
Use this component to generate a QR-code containing a string on the device, which can then be drawn on compatible displays.
@@ -667,8 +602,11 @@ To draw the QR-code, call the ``it.qr_code`` function from your render lambda:
// Draw the QR-code at position [x=50,y=0] with white color and a 2x scale
it.qr_code(50, 0, id(homepage_qr), Color(255,255,255), 2);
+
+.. _display-image:
+
Images
-******
+------
Use this component to store graphical images on the device, you can then draw the images on compatible displays.
@@ -783,7 +721,7 @@ You can also use this to invert images in two colors display, use ``COLOR_OFF``
as the additional parameters.
Animation
-*********
+---------
Allows to use animated images on displays. Animation inherits all options from the image component.
It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_frame()`` to change the shown picture of a gif.
@@ -984,7 +922,7 @@ Troubleshooting
---------------
Color Test Pattern
-******************
+------------------
If you're experiencing issues with your color display, the script below can help you to identify what might be wrong.
It will show 3 color bars in **RED**, **GREEN** and **BLUE**. To help the graphics display team determine
@@ -1031,6 +969,7 @@ See Also
--------
- :apiref:`display/display_buffer.h`
+- :ref:`Fonts `
- :ghedit:`Edit`
.. toctree::
diff --git a/components/display/qspi_amoled.rst b/components/display/qspi_amoled.rst
new file mode 100644
index 000000000..54e277b82
--- /dev/null
+++ b/components/display/qspi_amoled.rst
@@ -0,0 +1,186 @@
+Quad SPI AMOLED Displays
+========================
+
+.. seo::
+ :description: Instructions for setting up quad SPI AMOLED displays.
+ :image: t4-s3.jpg
+
+.. _qspi_amoled:
+
+Models
+------
+This display driver supports AMOLED displays with quad SPI interfaces.
+
+This driver has been tested with the following displays:
+
+ - Lilygo T4-S3
+ - Lilygo T-Display S3 AMOLED
+
+Usage
+-----
+This component requires an ESP32 and the use of
+ESP-IDF. PSRAM is a requirement due to the size of the display buffer. A :ref:`quad SPI bus ` interface must be configured.
+
+.. figure:: images/t4-s3.jpg
+ :align: center
+ :width: 75.0%
+
+ Lilygo T4-S3
+
+.. figure:: images/t-display-amoled.jpg
+ :align: center
+ :width: 75.0%
+
+ Lilygo T-Display S3 AMOLED
+
+
+.. code-block:: yaml
+
+ # Example minimal configuration entry
+
+ display:
+ - platform: qspi_amoled
+ model: RM690B0
+ data_rate: 80MHz
+ spi_mode: mode0
+ dimensions:
+ width: 450
+ height: 600
+ offset_width: 16
+ color_order: rgb
+ invert_colors: false
+ brightness: 255
+ cs_pin: 11
+ reset_pin: 13
+ enable_pin: 9
+
+
+Configuration variables:
+************************
+
+- **model** (**Required**): One of ``RM67162`` or ``RM690B0``.
+- **cs_pin** (**Required**, :ref:`Pin Schema `): The chip select pin.
+- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin.
+- **enable_pin** (*Optional*, :ref:`Pin Schema `): The display enable pin.
+- **brightness** (*Optional*, int): A brightness value in the range 0-255
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
+- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
+ 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_order** (*Optional*): Should be one of ``rgb`` (default) or ``bgr``.
+- **dimensions** (**Required**): Dimensions of the screen, specified either as *width* **x** *height* (e.g ``320x240``) or with separate config keys.
+ - **height** (**Required**, int): Specifies height of display in pixels.
+ - **width** (**Required**, int): Specifies width of display.
+ - **offset_width** (*Optional*, int): Specify an offset for the x-direction of the display, typically used when a display is smaller than the maximum supported by the driver chip. Default is 0
+ - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0.
+
+- **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``.
+- **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. This option cannot be used with ``rotation``.
+
+ - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes.
+ - **mirror_x** (*Optional*, boolean): If true, mirror the x axis.
+ - **mirror_y** (*Optional*, boolean): If true, mirror the y axis.
+- **data_rate** (*Optional*): Set the data rate of the SPI interface to the display. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz`` (default), ``5MHz``, ``2MHz`` or ``1MHz``.
+- **spi_mode** (*Optional*): Set the mode for the SPI interface to the display. Default is ``MODE0``.
+- **invert_colors** (*Optional*): With this boolean option you can invert the display colors.
+- **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display.
+ See :ref:`display-engine` for more information.
+
+
+
+Example configurations
+----------------------
+
+
+Lilygo T4-S3
+************
+
+.. code-block:: yaml
+
+ spi:
+ id: quad_spi
+ type: quad
+ clk_pin: 15
+ data_pins: [14, 10, 16, 12]
+
+ i2c:
+ sda: 6
+ scl: 7
+
+ touchscreen:
+ - platform: cst226
+ id: my_touchscreen
+ interrupt_pin: 8
+ reset_pin: 17
+
+ display:
+ - platform: qspi_amoled
+ model: RM690B0
+ data_rate: 80MHz
+ spi_mode: mode0
+ dimensions:
+ width: 450
+ height: 600
+ offset_width: 16
+ color_order: rgb
+ invert_colors: false
+ brightness: 255
+ cs_pin: 11
+ reset_pin: 13
+ enable_pin: 9
+ update_interval: never
+ auto_clear_enabled: false
+
+ psram:
+ mode: octal
+ speed: 80MHz
+
+Lilygo T-Display S3 AMOLED
+**************************
+
+.. code-block:: yaml
+
+ spi:
+ id: quad_spi
+ type: quad
+ clk_pin: 47
+ data_pins:
+ - 18
+ - 7
+ - 48
+ - 5
+
+ i2c:
+ sda: 3
+ scl: 2
+
+ touchscreen:
+ - platform: cst816
+ id: my_touchscreen
+ interrupt_pin:
+ number: 21
+
+ display:
+ - platform: qspi_amoled
+ model: RM67162
+ id: main_lcd
+ dimensions:
+ height: 240
+ width: 536
+ transform:
+ mirror_x: true
+ swap_xy: true
+ color_order: rgb
+ brightness: 255
+ cs_pin: 6
+ reset_pin: 17
+ enable_pin: 38
+
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`qspi_amoled/qspi_amoled.h`
+- :ghedit:`Edit`
diff --git a/components/display/rpi_dpi_rgb.rst b/components/display/rpi_dpi_rgb.rst
new file mode 100644
index 000000000..2b5ae9526
--- /dev/null
+++ b/components/display/rpi_dpi_rgb.rst
@@ -0,0 +1,213 @@
+RPI_DPI_RGB Display Driver
+===========================
+
+.. seo::
+ :description: Instructions for setting up 16 bit "RPI_DPI_RGB" parallel displays
+ :image: waveshare_touch-s3.jpg
+
+.. _rpi_dpi_rgb:
+
+Models
+------
+This display driver supports displays with 16 bit parallel interfaces, often referred to as "RPI_DPI_RGB" type.
+These have a parallel interface but no SPI interface and require no configuration of the driver chip.
+
+This driver has been tested with the following displays:
+
+ - Waveshare ESP32-S3-Touch-LCD-4.3
+ - Makerfabs 4.3" display (Sunton)
+
+Usage
+-----
+This component requires an ESP32 (usually an ESP32-S3 because of the number of GPIO pins required) and the use of
+ESP-IDF. PSRAM is a requirement due to the size of the display buffer.
+
+.. figure:: images/waveshare_touch-s3.jpg
+ :align: center
+ :width: 75.0%
+
+ Waveshare ESP32-S3 Touch 4.3
+
+
+.. code-block:: yaml
+
+
+ # Example minimal configuration entry
+ display:
+ - platform: rpi_dpi_rgb
+ id: rpi_disp
+ dimensions:
+ width: 800
+ height: 480
+ de_pin: REPLACE_ME
+ hsync_pin: REPLACE_ME
+ vsync_pin: REPLACE_ME
+ pclk_pin: REPLACE_ME
+
+ data_pins:
+ red:
+ - XX #r1
+ - XX #r2
+ - XX #r3
+ - XX #r4
+ - XX #r5
+ green:
+ - XX #g0
+ - XX #g1
+ - XX #g2
+ - XX #g3
+ - XX #g4
+ - XX #g5
+ blue:
+ - XX #b1
+ - XX #b2
+ - XX #b3
+ - XX #b4
+ - XX #b5
+
+Configuration variables:
+************************
+
+- **data_pins** (**Required**) A list of pins used for the databus. Specified in 3 groups:
+
+ - **red**: (**Required**, :ref:`Pin Schema `) Exactly 5 pin numbers for the red databits, listed from least to most significant bit.
+ - **green**: (**Required**, :ref:`Pin Schema `) Exactly 6 pin numbers for the green databits, listed from least to most significant bit.
+ - **blue**: (**Required**, :ref:`Pin Schema `) Exactly 5 pin numbers for the blue databits, listed from least to most significant bit.
+- **de_pin** (**Required**, :ref:`Pin Schema `): The DE pin
+- **pclk_pin** (**Required**, :ref:`Pin Schema `): The PCLK pin.
+- **hsync_pin** (**Required**, :ref:`Pin Schema `): The Horizontal sync pin.
+- **vsync_pin** (**Required**, :ref:`Pin Schema `): The Vertical sync pin.
+- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin.
+- **hsync_pulse_width** (*Optional*, int): The horizontal sync pulse width.
+- **hsync_front_porch** (*Optional*, int): The horizontal front porch length.
+- **hsync_back_porch** (*Optional*, int): The horizontal back porch length.
+- **vsync_pulse_width** (*Optional*, int): The vertical sync pulse width.
+- **vsync_front_porch** (*Optional*, int): The vertical front porch length.
+- **vsync_back_porch** (*Optional*, int): The vertical back porch length.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
+- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
+ 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_order** (*Optional*): Should be one of ``bgr`` (default) or ``rgb``.
+- **dimensions** (**Required**): Dimensions of the screen, specified either as *width* **x** *height* (e.g ``320x240``) or with separate config keys.
+ - **height** (**Required**, int): Specifies height of display in pixels.
+ - **width** (**Required**, int): Specifies width of display.
+ - **offset_width** (*Optional*, int): Specify an offset for the x-direction of the display, typically used when an LCD is smaller than the maximum supported by the driver chip. Default is 0
+ - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0.
+
+- **pclk_frequency** (*Optional*): Set the pixel clock speed. Default is 16MHz.
+- **pclk_inverted** (*Optional* bool): If the pclk is active negative (default is True)
+- **invert_colors** (*Optional*): With this boolean option you can invert the display colors. **Note** some of the displays have this option set automatically to true and can't be changed.
+- **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``.
+- **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display.
+ See :ref:`display-engine` for more information.
+
+
+The horizontal and vertical ``pulse_width``, ``front_porch`` and ``back_porch`` values are optional, but may require
+changing for a specific display. Refer to the manufacturer's sample code for suitable values. These specify timing
+requirements for the display.
+
+Example configurations
+----------------------
+
+
+Waveshare ESP32-S3 Touch 4.3
+****************************
+
+.. code-block:: yaml
+
+ display:
+ - platform: rpi_dpi_rgb
+ auto_clear_enabled: false
+ color_order: RGB
+ pclk_frequency: 16MHz
+ dimensions:
+ width: 800
+ height: 480
+ de_pin:
+ number: 5
+ hsync_pin:
+ number: 46
+ ignore_strapping_warning: true
+ vsync_pin:
+ number: 3
+ ignore_strapping_warning: true
+ pclk_pin: 7
+ hsync_back_porch: 30
+ hsync_front_porch: 210
+ hsync_pulse_width: 30
+ vsync_back_porch: 4
+ vsync_front_porch: 4
+ vsync_pulse_width: 4
+ data_pins:
+ red:
+ - 1 #r3
+ - 2 #r4
+ - 42 #r5
+ - 41 #r6
+ - 40 #r7
+ blue:
+ - 14 #b3
+ - 38 #b4
+ - 18 #b5
+ - 17 #b6
+ - 10 #b7
+ green:
+ - 39 #g2
+ - 0 #g3
+ - 45 #g4
+ - 48 #g5
+ - 47 #g6
+ - 21 #g7
+
+
+Makerfabs 4.3" 800x480 display
+******************************
+
+.. code-block:: yaml
+
+ display:
+ - platform: rpi_dpi_rgb
+ update_interval: never
+ auto_clear_enabled: false
+ id: rpi_display
+ color_order: RGB
+ rotation: 90
+ dimensions:
+ width: 800
+ height: 480
+ de_pin:
+ number: 40
+ hsync_pin: 39
+ vsync_pin: 41
+ pclk_pin: 42
+ data_pins:
+ red:
+ - 45 #r1
+ - 48 #r2
+ - 47 #r3
+ - 21 #r4
+ - 14 #r5
+ green:
+ - 5 #g0
+ - 6 #g1
+ - 7 #g2
+ - 15 #g3
+ - 16 #g4
+ - 4 #g5
+ blue:
+ - 8 #b1
+ - 3 #b2
+ - 46 #b3
+ - 9 #b4
+ - 1 #b5
+
+
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`rpi_dpi_rgb/rpi_dpi_rgb.h`
+- :ghedit:`Edit`
diff --git a/components/display/st7701s.rst b/components/display/st7701s.rst
new file mode 100644
index 000000000..ec217ad31
--- /dev/null
+++ b/components/display/st7701s.rst
@@ -0,0 +1,199 @@
+ST7701S Display Driver
+======================
+
+.. seo::
+ :description: Instructions for setting up ST7701S 16 bit "RGB" parallel displays
+ :image: indicator.jpg
+
+.. _st7701s:
+
+Models
+------
+This display driver supports displays with 16 bit parallel interfaces, often referred to as "RGB". It currently
+supports the ST7701S chip.
+
+This driver has been tested with the following displays:
+
+ - Seeed Sensecap Indicator
+ - Makerfabs 4" display
+
+Usage
+-----
+This component requires an ESP32 (usually an ESP32-S3 because of the number of GPIO pins required) and the use of
+ESP-IDF. PSRAM is a requirement due to the size of the display buffer.
+
+.. figure:: images/indicator.jpg
+ :align: center
+ :width: 75.0%
+
+ Sensecap Indicator display
+
+
+.. code-block:: yaml
+
+ # Example minimal configuration entry
+ display:
+ - platform: st7701s
+ dimensions:
+ width: 480
+ height: 480
+ cs_pin: REPLACE_ME
+ reset_pin: REPLACE_ME
+ de_pin: REPLACE_ME
+ hsync_pin: REPLACE_ME
+ vsync_pin: REPLACE_ME
+ pclk_pin: REPLACE_ME
+ # Replace XX with the correct pin number
+
+ data_pins:
+ red:
+ - XX #r1
+ - XX #r2
+ - XX #r3
+ - XX #r4
+ - XX #r5
+ green:
+ - XX #g0
+ - XX #g1
+ - XX #g2
+ - XX #g3
+ - XX #g4
+ - XX #g5
+ blue:
+ - XX #b1
+ - XX #b2
+ - XX #b3
+ - XX #b4
+ - XX #b5
+
+Configuration variables:
+************************
+
+- **init_sequence** (*Optional*, A list of byte arrays): Specifies the init sequence for the display
+- **data_pins** (**Required**): A list of pins used for the databus. Specified in 3 groups.
+
+ - **red**: (**Required**, :ref:`Pin Schema `) Exactly 5 pin numbers for the red databits, listed from least to most significant bit.
+ - **green**: (**Required**, :ref:`Pin Schema `) Exactly 6 pin numbers for the green databits, listed from least to most significant bit.
+ - **blue**: (**Required**, :ref:`Pin Schema `) Exactly 5 pin numbers for the blue databits, listed from least to most significant bit.
+- **de_pin** (**Required**, :ref:`Pin Schema `): The DE pin.
+- **dc_pin** (*Optional*, :ref:`Pin Schema `): The DC pin.
+- **pclk_pin** (**Required**, :ref:`Pin Schema `): The PCLK pin.
+- **hsync_pin** (**Required**, :ref:`Pin Schema `): The Horizontal sync pin.
+- **vsync_pin** (**Required**, :ref:`Pin Schema `): The Vertical sync pin.
+- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin.
+- **hsync_pulse_width** (*Optional*, int): The horizontal sync pulse width.
+- **hsync_front_porch** (*Optional*, int): The horizontal front porch length.
+- **hsync_back_porch** (*Optional*, int): The horizontal back porch length.
+- **vsync_pulse_width** (*Optional*, int): The vertical sync pulse width.
+- **vsync_front_porch** (*Optional*, int): The vertical front porch length.
+- **vsync_back_porch** (*Optional*, int): The vertical back porch length.
+- **pclk_frequency** (*Optional*): Set the pixel clock speed. Default is 8MHz.
+- **pclk_inverted** (*Optional* bool): If the pclk is active negative (default is True)
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
+- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
+ 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_order** (*Optional*): Should be one of ``bgr`` (default) or ``rgb``.
+- **dimensions** (**Required**): Dimensions of the screen, specified either as *width* **x** *height* (e.g ``320x240``) or with separate config keys.
+
+ - **height** (**Required**, int): Specifies height of display in pixels.
+ - **width** (**Required**, int): Specifies width of display.
+ - **offset_width** (*Optional*, int): Specify an offset for the x-direction of the display, typically used when an LCD is smaller than the maximum supported by the driver chip. Default is 0
+ - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0.
+
+- **data_rate** (*Optional*): Set the data rate of the SPI interface to the display. One of ``80MHz``, ``40MHz``,
+ ``20MHz``, ``10MHz``, ``5MHz``, ``2MHz``, ``1MHz`` (default), ``200kHz``, ``75kHz`` or ``1kHz``.
+- **spi_mode** (*Optional*): Set the mode for the SPI interface to the display. Default is ``MODE0`` but some displays require ``MODE3``.
+- **invert_colors** (*Optional*): With this boolean option you can invert the display colors. **Note** some of the displays have this option set automatically to true and can't be changed.
+- **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``. This option cannot be used with ``transform``.
+- **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. This option cannot be used with ``rotation``.
+
+ - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes.
+ - **mirror_x** (*Optional*, boolean): If true, mirror the x axis.
+ - **mirror_y** (*Optional*, boolean): If true, mirror the y axis.
+- **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display.
+ See :ref:`display-engine` for more information.
+
+
+**Note:** To rotate the display in hardware use one of the following combinations:
+
+ - 90 degrees - use ``swap_xy`` with ``mirror_x``
+ - 180 degrees - use ``mirror_x`` with ``mirror_y``
+ - 270 degrees - use ``swap_xy`` with ``mirror_y``
+
+The horizontal and vertical ``pulse_width``, ``front_porch`` and ``back_porch`` values are optional, but may require
+changing for a specific display. Refer to the manufacturer's sample code for suitable values. These specify timing
+requirements for the display.
+
+The ``init_sequence`` requires a list of elements, one of which may be a single integer selecting a canned init
+sequence (the default and currently the only sequence is 1), the remainder must be byte arrays providing additional
+init commands, each consisting of a command byte followed by zero or more data bytes.
+
+These will be collected and sent to the display via SPI during initialisation.
+
+Example configurations
+----------------------
+
+Seeed Sensecap Indicator
+************************
+
+.. code-block:: yaml
+
+ display:
+ - platform: st7701s
+ auto_clear_enabled: false
+ update_interval: never
+ spi_mode: MODE3
+ color_order: RGB
+ dimensions:
+ width: 480
+ height: 480
+ invert_colors: true
+ transform:
+ mirror_x: true
+ mirror_y: true
+ cs_pin:
+ pca9554: p_c_a
+ number: 4
+ reset_pin:
+ pca9554: p_c_a
+ number: 5
+ de_pin: 18
+ hsync_pin: 16
+ vsync_pin: 17
+ pclk_pin: 21
+ init_sequence:
+ - 1 # select canned init sequence number 1
+ - [ 0xE0, 0x1F ] # Set sunlight readable enhancement
+ data_pins:
+ red:
+ - 4 #r1
+ - 3 #r2
+ - 2 #r3
+ - 1 #r4
+ - 0 #r5
+ green:
+ - 10 #g0
+ - 9 #g1
+ - 8 #g2
+ - 7 #g3
+ - 6 #g4
+ - 5 #g5
+ blue:
+ - 15 #b1
+ - 14 #b2
+ - 13 #b3
+ - 12 #b4
+ - 11 #b5
+ lambda: |-
+ it.fill(COLOR_BLACK);
+ it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!");
+
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`st7701s/st7701s.h`
+- :ghedit:`Edit`
diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst
index 43c8cb83e..44a194a81 100644
--- a/components/display/waveshare_epaper.rst
+++ b/components/display/waveshare_epaper.rst
@@ -7,8 +7,9 @@ Waveshare E-Paper Display
The ``waveshare_epaper`` display platform allows you to use
some E-Paper displays sold by `Waveshare `__
-with ESPHome. The 2.13" `TTGO module `__ with an ESP32 on the board
-is supported as well. Depending on your specific revision of the board you might need to try out the ``-b73`` or ``-b1``
+with ESPHome. The 2.13" `TTGO module `__ and the
+`Waveshare Cloud Module `__ with an ESP32
+on the board are supported as well. Depending on your specific revision of the TTGO board you might need to try out the ``-b73`` or ``-b1``
version (see below).
The 1.54" `Good Display gdew0154m09 `__
as used in the `M5Stack Core Ink `__
@@ -88,6 +89,7 @@ Configuration variables:
- ``2.13in-ttgo-b74`` - T5_V2.3.1 with B74 display tested
- ``2.13in-ttgo-b1`` - T5_V2.3 with B1 display tested
- ``2.13in-ttgo-dke`` - T5_V2.3 with DKE group display (DEPG0213BN) tested
+ - ``2.13inv2`` - 2.13in V2 display (Pico e-Paper 2.13v2 and Cloud Module)
- ``2.13inv3`` - 2.13in V3 display (Pico e-Paper 2.13v3)
- ``2.70in`` - currently not working with the HAT Rev 2.1 version
- ``2.70inv2``
@@ -95,6 +97,7 @@ Configuration variables:
- ``2.70in-bv2`` - Black/White/Red
- ``2.90in``
- ``2.90inv2``
+ - ``2.90inv2-r2`` - 2.9in V2 display, but with different initialization and full/partial display refresh management than ``2.90inv2``
- ``2.90in-b`` - B/W rendering only
- ``2.90in-bV3`` - B/W rendering only
- ``4.20in``
@@ -119,13 +122,13 @@ Configuration variables:
- **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.
Make sure you pull this pin high (by connecting it to 3.3V with a resistor) if not connected to a GPIO pin.
- The B74 display variant requires the reset pin.
+ The 2.13" B74 and V2 display variants require the reset pin.
- **rotation** (*Optional*): Set the rotation of the display. Everything you draw in ``lambda:`` will be rotated
by this option. One of ``0°`` (default), ``90°``, ``180°``, ``270°``.
- **full_update_every** (*Optional*, int): E-Paper displays have two modes of switching to the next image: A partial
update that only changes the pixels that have changed and a full update mode that first clears the entire display
and then re-draws the image. The former is much quicker and nicer, but every so often a full update needs to happen
- because artifacts accumulate. On the ``1.54in``, ``1.54inv2``, ``2.13in``, ``2.90in`` and ``2.90inv2`` models you have the option to switch only
+ because artifacts accumulate. On the ``1.54in``, ``1.54inv2``, ``2.13in``, ``2.13inv2``, ``2.90in`` and ``2.90inv2`` models, you have the option to only
do a full-redraw every x-th time using this option. Defaults to ``30`` on the described models and a full update for
all other models.
- **reset_duration** (*Optional*, :ref:`config-time`): Duration for the display reset operation. Defaults to ``200ms``.
diff --git a/components/esphome.rst b/components/esphome.rst
index 80d42af5d..ec0217c50 100644
--- a/components/esphome.rst
+++ b/components/esphome.rst
@@ -40,8 +40,9 @@ Advanced options:
- **build_path** (*Optional*, string): Customize where ESPHome will store the build files
for your node. By default, ESPHome puts the PlatformIO project it uses to build the
- firmware in the ``.esphome/build/`` directory, but you can customize this
- behavior using this option.
+ firmware in the ``.esphome/build/`` (or into path from ``ESPHOME_BUILD_PATH`` environment variable if specified) directory,
+ but you can customize this behavior using this option. Official docker image automatically use `/build` folder
+ as default one in case it is mounted to it.
- **platformio_options** (*Optional*, mapping): Additional options to pass over to PlatformIO in the
platformio.ini file. See :ref:`esphome-platformio_options`.
- **includes** (*Optional*, list of files): A list of C/C++ files to include in the main (auto-generated) sketch file
@@ -57,6 +58,10 @@ Advanced options:
- **name** (**Required**, string): Name of the project
- **version** (**Required**, string): Version of the project
+ - **on_update** (*Optional*, :ref:`Automation `): An automation to perform when the device firmware is updated.
+ This compares the above ``version`` field with the ``version`` that was in the previous firmware
+ as long as the ``name`` matches.
+ The ``version`` is stored in flash memory when the firmware is first run for future comparisons.
- **min_version** (*Optional*, string): The minimum ESPHome version required to compile this configuration.
See :ref:`esphome-min_version`.
- **compile_process_limit** (*Optional*, int): The maximum number of simultaneous compile processes to run.
@@ -324,15 +329,15 @@ The same procedure can be done for changing the static IP of a device.
Adding the MAC address as a suffix to the device name
-----------------------------------------------------
-Using ``name_add_mac_suffix`` allows :doc:`creators ` to
-provision multiple devices at the factory with a single firmware and still
+Using ``name_add_mac_suffix`` allows :doc:`creators ` to
+provision multiple devices at the factory with a single firmware and still
have unique identification for customer installs.
.. note::
- End users will need to create an individual YAML config file if they want to OTA update the
+ End users will need to create an individual YAML config file if they want to OTA update the
devices in the future. Creators can facilitate this process by providing ``dashboard_import`` URL
- for end users. This allows them to easily update their devices as new features are made available
+ for end users. This allows them to easily update their devices as new features are made available
upstream.
diff --git a/components/ethernet.rst b/components/ethernet.rst
index 32ca43ed3..306dcd098 100644
--- a/components/ethernet.rst
+++ b/components/ethernet.rst
@@ -14,7 +14,7 @@ This component and the Wi-Fi component may **not** be used simultaneously, even
.. code-block:: yaml
- # Example configuration entry
+ # Example configuration entry for RMII chips
ethernet:
type: LAN8720
mdc_pin: GPIO23
@@ -28,6 +28,18 @@ This component and the Wi-Fi component may **not** be used simultaneously, even
gateway: 10.0.0.1
subnet: 255.255.255.0
+.. code-block:: yaml
+
+ # Example configuration entry for SPI chips
+ ethernet:
+ type: W5500
+ clk_pin: GPIO19
+ mosi_pin: GPIO21
+ miso_pin: GPIO23
+ cs_pin: GPIO18
+ interrupt_pin: GPIO36
+ reset_pin: GPIO22
+
Configuration variables:
------------------------
@@ -35,13 +47,17 @@ Configuration variables:
Supported chipsets are:
- - ``LAN8720``
- - ``RTL8201``
- - ``DP83848``
- - ``IP101``
- - ``JL1101``
- - ``KSZ8081``
- - ``KSZ8081RNA``
+ - ``LAN8720`` (RMII)
+ - ``RTL8201`` (RMII)
+ - ``DP83848`` (RMII)
+ - ``IP101`` (RMII)
+ - ``JL1101`` (RMII)
+ - ``KSZ8081`` (RMII)
+ - ``KSZ8081RNA`` (RMII)
+ - ``W5500`` (SPI)
+
+RMII configuration variables:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **mdc_pin** (**Required**, :ref:`config-pin`): The MDC pin of the board.
Usually this is ``GPIO23``.
@@ -58,6 +74,24 @@ Configuration variables:
- **phy_addr** (*Optional*, int): The PHY addr type of the Ethernet controller. Defaults to 0.
- **power_pin** (*Optional*, :ref:`Pin Schema `): The pin controlling the
power/reset status of the Ethernet controller. Leave unspecified for no power pin (default).
+
+SPI configuration variables:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- **clk_pin** (**Required**, :ref:`config-pin`): The SPI clock pin.
+- **mosi_pin** (**Required**, :ref:`config-pin`): The SPI MOSI pin.
+- **miso_pin** (**Required**, :ref:`config-pin`): The SPI MISO pin.
+- **cs_pin** (**Required**, :ref:`config-pin`): The SPI chip select pin.
+- **interrupt_pin** (*Optional*, :ref:`config-pin`): The interrupt pin.
+- **reset_pin** (*Optional*, :ref:`config-pin`): The reset pin.
+- **clock_speed** (*Optional*, float): The SPI clock speed.
+ Any frequency between `8Mhz` and `80Mhz` is allowed, but the nearest integer division
+ of `80Mhz` is used, i.e. `16Mhz` (`80Mhz` / 5) is used when `15Mhz` is configured.
+ Default: `26.67Mhz`.
+
+Advanced common configuration variables:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
- **manual_ip** (*Optional*): Manually configure the static IP of the node.
- **static_ip** (**Required**, IPv4 address): The static IP of your node.
@@ -83,6 +117,10 @@ Configuration variables:
clock signal that will not travel reliably over these types of connections. For more
information and wiring details refer to the link in the *See also* section.
+.. note::
+
+ SPI based chips do *not* use :doc:`spi`. This means that SPI pins can't be shared with other devices.
+
Configuration examples
----------------------
diff --git a/components/fan/index.rst b/components/fan/index.rst
index 7dfdb0ef6..415e3d562 100644
--- a/components/fan/index.rst
+++ b/components/fan/index.rst
@@ -73,14 +73,20 @@ MQTT options:
Automation triggers:
+- **on_state** (*Optional*, :ref:`Action `): An automation to perform
+ when the fan state is changed. See :ref:`fan-on_state_trigger`.
- **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform
when the fan is turned on. See :ref:`fan-on_turn_on_off_trigger`.
- **on_turn_off** (*Optional*, :ref:`Action `): An automation to perform
when the fan is turned off. See :ref:`fan-on_turn_on_off_trigger`.
+- **on_direction_set** (*Optional*, :ref:`Action `): An automation to perform
+ when the fan direction is changed. See :ref:`fan-on_direction_set_trigger`.
+- **on_oscillating_set** (*Optional*, :ref:`Action `): An automation to perform
+ when the fan oscillating state is changed. See :ref:`fan-on_oscillating_set_trigger`.
- **on_speed_set** (*Optional*, :ref:`Action `): An automation to perform
- when the fan speed is set/changed. See :ref:`fan-on_speed_set_trigger`.
+ when the fan speed is changed. See :ref:`fan-on_speed_set_trigger`.
- **on_preset_set** (*Optional*, :ref:`Action `): An automation to perform
- when the fan preset mode is set/changed. See :ref:`fan-on_preset_set_trigger`.
+ when the fan preset mode is changed. See :ref:`fan-on_preset_set_trigger`.
.. _fan-toggle_action:
@@ -175,6 +181,24 @@ This :ref:`condition ` passes if the given fan is on or off.
then:
- script.execute: my_script
+.. _fan-on_state_trigger:
+
+``fan.on_state`` Trigger
+------------------------
+
+This trigger is activated each time the fan state is changed. It will fire when the state is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+A pointer to the ``Fan`` is available as a variable called ``x``.
+
+.. code-block:: yaml
+
+ fan:
+ - platform: speed # or any other platform
+ # ...
+ on_state:
+ - logger.log:
+ format: "Fan State changed! Fan Speed is %d!"
+ args: [ x->speed ]
+
.. _fan-on_turn_on_off_trigger:
``fan.on_turn_on`` / ``fan.on_turn_off`` Trigger
@@ -193,12 +217,49 @@ if a command to turn the fan on or off already matches the current state.
on_turn_off:
- logger.log: "Fan Turned Off!"
+.. _fan-on_direction_set_trigger:
+
+``fan.on_direction_set`` Trigger
+--------------------------------
+
+This trigger is activated each time the fan direction is changed. It will fire when the direction is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+The new direction is available as a variable called ``x``. (``0`` is FORWARD, ``1`` is REVERSE)
+
+.. code-block:: yaml
+
+ fan:
+ - platform: speed # or any other platform
+ # ...
+ on_direction_set:
+ - logger.log:
+ format: "Fan Direction was changed to %s!"
+ args: [ x == 0 ? "FORWARD" : "REVERSE" ]
+
+.. _fan-on_oscillating_set_trigger:
+
+``fan.on_oscillating_set`` Trigger
+----------------------------------
+
+This trigger is activated each time the fan oscillating state is changed. It will fire when the state is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+The new oscillating state is available as a variable called ``x``.
+
+.. code-block:: yaml
+
+ fan:
+ - platform: speed # or any other platform
+ # ...
+ on_oscillating_set:
+ - logger.log:
+ format: "Fan Oscillating State was changed to %s!"
+ args: [ ONOFF(x) ]
+
.. _fan-on_speed_set_trigger:
``fan.on_speed_set`` Trigger
----------------------------
This trigger is activated each time the fan speed is changed. It will fire when the speed is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+The new speed is available as a variable called ``x``.
.. code-block:: yaml
@@ -206,7 +267,9 @@ This trigger is activated each time the fan speed is changed. It will fire when
- platform: speed # or any other platform
# ...
on_speed_set:
- - logger.log: "Fan Speed was changed!"
+ - logger.log:
+ format: "Fan Speed was changed to %d!"
+ args: [ x ]
.. _fan-on_preset_set_trigger:
@@ -214,6 +277,7 @@ This trigger is activated each time the fan speed is changed. It will fire when
-----------------------------
This trigger is activated each time the fan preset mode is changed. It will fire when the preset mode is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+The new mode is available as a variable called ``x``.
.. code-block:: yaml
@@ -221,7 +285,9 @@ This trigger is activated each time the fan preset mode is changed. It will fire
- platform: speed # or any other platform
# ...
on_preset_set:
- - logger.log: "Fan preset mode was changed!"
+ - logger.log:
+ format: "Fan preset mode was changed to %s!"
+ args: [ x.c_str() ]
Lambda calls
------------
diff --git a/components/fan/speed.rst b/components/fan/speed.rst
index 31af9cd27..e23f0b009 100644
--- a/components/fan/speed.rst
+++ b/components/fan/speed.rst
@@ -24,8 +24,7 @@ Configuration variables:
------------------------
- **name** (*Optional*, string): The name for this fan.
-- **output** (*Optional*, :ref:`config-id`): The id of the :ref:`float output