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

Merge branch 'next' into hob2hood_protocol

This commit is contained in:
Mat931 2023-12-20 04:52:27 +00:00 committed by GitHub
parent 38b3f47c82 2544de1052
commit a4fe113388
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
176 changed files with 6046 additions and 682 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/lint.yml vendored
View File

@ -21,7 +21,7 @@ jobs:
steps:
- uses: actions/checkout@v4.1.0
- name: Set up Python 3.8
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: 3.8
- name: Install dependencies

2
Doxygen
View File

@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 2023.11.0-dev
PROJECT_NUMBER = 2024.1.0-dev
# 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

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

2
_static/version
View File

@ -1 +1 @@
2023.11.0-dev
2024.1.0-dev

45
changelog/2023.10.0.rst
View File

@ -34,6 +34,51 @@ A new ``xor`` condition has been added to the automation engine. This condition
when a single condition in the list is true.
Release 2023.10.1 - October 19
------------------------------
- Fix voice_assistant without a speaker :esphomepr:`5558` by :ghuser:`jesserockz`
- esp32_improv add timeout :esphomepr:`5556` by :ghuser:`jesserockz`
- Create IPv4 sockets if ipv6 is not enabled :esphomepr:`5565` by :ghuser:`jesserockz`
- Incorrect ESP32 Strapping PIN Defined :esphomepr:`5563` by :ghuser:`descipher`
Release 2023.10.2 - October 24
------------------------------
- Fix XOR condition :esphomepr:`5567` by :ghuser:`jesserockz`
- Improv Serial support via USB CDC and JTAG :esphomepr:`5559` by :ghuser:`kbx81`
- Publish the `pulse_meter` total when setting the total :esphomepr:`5475` by :ghuser:`TrentHouliston`
- Remove explicit cast for IPAddress :esphomepr:`5574` by :ghuser:`HeMan`
- Set addr type when copy from ip4_addr_t :esphomepr:`5583` by :ghuser:`HeMan`
- fix canbus send config :esphomepr:`5585` by :ghuser:`ssieb`
- Allow set climate preset to NONE :esphomepr:`5588` by :ghuser:`dentra`
Release 2023.10.3 - October 24
------------------------------
- Set IP address `type` only when IPv4 and IPv6 are both enabled :esphomepr:`5595` by :ghuser:`kbx81`
Release 2023.10.4 - October 30
------------------------------
- Update current_based_cover bugfix :esphomepr:`5587` by :ghuser:`rogerbusser`
- Fixes ip include on arduino 2.7.4 :esphomepr:`5620` by :ghuser:`HeMan`
- Fix bug when requesting italic gfonts :esphomepr:`5623` by :ghuser:`dewet22`
- Handle enum type in tuya text_sensor :esphomepr:`5626` by :ghuser:`jesserockz`
Release 2023.10.5 - November 1
------------------------------
- Add connection triggers to api :esphomepr:`5628` by :ghuser:`jesserockz`
- Add on_client_connected and disconnected to voice assistant :esphomepr:`5629` by :ghuser:`jesserockz`
- Ensure that all uses of strncpy in wifi component are safe. :esphomepr:`5636` by :ghuser:`kpfleming`
- Remove some explicit IPAddress casts :esphomepr:`5639` by :ghuser:`HeMan`
Release 2023.10.6 - November 3
------------------------------
- Revert "Ensure that all uses of strncpy in wifi component are safe." :esphomepr:`5662` by :ghuser:`jesserockz`
Breaking changes
----------------

328
changelog/2023.11.0.rst Normal file
View File

@ -0,0 +1,328 @@
ESPHome 2023.11.0 - 15th November 2023
======================================
.. seo::
:description: Changelog for ESPHome 2023.11.0.
:image: /_static/changelog-2023.11.0.png
:author: Jesse Hills
:author_twitter: @jesserockz
.. imgtable::
:columns: 4
Text Core, components/text/index, folder-open.svg, dark-invert
Template Text, components/text/template, description.svg, dark-invert
UART Button, components/button/uart, uart.svg
GREE Climate, components/climate/climate_ir, air-conditioner-ir.svg, dark-invert
DFRobot mmWave Radar, components/dfrobot_sen0395, dfrobot_sen0395.jpg
LD2420, components/sensor/ld2420, ld2420.jpg
Qwiic PIR Motion, components/binary_sensor/qwiic_pir, qwiic_pir.jpg
Noblex Climate, components/climate/climate_ir, air-conditioner-ir.svg, dark-invert
Honeywell ABP2, components/sensor/honeywellabp2_i2c, honeywellabp.jpg
iAQ-Core, components/sensor/iaqcore, iaqcore.jpg
SFA30, components/sensor/sfa30, sfa30.jpg
ZH/LT-01 Climate, components/climate/climate_ir, air-conditioner-ir.svg, dark-invert
EMC2101, components/emc2101, emc2101.jpg
MicroNova pellet stove, components/micronova, pellet.svg
XGZP68xx Series, components/sensor/xgzp68xx, 6897d.jpg
Text Components
---------------
We finally have implemented the :doc:`Text </components/text/index>` Components.
Many people have been using "Text Input Helpers" to get user entered text into
ESPHome for various reasons. Now ESPHome can expose text entities
directly to Home Assistant. These require Home Assistant 2023.11 or above to use.
Various Automations
-------------------
- BLE have had ``ble.enable`` and ``ble.disable`` actions added to turn on and off when not needed,
as well as a new condition ``ble.enabled`` to check the state.
- Wi-Fi has new triggers for ``on_connect`` and ``on_disconnect``.
- ``api`` has new triggers ``on_client_connected`` and ``on_client_disconnected`` which were
released in the 2023.10.5 patch version due to requiring that specific PR to not cause merge
conflicts later.
Areas
-----
When you add a new ESPHome device to Home Assistant, you assign that device to an area.
From Home Assistant 2023.12, you will be able to specify the suggested area that Home Assistant
pre-populates when you connect the device.
.. code-block:: yaml
esphome:
name: living-room-light
friendly_name: Living Room Light
area: Living Room
Release 2023.11.1 - November 16
-------------------------------
- Add more VA triggers :esphomepr:`5762` by :ghuser:`kbx81`
- Fix MY9231 flicker :esphomepr:`5765` by :ghuser:`Mat931`
Release 2023.11.2 - November 18
-------------------------------
- Bump aioesphomeapi from 18.4.0 to 18.4.1 :esphomepr:`5767` by :ghuser:`dependabot[bot]`
- Bump aioesphomeapi from 18.4.1 to 18.5.2 :esphomepr:`5780` by :ghuser:`dependabot[bot]`
- fix 32-bit arm :esphomepr:`5781` by :ghuser:`ssieb`
- Add 2MB option for partitions.csv generation and restore use of user-defined partitions :esphomepr:`5779` by :ghuser:`kbx81`
Release 2023.11.3 - November 22
-------------------------------
- include payload_open when a lock supports OPEN :esphomepr:`5809` by :ghuser:`ccutrer`
- dashboard: Fix online status when api is disabled :esphomepr:`5791` by :ghuser:`bdraco`
- fix: compile errors with fonts :esphomepr:`5808` by :ghuser:`cvandesande`
- Early return when there are no wifi scan results :esphomepr:`5797` by :ghuser:`jesserockz`
- Add some additional VA triggers, part 2 :esphomepr:`5811` by :ghuser:`kbx81`
Release 2023.11.4 - November 24
-------------------------------
- Allow images to be downloaded from URLs :esphomepr:`5214` by :ghuser:`landonr`
Release 2023.11.5 - November 28
-------------------------------
- Voice Assistant improvements :esphomepr:`5827` by :ghuser:`jesserockz`
- Fix missing include in remote_base :esphomepr:`5843` by :ghuser:`jesserockz`
- Add 'voice_assistant.connected' condition :esphomepr:`5845` by :ghuser:`jesserockz`
Release 2023.11.6 - November 28
-------------------------------
- Fix write_speaker without speaker in config :esphomepr:`5847` by :ghuser:`jesserockz`
Full list of changes
--------------------
New Components
^^^^^^^^^^^^^^
- Add Support for Sensirion SFA30 sensor :esphomepr:`5519` by :ghuser:`ghsensdev` (new-integration)
- add uart button :esphomepr:`5540` by :ghuser:`ssieb` (new-integration)
- Add ZH/LT-01 climate component with IR receiver option :esphomepr:`4333` by :ghuser:`cfeenstra1024` (new-integration)
- Feat: Add GREE climateir component :esphomepr:`4464` by :ghuser:`PiuPiuson` (new-integration)
- AMS iAQ Core CO2 sensor component :esphomepr:`5192` by :ghuser:`yozik04` (new-integration)
- Add IR Noblex climate component :esphomepr:`4913` by :ghuser:`AGalfra` (new-integration)
- Add text component :esphomepr:`5336` by :ghuser:`EternityForest` (new-integration)
- Add support for honeywellabp2 pressure sensor :esphomepr:`5422` by :ghuser:`jpfaff` (new-integration)
- Add Emc2101 :esphomepr:`4491` by :ghuser:`ellull` (new-integration)
- Add support for Qwiic PIR binary sensor :esphomepr:`5194` by :ghuser:`kahrendt` (new-integration)
- Add dfrobot_sen0395 mmwave radar component :esphomepr:`4203` by :ghuser:`niklasweber` (new-integration)
- Add HLK-LD2420 mmWave Radar module component. :esphomepr:`4847` by :ghuser:`descipher` (new-integration)
- Add Micronova component :esphomepr:`4760` by :ghuser:`Jorre05` (new-integration)
- Add differential pressure sensor support for CFSensor XGZP68xxD devices :esphomepr:`5562` by :ghuser:`gcormier` (new-integration)
- Add spi support for ade7953 :esphomepr:`5439` by :ghuser:`angelnu` (new-integration)
- Add resistance_sampler interface for config validation :esphomepr:`5718` by :ghuser:`jesserockz` (new-integration)
Breaking Changes
^^^^^^^^^^^^^^^^
- Hydreon updates :esphomepr:`5424` by :ghuser:`jj-uk` (breaking-change)
- Fix esp32_rmt_led_strip custom timing units :esphomepr:`5696` by :ghuser:`jesserockz` (breaking-change)
Beta Changes
^^^^^^^^^^^^
- Handle nanoseconds in config :esphomepr:`5695` by :ghuser:`jesserockz`
- Fix esp32_rmt_led_strip custom timing units :esphomepr:`5696` by :ghuser:`jesserockz` (breaking-change)
- Fix static assets cache logic :esphomepr:`5700` by :ghuser:`bdraco`
- Use piwheels for armv7 docker image builds :esphomepr:`5703` by :ghuser:`bdraco`
- fix: Fix broken bluetooth_proxy and ble_clients after BLE enable/disable :esphomepr:`5704` by :ghuser:`Rapsssito`
- Bump aioesphomeapi to 18.2.7 :esphomepr:`5706` by :ghuser:`bdraco`
- Update Dockerfile to use piwheels for armv7 :esphomepr:`5709` by :ghuser:`bdraco`
- Bump zeroconf from 0.120.0 to 0.122.3 :esphomepr:`5715` by :ghuser:`dependabot[bot]`
- Add resistance_sampler interface for config validation :esphomepr:`5718` by :ghuser:`jesserockz` (new-integration)
- Fix zeroconf name resolution refactoring error :esphomepr:`5725` by :ghuser:`bdraco`
- Missed ifdefs :esphomepr:`5727` by :ghuser:`descipher`
- Bump aioesphomeapi from 18.2.7 to 18.4.0 :esphomepr:`5735` by :ghuser:`dependabot[bot]`
- Migrate to using aioesphomeapi for the log runner to fix multiple issues :esphomepr:`5733` by :ghuser:`bdraco`
- Bump zeroconf to 0.123.0 :esphomepr:`5736` by :ghuser:`bdraco`
- Handle wake word not set up internally :esphomepr:`5738` by :ghuser:`jesserockz`
- dashboard: remove usage of codecs module :esphomepr:`5741` by :ghuser:`bdraco`
- dashboard: Run get_serial_ports in the executor :esphomepr:`5740` by :ghuser:`bdraco`
- Generate partitions.csv based on flash size :esphomepr:`5697` by :ghuser:`kbx81`
- Allow setup to continue past mqtt if network/wifi is disabled :esphomepr:`5754` by :ghuser:`jesserockz`
- Dont dump wifi info when disabled :esphomepr:`5755` by :ghuser:`jesserockz`
All changes
^^^^^^^^^^^
- Splits FastLed test scripts out of test1.yaml :esphomepr:`5522` by :ghuser:`nielsnl68`
- Add round sensor filter :esphomepr:`5532` by :ghuser:`jesserockz`
- Add Support for Sensirion SFA30 sensor :esphomepr:`5519` by :ghuser:`ghsensdev` (new-integration)
- Change UART source clock to `UART_SCLK_DEFAULT` when IDF >=v5 :esphomepr:`5533` by :ghuser:`leoshusar`
- add uart button :esphomepr:`5540` by :ghuser:`ssieb` (new-integration)
- add on/off options for uart switch :esphomepr:`5539` by :ghuser:`ssieb`
- Update docker base and packages + docker python 3.11 :esphomepr:`5473` by :ghuser:`bdraco`
- IDF 5 fixes for various components from test1.yaml :esphomepr:`5451` by :ghuser:`kbx81`
- Bump aioesphomeapi from 15.0.0 to 18.0.6 :esphomepr:`5557` by :ghuser:`dependabot[bot]`
- Bump zeroconf from 0.115.1 to 0.119.0 :esphomepr:`5560` by :ghuser:`dependabot[bot]`
- Add config to allow suppression of warnings about use of strapping pins :esphomepr:`5287` by :ghuser:`clydebarrow`
- Hydreon updates :esphomepr:`5424` by :ghuser:`jj-uk` (breaking-change)
- Bump actions/checkout from 4.1.0 to 4.1.1 :esphomepr:`5551` by :ghuser:`dependabot[bot]`
- Bump pyupgrade from 3.10.1 to 3.13.0 :esphomepr:`5428` by :ghuser:`dependabot[bot]`
- Bump tzlocal from 5.0.1 to 5.1 :esphomepr:`5480` by :ghuser:`dependabot[bot]`
- Bump black from 23.9.1 to 23.10.0 :esphomepr:`5561` by :ghuser:`dependabot[bot]`
- Fan no off cycle action :esphomepr:`5564` by :ghuser:`skykingjwc`
- Bump aioesphomeapi from 18.0.6 to 18.0.7 :esphomepr:`5573` by :ghuser:`dependabot[bot]`
- Remove unnecessary checks in Nextion component :esphomepr:`5578` by :ghuser:`edwardtfn`
- update storage version from mdns :esphomepr:`5584` by :ghuser:`glmnet`
- set Nextion protocol reparse mode :esphomepr:`5484` by :ghuser:`edwardtfn`
- Add address text sensor to WireGuard :esphomepr:`5576` by :ghuser:`droscy`
- Add LibreTiny hardwares to PR Template :esphomepr:`5575` by :ghuser:`HeMan`
- Bump pytest-mock from 3.11.1 to 3.12.0 :esphomepr:`5571` by :ghuser:`dependabot[bot]`
- Bump pyupgrade from 3.13.0 to 3.15.0 :esphomepr:`5570` by :ghuser:`dependabot[bot]`
- Add ZH/LT-01 climate component with IR receiver option :esphomepr:`4333` by :ghuser:`cfeenstra1024` (new-integration)
- Feat: Add GREE climateir component :esphomepr:`4464` by :ghuser:`PiuPiuson` (new-integration)
- AMS iAQ Core CO2 sensor component :esphomepr:`5192` by :ghuser:`yozik04` (new-integration)
- Add IR Noblex climate component :esphomepr:`4913` by :ghuser:`AGalfra` (new-integration)
- Bump aioesphomeapi from 18.0.7 to 18.0.12 :esphomepr:`5597` by :ghuser:`dependabot[bot]`
- Add text component :esphomepr:`5336` by :ghuser:`EternityForest` (new-integration)
- Fix exception handling when loading packages :esphomepr:`5569` by :ghuser:`dentra`
- Add support for honeywellabp2 pressure sensor :esphomepr:`5422` by :ghuser:`jpfaff` (new-integration)
- Add Emc2101 :esphomepr:`4491` by :ghuser:`ellull` (new-integration)
- Fix: Incorporate unique serial number in preference's hash for multiple Sensirion sensors :esphomepr:`5479` by :ghuser:`kahrendt`
- Add support for Qwiic PIR binary sensor :esphomepr:`5194` by :ghuser:`kahrendt` (new-integration)
- Add ignore out of range option for clamp filter :esphomepr:`5455` by :ghuser:`kahrendt`
- Print text mqtt command topic :esphomepr:`5601` by :ghuser:`jesserockz`
- Correctly allow mqtt topics to be none so ESPHome does not sub/pub to them :esphomepr:`5213` by :ghuser:`jesserockz`
- SX1509 output debounce fix (resolves esphome/issues#4402) :esphomepr:`4672` by :ghuser:`tracestep`
- Add details when error loading package :esphomepr:`5603` by :ghuser:`dentra`
- Fallback to main secrets.yaml for packages :esphomepr:`5604` by :ghuser:`dentra`
- Add area (zone) to esphome core config to be suggested through API and MQTT. :esphomepr:`5602` by :ghuser:`Cossid`
- Devcontainer: allow pip install and dont warn about root user :esphomepr:`5608` by :ghuser:`jesserockz`
- Validate test files before compiling :esphomepr:`5611` by :ghuser:`jesserockz`
- Minor defines.h updates :esphomepr:`5610` by :ghuser:`jesserockz`
- timeout filter: return value :esphomepr:`5612` by :ghuser:`jesserockz`
- Add dfrobot_sen0395 mmwave radar component :esphomepr:`4203` by :ghuser:`niklasweber` (new-integration)
- refactor mcp4728 component :esphomepr:`5609` by :ghuser:`ssieb`
- Fix HA error related to incorrect state class :esphomepr:`5605` by :ghuser:`nagyrobi`
- Fix xpt2046 for IDF 5 :esphomepr:`5614` by :ghuser:`kbx81`
- IDF 5 fixes for various components from test4.yaml :esphomepr:`5622` by :ghuser:`kbx81`
- IDF 5 fixes for various components from test2.yaml :esphomepr:`5621` by :ghuser:`kbx81`
- Fix armv7 docker builds :esphomepr:`5630` by :ghuser:`bdraco`
- Bump aioesphomeapi from 18.0.12 to 18.2.0 :esphomepr:`5606` by :ghuser:`dependabot[bot]`
- Add needs-docs workflow to fail CI :esphomepr:`5643` by :ghuser:`jesserockz`
- Add support for PCA9535 16 bit I/O expander :esphomepr:`5634` by :ghuser:`clydebarrow`
- Fix nextion waveform sending for multiple waveforms :esphomepr:`4408` by :ghuser:`gpambrozio`
- Allow validation of pins based on hub config :esphomepr:`5647` by :ghuser:`jesserockz`
- Bump aioesphomeapi from 18.2.0 to 18.2.1 :esphomepr:`5653` by :ghuser:`dependabot[bot]`
- Validate sn74hc595 pin number are within range :esphomepr:`5655` by :ghuser:`jesserockz`
- Update PCA9554 pin checks to new facility :esphomepr:`5656` by :ghuser:`clydebarrow`
- Update mDNS component to 1.2.2 :esphomepr:`5654` by :ghuser:`HeMan`
- Fix return value of run_external_command :esphomepr:`5657` by :ghuser:`jesserockz`
- Update RTTTL component to allow I2S :esphomepr:`5177` by :ghuser:`nielsnl68`
- Bump flake8 version in pre-commit to match requirements file :esphomepr:`5658` by :ghuser:`jesserockz`
- Bump pytest from 7.4.2 to 7.4.3 :esphomepr:`5599` by :ghuser:`dependabot[bot]`
- Bump tzlocal from 5.1 to 5.2 :esphomepr:`5594` by :ghuser:`dependabot[bot]`
- Bump black from 23.10.0 to 23.10.1 :esphomepr:`5593` by :ghuser:`dependabot[bot]`
- Add Healthcheck to Dockerfile :esphomepr:`5651` by :ghuser:`JcMinarro`
- Add HLK-LD2420 mmWave Radar module component. :esphomepr:`4847` by :ghuser:`descipher` (new-integration)
- Add Micronova component :esphomepr:`4760` by :ghuser:`Jorre05` (new-integration)
- Add basic shell autocompletion using argcomplete :esphomepr:`5618` by :ghuser:`Nardol`
- Fixed int variables for user defined service in case of ESP32-C3 :esphomepr:`5675` by :ghuser:`paveldn`
- Add callback for raw sml messages :esphomepr:`5668` by :ghuser:`micw`
- Fix compile with latest esp-idf on esp32c6 :esphomepr:`5677` by :ghuser:`DAVe3283`
- Null topic_prefix disables MQTT publishing/subscription unless topic is explicitly configured :esphomepr:`5644` by :ghuser:`kahrendt`
- feat: Add ESP32 BLE enable/disable automations :esphomepr:`5616` by :ghuser:`Rapsssito`
- ble_client rssi sensor fix when not connected :esphomepr:`5632` by :ghuser:`jesserockz`
- Add Byron Doorbell RF protocol :esphomepr:`4718` by :ghuser:`marshn`
- Refactor dashboard zeroconf support :esphomepr:`5681` by :ghuser:`bdraco`
- Allow static assets to be cached if not in debug mode :esphomepr:`5684` by :ghuser:`jesserockz`
- Remove extra code in old sgp40 :esphomepr:`5685` by :ghuser:`jesserockz`
- Allow pulse light effect to have separate on and off transition lengths :esphomepr:`5659` by :ghuser:`jesserockz`
- Add differential pressure sensor support for CFSensor XGZP68xxD devices :esphomepr:`5562` by :ghuser:`gcormier` (new-integration)
- Bump zeroconf from 0.119.0 to 0.120.0 :esphomepr:`5682` by :ghuser:`dependabot[bot]`
- Add spi support for ade7953 :esphomepr:`5439` by :ghuser:`angelnu` (new-integration)
- Remove page jump on Nextion startup :esphomepr:`5673` by :ghuser:`edwardtfn`
- [web_server] Adds the ability to handle Private Network Access preflight requests :esphomepr:`5669` by :ghuser:`DanielBaulig`
- Update esphome-dashboard to version 20231107.0 :esphomepr:`5686` by :ghuser:`jesserockz`
- add wifi.on_connect and wifi.on_disconnect triggers :esphomepr:`3639` by :ghuser:`ChemicalXandco`
- Implement a memory cache for dashboard entries to avoid frequent disk reads :esphomepr:`5687` by :ghuser:`bdraco`
- support spi for sn74hc595 :esphomepr:`5491` by :ghuser:`angelnu`
- Handle on_disconnect when Wi-Fi is disabled :esphomepr:`5691` by :ghuser:`kbx81`
- Bump aioesphomeapi from 18.2.1 to 18.2.4 :esphomepr:`5692` by :ghuser:`dependabot[bot]`
- Handle nanoseconds in config :esphomepr:`5695` by :ghuser:`jesserockz`
- Fix esp32_rmt_led_strip custom timing units :esphomepr:`5696` by :ghuser:`jesserockz` (breaking-change)
- Fix static assets cache logic :esphomepr:`5700` by :ghuser:`bdraco`
- Use piwheels for armv7 docker image builds :esphomepr:`5703` by :ghuser:`bdraco`
- fix: Fix broken bluetooth_proxy and ble_clients after BLE enable/disable :esphomepr:`5704` by :ghuser:`Rapsssito`
- Bump aioesphomeapi to 18.2.7 :esphomepr:`5706` by :ghuser:`bdraco`
- Update Dockerfile to use piwheels for armv7 :esphomepr:`5709` by :ghuser:`bdraco`
- Bump zeroconf from 0.120.0 to 0.122.3 :esphomepr:`5715` by :ghuser:`dependabot[bot]`
- Add resistance_sampler interface for config validation :esphomepr:`5718` by :ghuser:`jesserockz` (new-integration)
- Fix zeroconf name resolution refactoring error :esphomepr:`5725` by :ghuser:`bdraco`
- Missed ifdefs :esphomepr:`5727` by :ghuser:`descipher`
- Bump aioesphomeapi from 18.2.7 to 18.4.0 :esphomepr:`5735` by :ghuser:`dependabot[bot]`
- Migrate to using aioesphomeapi for the log runner to fix multiple issues :esphomepr:`5733` by :ghuser:`bdraco`
- Bump zeroconf to 0.123.0 :esphomepr:`5736` by :ghuser:`bdraco`
- Handle wake word not set up internally :esphomepr:`5738` by :ghuser:`jesserockz`
- dashboard: remove usage of codecs module :esphomepr:`5741` by :ghuser:`bdraco`
- dashboard: Run get_serial_ports in the executor :esphomepr:`5740` by :ghuser:`bdraco`
- Generate partitions.csv based on flash size :esphomepr:`5697` by :ghuser:`kbx81`
- Allow setup to continue past mqtt if network/wifi is disabled :esphomepr:`5754` by :ghuser:`jesserockz`
- Dont dump wifi info when disabled :esphomepr:`5755` by :ghuser:`jesserockz`
Past Changelogs
---------------
- :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`

2
changelog/index.rst
View File

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

205
components/api.rst
View File

@ -7,7 +7,7 @@ Native API Component
:keywords: Native API, ESPHome, Home Assistant
The ESPHome native API is used to communicate with clients directly, with a highly-optimized
network protocol. Currently, only the ESPHome tool and Home Assistant use this native API.
network protocol. Currently, only the ESPHome tool, Home Assistant and ioBroker use this native API.
After adding an ``api:`` line to your ESPHome configuration you can go to the Home Assistant
web interface and navigate to the "Integrations" screen in the "Configuration" panel. Then wait
@ -66,13 +66,56 @@ Configuration variables:
the ESP is connected to the network, when in fact it is not - only a full reboot fixes it.
Can be disabled by setting this to ``0s``. Defaults to ``15min``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults to no password.
It is recommended to use the ``encryption`` -> ``key`` above instead of the the ``password``.
- **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults
to no password. It is recommended to use the ``encryption`` -> ``key`` above instead of the the ``password``.
- **on_client_connected** (*Optional*, :ref:`Action <config-action>`): An automation to perform when a client
connects to the API. See :ref:`api-on_client_connected_trigger`.
- **on_client_disconnected** (*Optional*, :ref:`Action <config-action>`): An automation to perform when a client
disconnects from the API. See :ref:`api-on_client_disconnected_trigger`.
.. _api-actions:
.. note::
Before a newly added ESPHome device can interact with the Home Assistant API it needs to be allowed to communicate
with it. This setting can be found in the ESPHome integration (NOT in the Add-On) by clicking "CONFIGURE" for
that device and enabling the "Allow device to make service calls" option.
Actions
-------
.. _api-homeassistant_event_action:
``homeassistant.event`` Action
******************************
When using the native API with Home Assistant, you can create events in the Home Assistant event bus
straight from ESPHome :ref:`Automations <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.event:
event: esphome.button_pressed
data:
message: Button was pressed
Configuration variables:
````````````````````````
- **event** (**Required**, string): The event to create - must begin with ``esphome.``
- **data** (*Optional*, mapping): Optional *static* data to pass along with the event.
- **data_template** (*Optional*, mapping): Optional template data to pass along with the event.
This is evaluated on the Home Assistant side with Home Assistant's templating engine.
- **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``.
Values are :ref:`lambdas <config-lambda>` and will be evaluated before sending the request.
.. _api-homeassistant_service_action:
``homeassistant.service`` Action
--------------------------------
********************************
When using the native API with Home Assistant, you can create Home Assistant service
calls straight from ESPHome :ref:`Automations <automation>`.
@ -97,7 +140,8 @@ calls straight from ESPHome :ref:`Automations <automation>`.
my_variable: |-
return id(my_sensor).state;
Configuration options:
Configuration variables:
````````````````````````
- **service** (**Required**, string): The Home Assistant `Service <https://www.home-assistant.io/docs/scripts/service-calls/>`__
to call.
@ -126,7 +170,7 @@ the parameters in plain format.
- '{{ green }}'
- '{{ blue }}'
Then in ESPHome
Then, in ESPHome:
.. code-block:: yaml
@ -140,6 +184,86 @@ Then in ESPHome
green: '199'
blue: '71'
.. _api-homeassistant_tag_scanned_action:
``homeassistant.tag_scanned`` Action
************************************
When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
straight from ESPHome :ref:`Automations <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.tag_scanned: some-tag
Configuration variables:
````````````````````````
- **tag** (**Required**, :ref:`templatable <config-templatable>`, string): The id of the scanned tag
Triggers
--------
.. _api-on_client_connected_trigger:
``on_client_connected`` Trigger
*******************************
This trigger is activated each time a client connects to the API. Two variables of
type ``std::string`` are available for use by actions called from within this trigger:
- ``client_address``: the IP address of the client that connected
- ``client_info``: the name of the client that connected
.. code-block:: yaml
api:
# ...
on_client_connected:
- logger.log:
format: "Client %s connected to API with IP %s"
args: ["client_info.c_str()", "client_address.c_str()"]
.. _api-on_client_disconnected_trigger:
``on_client_disconnected`` Trigger
**********************************
This trigger is activated each time the API disconnects from the API. Two variables of
type ``std::string`` are available for use by actions called from within this trigger:
- ``client_address``: the IP address of the client that disconnected
- ``client_info``: the name of the client that disconnected
.. code-block:: yaml
api:
# ...
on_client_disconnected:
- logger.log: "API client disconnected!"
.. _api-connected_condition:
``api.connected`` Condition
---------------------------
This :ref:`Condition <config-condition>` checks if at least one client is connected to the ESPHome
native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output
if logs are shown remotely.
.. code-block:: yaml
on_...:
if:
condition:
api.connected:
then:
- logger.log: API is connected!
.. _api-services:
User-defined Services
@ -208,30 +332,11 @@ Each of these also exist in array form:
- bool[]: An array of boolean values. C++ type: ``std::vector<bool>``
- ... - Same for other types.
.. _api-connected_condition:
``api.connected`` Condition
---------------------------
This :ref:`Condition <config-condition>` checks if at least one client is connected to the ESPHome
native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output
if logs are shown remotely.
.. code-block:: yaml
on_...:
if:
condition:
api.connected:
then:
- logger.log: API is connected!
Advantages over MQTT
--------------------
The ESPHome native API has many advantages over using MQTT for communication with Home
Automation software (currently only Home Assistant). But MQTT is a great protocol and will
Automation software (currently only Home Assistant and ioBroker). But MQTT is a great protocol and will
never be removed. Features of native API (vs. MQTT):
- **Much more efficient:** ESPHome encodes all messages in a highly optimized format with
@ -245,54 +350,6 @@ never be removed. Features of native API (vs. MQTT):
- **Low Latency:** The native API is optimized for very low latency, usually this is only
a couple of milliseconds and far less than can be noticed by the eye.
.. _api-homeassistant_event_action:
``homeassistant.event`` Action
------------------------------
When using the native API with Home Assistant, you can create events in the Home Assistant event bus
straight from ESPHome :ref:`Automations <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.event:
event: esphome.button_pressed
data:
message: Button was pressed
Configuration options:
- **event** (**Required**, string): The event to create - must begin with ``esphome.``
- **data** (*Optional*, mapping): Optional *static* data to pass along with the event.
- **data_template** (*Optional*, mapping): Optional template data to pass along with the event.
This is evaluated on the Home Assistant side with Home Assistant's templating engine.
- **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``.
Values are :ref:`lambdas <config-lambda>` and will be evaluated before sending the request.
.. _api-homeassistant_tag_scanned_action:
``homeassistant.tag_scanned`` Action
------------------------------------
When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
straight from ESPHome :ref:`Automations <automation>`.
.. code-block:: yaml
# In some trigger
on_...:
# Simple
- homeassistant.tag_scanned: some-tag
Configuration options:
- **tag** (**Required**, :ref:`templatable <config-templatable>`, string): The id of the scanned tag
See Also
--------

11
components/binary_sensor/ble_presence.rst
View File

@ -5,8 +5,15 @@ ESP32 Bluetooth Low Energy Device
:description: Instructions for setting up BLE binary sensors for the ESP32.
:image: bluetooth.svg
The ``ble_presence`` binary sensor platform lets you track the presence of a
Bluetooth Low Energy device.
The ``ble_presence`` binary sensor platform lets you track the presence of a Bluetooth Low Energy device.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. figure:: images/esp32_ble-ui.png
:align: center

10
components/binary_sensor/custom.rst
View File

@ -1,6 +1,16 @@
Custom Binary Sensor
====================
.. warning::
Custom components are deprecated, not recommended for new configurations
and will be removed from ESPHome in a future release.
Please look at creating a real ESPHome component and "importing" it into your
configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom binary sensors in ESPHome
using the C++ (Arduino) API.

BIN
components/binary_sensor/images/pn7150-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 180 KiB

BIN
components/binary_sensor/images/pn716x-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 180 KiB

BIN
components/binary_sensor/images/qwiic_pir.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

379
components/binary_sensor/pn7150.rst Normal file
View File

@ -0,0 +1,379 @@
PN7150 NFC
==========
.. seo::
:description: Instructions for setting up PN7150 NFC tag readers and tags in ESPHome
:image: pn7150.jpg
:keywords: PN7150, NFC, RFID
.. _pn7150-component:
Component/Hub
-------------
The ``pn7150`` component allows you to use PN7150 NFC controllers with ESPHome. This component is a global hub that
establishes a connection to the PN7150 via :ref:`I²C <i2c>`.
.. figure:: images/pn7150-full.jpg
:align: center
:width: 70.0%
An :ref:`I²C <i2c>` bus must be defined within your device's ESPHome configuration to use the PN7150.
ESPHome supports both card/tag reading/writing as well as card/tag emulation with this component. By default,
only read/write mode is enabled; card/tag emulation is enabled only if the ``emulation_message`` configuration
variable is defined (see below). Regardless, reader/writer (polling) mode and card/tag emulation mode may be
independently enabled and disabled by using the corresponding :ref:`pn7150-actions` (see below).
.. code-block:: yaml
pn7150_i2c:
dwl_req_pin: 17
irq_pin: 35
ven_pin: 16
wkup_req_pin: 21
emulation_message: https://www.home-assistant.io/tag/pulse_ce
tag_ttl: 1000ms
Configuration variables:
************************
- **dwl_req_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7150's
``DWL_REQ`` line. Used to invoke the PN7150's firmware update mode; may be used in a future release.
- **irq_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7150's ``IRQ`` line.
- **ven_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7150's ``VEN`` line.
- **wkup_req_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7150's
``WKUP_REQ`` line. May be used to improve power management in a future release.
- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this
string is used as the content for an NDEF-formatted response. This allows the PN7150 to act as a tag in addition to a
tag reader/writer.
- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7150 is no longer able to
"see" a tag before it is considered to have been removed from the reader.
- **on_tag** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a tag is first read. See
:ref:`pn7150-on_tag`.
- **on_tag_removed** (*Optional*, :ref:`Automation <automation>`): An automation to perform after a tag is removed. See
:ref:`pn7150-on_tag_removed`.
- **on_emulated_tag_scan** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the PN7150 is
scanned by another tag reader (such as a smartphone). See :ref:`pn7150-on_emulated_tag_scan`.
- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component <i2c>` if you need
to use multiple I²C buses.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component.
.. _pn7150-actions:
Actions
-------
.. _pn7150-set_clean_mode:
``tag.set_clean_mode`` Action
*****************************
Use this action to invoke "clean mode" -- the next tag presented to the PN7150 will be "cleaned", removing all data
from the tag.
.. code-block:: yaml
on_...:
then:
- tag.set_clean_mode: my_pn7150_id
.. _pn7150-set_format_mode:
``tag.set_format_mode`` Action
******************************
Use this action to invoke "format mode" -- the next tag presented to the PN7150 will be "formatted", leaving only an
empty NDEF message structure on the tag.
.. code-block:: yaml
on_...:
then:
- tag.set_format_mode: my_pn7150_id
.. _pn7150-set_read_mode:
``tag.set_read_mode`` Action
****************************
Use this action to invoke "read mode" -- the next tag presented to the PN7150 will be read. This is the default mode
that the component operates in.
.. code-block:: yaml
on_...:
then:
- tag.set_read_mode: my_pn7150_id
.. _pn7150-set_write_message:
``tag.set_write_message`` Action
********************************
Use this action to set the NDEF message used for "write mode" (see below).
.. code-block:: yaml
on_...:
then:
- tag.set_write_message:
message: https://www.home-assistant.io/tag/pulse
include_android_app_record: false
- **message** (**Required**, string, templatable): The string to include in the tag's first NDEF record; typically
a URL as shown.
- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android
operating systems. Defaults to ``true``.
.. _pn7150-set_write_mode:
``tag.set_write_mode`` Action
*****************************
Use this action to invoke "write mode" -- the next tag presented to the PN7150 will have its NDEF message set to the
message defined by the ``tag.set_write_message`` action (see above). **Note that a message must be set before this mode
may be invoked.**
.. code-block:: yaml
on_...:
then:
- tag.set_write_mode: my_pn7150_id
.. _pn7150-set_emulation_message:
``tag.set_emulation_message`` Action
************************************
Use this action to set the NDEF message used for card (tag) emulation mode, when enabled (see below).
.. code-block:: yaml
on_...:
then:
- tag.set_emulation_message:
message: https://www.home-assistant.io/tag/pulse
include_android_app_record: false
- **message** (**Required**, string, templatable): The string to include in the (emulated) tag's first NDEF record;
typically a URL as shown.
- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android
operating systems. Defaults to ``true``.
.. _pn7150-emulation_off:
``tag.emulation_off`` Action
****************************
Use this action to disable card (tag) emulation mode. The PN7150 will no longer respond to requests from other readers,
such as smartphones.
.. code-block:: yaml
on_...:
then:
- tag.emulation_off: my_pn7150_id
.. _pn7150-emulation_on:
``tag.emulation_on`` Action
***************************
Use this action to enable card (tag) emulation mode. The PN7150 will respond to requests from other readers, such as
smartphones.
**Note:** when card/tag emulation is enabled, polling (detecting a nearby card/tag) frequency is decreased; this
typically results in slightly slower detection of cards/tags presented to the PN7150. This behavior is normal and should
be expected; it is the result of the PN7150 toggling between polling and listening modes to support both functions.
.. code-block:: yaml
on_...:
then:
- tag.emulation_on: my_pn7150_id
.. _pn7150-polling_off:
``tag.polling_off`` Action
****************************
Use this action to disable card (tag) reading/writing. The PN7150 will no longer read or write cards/tags.
.. code-block:: yaml
on_...:
then:
- tag.polling_off: my_pn7150_id
.. _pn7150-polling_on:
``tag.polling_on`` Action
***************************
Use this action to enable card (tag) reading/writing. The PN7150 will read or write cards/tags.
.. code-block:: yaml
on_...:
then:
- tag.polling_on: my_pn7150_id
Triggers
--------
.. _pn7150-on_tag:
``on_tag`` Trigger
******************
This automation will be triggered immediately after the PN7150 module identifies a tag and reads its NDEF
message (if one is present).
The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format
``74-10-37-94``. The example configuration below will publish the tag ID on the MQTT topic ``pn7150/tag``.
See :ref:`pn7150-ndef_reading` below for how to use the second ``tag`` parameter that is provided to this trigger.
.. code-block:: yaml
pn7150_i2c:
# ...
on_tag:
then:
- mqtt.publish:
topic: pn7150/tag
payload: !lambda 'return x;'
A tag scanned event can also be sent to the Home Assistant tag component
using :ref:`api-homeassistant_tag_scanned_action`.
.. code-block:: yaml
pn7150_i2c:
# ...
on_tag:
then:
- homeassistant.tag_scanned: !lambda 'return x;'
You could also send the value to Home Assistant via a :doc:`template sensor </components/sensor/template>`:
.. code-block:: yaml
pn7150_i2c:
# ...
on_tag:
then:
- text_sensor.template.publish:
id: nfc_tag
state: !lambda 'return x;'
text_sensor:
- platform: template
name: "NFC Tag"
id: nfc_tag
.. _pn7150-on_tag_removed:
``on_tag_removed`` Trigger
**************************
This automation will be triggered after the ``tag_ttl`` interval (see above) when the PN7150 no longer "sees" a
previously scanned tag.
The parameter ``x`` this trigger provides is of type ``std::string`` and is the removed tag UID in the format
``74-10-37-94``. The example configuration below will publish the removed tag ID on the MQTT topic ``pn7150/tag_removed``.
.. code-block:: yaml
pn7150_i2c:
# ...
on_tag_removed:
then:
- mqtt.publish:
topic: pn7150/tag_removed
payload: !lambda 'return x;'
.. _pn7150-on_emulated_tag_scan:
``on_emulated_tag_scan`` Trigger
********************************
If card/tag emulation is enabled, this automation will be triggered when another reader (such as a smartphone) scans
the PN7150 and reads the NDEF message it responds with. No parameters are available to this action because data is only
sent *from* the PN7150 *to* the scanning device.
.. code-block:: yaml
pn7150_i2c:
# ...
on_emulated_tag_scan:
then:
- rtttl.play: "alert:d=32,o=5,b=160:e6,p,e6,p,e6"
.. _pn7150-ndef:
NDEF
====
The PN7150 supports reading NDEF messages from and writing NDEF messages to cards/tags.
.. _pn7150-ndef_reading:
NDEF Reading
------------
Given an NFC tag formatted and written using the Home Assistant Companion App, the following example will send the tag
ID contained within its NDEF message to Home Assistant using the :ref:`api-homeassistant_tag_scanned_action`.
If no NDEF record is found with a tag ID, the tag's UID will be sent to Home Assistant, instead.
The ``tag`` variable is available to any actions that run within the ``on_tag`` and ``on_tag_removed`` triggers.
.. code-block:: yaml
pn7150_i2c:
# ...
on_tag:
then:
- homeassistant.tag_scanned: !lambda "return tag.has_ha_tag_id() ? tag.get_ha_tag_id() : x;"
.. _pn7150-ndef_writing:
NDEF Writing
------------
The examples below illustrate how NDEF messages may be written to cards/tags via the PN7150. Note that a
:doc:`button </components/button/index>` is a great mechanism to use to trigger these actions.
The first example will write a simple, fixed NDEF message to a tag.
.. code-block:: yaml
on_...
then:
- tag.set_write_message:
message: https://www.home-assistant.io/tag/pulse
include_android_app_record: false # optional
- tag.set_write_mode: my_pn7150_id
The next example can be used to write a (pseudo) random UUID to a tag in the same manner as the Home Assistant
Companion App.
.. code-block:: yaml
on_...
then:
- tag.set_write_message:
message: !lambda "return nfc::get_random_ha_tag_ndef();"
- tag.set_write_mode: my_pn7150_id
See Also
--------
- :doc:`index`
- :doc:`pn532`
- :doc:`rc522`
- :doc:`rdm6300`
- :apiref:`pn7150/pn7150.h`
- :ghedit:`Edit`

437
components/binary_sensor/pn7160.rst Normal file
View File

@ -0,0 +1,437 @@
PN7160 NFC
==========
.. seo::
:description: Instructions for setting up PN7160 NFC tag readers and tags in ESPHome
:image: pn716x.jpg
:keywords: PN7160, NFC, RFID
.. _pn7160-component:
Component/Hub
-------------
The ``pn7160`` component allows you to use PN7160 NFC controllers with ESPHome. This component is a global hub that
establishes a connection to the PN7160 via :ref:`SPI <spi>` or :ref:`I²C <i2c>`.
.. figure:: images/pn716x-full.jpg
:align: center
:width: 70.0%
Within ESPHome, the PN7160 can be configured to use either the SPI **or** I²C protocol for data communication.
Note that there are different versions of the IC for each bus type, each with a different part number; in other
words, **the bus type cannot be changed by jumpers/switches as it is determed at the time of manufacture.**
You must determine which version of the IC you have and then configure the corresponding bus -- either the
:ref:`SPI bus <spi>` or the :ref:`I²C bus <i2c>`.
ESPHome supports both card/tag reading/writing as well as card/tag emulation with this component. By default,
only read/write mode is enabled; card/tag emulation is enabled only if the ``emulation_message`` configuration
variable is defined (see below). Regardless, reader/writer (polling) mode and card/tag emulation mode may be
independently enabled and disabled by using the corresponding :ref:`pn7160-actions` (see below).
.. _pn7160-spi:
Over SPI
--------
The ``pn7160_spi`` component allows you to use :ref:`SPI-equipped <spi>` PN7160 NFC controllers with with ESPHome.
.. code-block:: yaml
pn7160_spi:
cs_pin: 15
dwl_req_pin: 17
irq_pin: 35
ven_pin: 16
wkup_req_pin: 21
emulation_message: https://www.home-assistant.io/tag/pulse_ce
tag_ttl: 1000ms
Configuration variables:
************************
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's ``NSS`` (chip
select) line.
- **dwl_req_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's
``DWL_REQ`` line. Used to invoke the PN7160's firmware update mode; may be used in a future release.
- **irq_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's ``IRQ`` line.
- **ven_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's ``VEN`` line.
- **wkup_req_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's
``WKUP_REQ`` line. May be used to improve power management in a future release.
- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this
string is used as the content for an NDEF-formatted response. This allows the PN7160 to act as a tag in addition to a
tag reader/writer.
- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7160 is no longer able to
"see" a tag before it is considered to have been removed from the reader.
- **on_tag** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a tag is first read. See
:ref:`pn7160-on_tag`.
- **on_tag_removed** (*Optional*, :ref:`Automation <automation>`): An automation to perform after a tag is removed. See
:ref:`pn7160-on_tag_removed`.
- **on_emulated_tag_scan** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the PN7160 is
scanned by another tag reader (such as a smartphone). See :ref:`pn7160-on_emulated_tag_scan`.
- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component <spi>` if you want
to use multiple SPI buses.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component.
.. _pn7160-i2c:
Over I²C
--------
The ``pn7160_i2c`` component allows you to use :ref:`I²C-equipped <i2c>` PN7160 NFC controllers with ESPHome.
.. code-block:: yaml
pn7160_i2c:
dwl_req_pin: 17
irq_pin: 35
ven_pin: 16
wkup_req_pin: 21
emulation_message: https://www.home-assistant.io/tag/pulse_ce
tag_ttl: 1000ms
Configuration variables:
************************
- **dwl_req_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's
``DWL_REQ`` line. Used to invoke the PN7160's firmware update mode; may be used in a future release.
- **irq_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's ``IRQ`` line.
- **ven_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's ``VEN`` line.
- **wkup_req_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7160's
``WKUP_REQ`` line. May be used to improve power management in a future release.
- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this
string is used as the content for an NDEF-formatted response. This allows the PN7160 to act as a tag in addition to a
tag reader/writer.
- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7160 is no longer able to
"see" a tag before it is considered to have been removed from the reader.
- **on_tag** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a tag is first read. See
:ref:`pn7160-on_tag`.
- **on_tag_removed** (*Optional*, :ref:`Automation <automation>`): An automation to perform after a tag is removed. See
:ref:`pn7160-on_tag_removed`.
- **on_emulated_tag_scan** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the PN7160 is
scanned by another tag reader (such as a smartphone). See :ref:`pn7160-on_emulated_tag_scan`.
- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component <i2c>` if you need
to use multiple I²C buses.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component.
.. _pn7160-actions:
Actions
-------
.. _pn7160-set_clean_mode:
``tag.set_clean_mode`` Action
*****************************
Use this action to invoke "clean mode" -- the next tag presented to the PN7160 will be "cleaned", removing all data
from the tag.
.. code-block:: yaml
on_...:
then:
- tag.set_clean_mode: my_pn7160_id
.. _pn7160-set_format_mode:
``tag.set_format_mode`` Action
******************************
Use this action to invoke "format mode" -- the next tag presented to the PN7160 will be "formatted", leaving only an
empty NDEF message structure on the tag.
.. code-block:: yaml
on_...:
then:
- tag.set_format_mode: my_pn7160_id
.. _pn7160-set_read_mode:
``tag.set_read_mode`` Action
****************************
Use this action to invoke "read mode" -- the next tag presented to the PN7160 will be read. This is the default mode
that the component operates in.
.. code-block:: yaml
on_...:
then:
- tag.set_read_mode: my_pn7160_id
.. _pn7160-set_write_message:
``tag.set_write_message`` Action
********************************
Use this action to set the NDEF message used for "write mode" (see below).
.. code-block:: yaml
on_...:
then:
- tag.set_write_message:
message: https://www.home-assistant.io/tag/pulse
include_android_app_record: false
- **message** (**Required**, string, templatable): The string to include in the tag's first NDEF record; typically
a URL as shown.
- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android
operating systems. Defaults to ``true``.
.. _pn7160-set_write_mode:
``tag.set_write_mode`` Action
*****************************
Use this action to invoke "write mode" -- the next tag presented to the PN7160 will have its NDEF message set to the
message defined by the ``tag.set_write_message`` action (see above). **Note that a message must be set before this mode
may be invoked.**
.. code-block:: yaml
on_...:
then:
- tag.set_write_mode: my_pn7160_id
.. _pn7160-set_emulation_message:
``tag.set_emulation_message`` Action
************************************
Use this action to set the NDEF message used for card (tag) emulation mode, when enabled (see below).
.. code-block:: yaml
on_...:
then:
- tag.set_emulation_message:
message: https://www.home-assistant.io/tag/pulse
include_android_app_record: false
- **message** (**Required**, string, templatable): The string to include in the (emulated) tag's first NDEF record;
typically a URL as shown.
- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android
operating systems. Defaults to ``true``.
.. _pn7160-emulation_off:
``tag.emulation_off`` Action
****************************
Use this action to disable card (tag) emulation mode. The PN7160 will no longer respond to requests from other readers,
such as smartphones.
.. code-block:: yaml
on_...:
then:
- tag.emulation_off: my_pn7160_id
.. _pn7160-emulation_on:
``tag.emulation_on`` Action
***************************
Use this action to enable card (tag) emulation mode. The PN7160 will respond to requests from other readers, such as
smartphones.
**Note:** when card/tag emulation is enabled, polling (detecting a nearby card/tag) frequency is decreased; this
typically results in slightly slower detection of cards/tags presented to the PN7160. This behavior is normal and should
be expected; it is the result of the PN7160 toggling between polling and listening modes to support both functions.
.. code-block:: yaml
on_...:
then:
- tag.emulation_on: my_pn7160_id
.. _pn7160-polling_off:
``tag.polling_off`` Action
****************************
Use this action to disable card (tag) reading/writing. The PN7160 will no longer read or write cards/tags.
.. code-block:: yaml
on_...:
then:
- tag.polling_off: my_pn7160_id
.. _pn7160-polling_on:
``tag.polling_on`` Action
***************************
Use this action to enable card (tag) reading/writing. The PN7160 will read or write cards/tags.
.. code-block:: yaml
on_...:
then:
- tag.polling_on: my_pn7160_id
Triggers
--------
.. _pn7160-on_tag:
``on_tag`` Trigger
******************
This automation will be triggered immediately after the PN7160 module identifies a tag and reads its NDEF
message (if one is present).
The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format
``74-10-37-94``. The example configuration below will publish the tag ID on the MQTT topic ``pn7160/tag``.
See :ref:`pn7160-ndef_reading` below for how to use the second ``tag`` parameter that is provided to this trigger.
.. code-block:: yaml
pn7160_...:
# ...
on_tag:
then:
- mqtt.publish:
topic: pn7160/tag
payload: !lambda 'return x;'
A tag scanned event can also be sent to the Home Assistant tag component
using :ref:`api-homeassistant_tag_scanned_action`.
.. code-block:: yaml
pn7160_...:
# ...
on_tag:
then:
- homeassistant.tag_scanned: !lambda 'return x;'
You could also send the value to Home Assistant via a :doc:`template sensor </components/sensor/template>`:
.. code-block:: yaml
pn7160_...:
# ...
on_tag:
then:
- text_sensor.template.publish:
id: nfc_tag
state: !lambda 'return x;'
text_sensor:
- platform: template
name: "NFC Tag"
id: nfc_tag
.. _pn7160-on_tag_removed:
``on_tag_removed`` Trigger
**************************
This automation will be triggered after the ``tag_ttl`` interval (see above) when the PN7160 no longer "sees" a
previously scanned tag.
The parameter ``x`` this trigger provides is of type ``std::string`` and is the removed tag UID in the format
``74-10-37-94``. The example configuration below will publish the removed tag ID on the MQTT topic ``pn7160/tag_removed``.
.. code-block:: yaml
pn7160_...:
# ...
on_tag_removed:
then:
- mqtt.publish:
topic: pn7160/tag_removed
payload: !lambda 'return x;'
.. _pn7160-on_emulated_tag_scan:
``on_emulated_tag_scan`` Trigger
********************************
If card/tag emulation is enabled, this automation will be triggered when another reader (such as a smartphone) scans
the PN7160 and reads the NDEF message it responds with. No parameters are available to this action because data is only
sent *from* the PN7160 *to* the scanning device.
.. code-block:: yaml
pn7160_...:
# ...
on_emulated_tag_scan:
then:
- rtttl.play: "alert:d=32,o=5,b=160:e6,p,e6,p,e6"
.. _pn7160-ndef:
NDEF
====
The PN7160 supports reading NDEF messages from and writing NDEF messages to cards/tags.
.. _pn7160-ndef_reading:
NDEF Reading
------------
Given an NFC tag formatted and written using the Home Assistant Companion App, the following example will send the tag
ID contained within its NDEF message to Home Assistant using the :ref:`api-homeassistant_tag_scanned_action`.
If no NDEF record is found with a tag ID, the tag's UID will be sent to Home Assistant, instead.
The ``tag`` variable is available to any actions that run within the ``on_tag`` and ``on_tag_removed`` triggers.
.. code-block:: yaml
pn7160_...:
# ...
on_tag:
then:
- homeassistant.tag_scanned: !lambda "return tag.has_ha_tag_id() ? tag.get_ha_tag_id() : x;"
.. _pn7160-ndef_writing:
NDEF Writing
------------
The examples below illustrate how NDEF messages may be written to cards/tags via the PN7160. Note that a
:doc:`button </components/button/index>` is a great mechanism to use to trigger these actions.
The first example will write a simple, fixed NDEF message to a tag.
.. code-block:: yaml
on_...
then:
- tag.set_write_message:
message: https://www.home-assistant.io/tag/pulse
include_android_app_record: false # optional
- tag.set_write_mode: my_pn7160_id
The next example can be used to write a (pseudo) random UUID to a tag in the same manner as the Home Assistant
Companion App.
.. code-block:: yaml
on_...
then:
- tag.set_write_message:
message: !lambda "return nfc::get_random_ha_tag_ndef();"
- tag.set_write_mode: my_pn7160_id
See Also
--------
- :doc:`index`
- :doc:`pn532`
- :doc:`rc522`
- :doc:`rdm6300`
- :apiref:`pn7160/pn7160.h`
- :ghedit:`Edit`

72
components/binary_sensor/qwiic_pir.rst Normal file
View File

@ -0,0 +1,72 @@
Qwiic PIR Motion Binary Sensor
==============================
.. seo::
:description: Instructions for setting up the Qwiic PIR Motion binary sensor.
:image: qwiic_pir.jpg
The Qwiic PIR Motion binary sensor allows you to use your Qwiic PIR (`EKMC4607112K based <https://www.sparkfun.com/products/17374>`__, `EKMB1107112 based <https://www.sparkfun.com/products/17375>`__, `firmware documentation <https://github.com/sparkfun/Qwiic_PIR>`__)
sensors from SparkFun with ESPHome.
.. figure:: images/qwiic_pir.jpg
:align: center
:width: 30.0%
SparkFun Qwiic PIR sensor.
(Credit: `Sparkfun <https://www.sparkfun.com/products/17374>`__, image cropped and compressed)
.. _Sparkfun: https://www.sparkfun.com/products/17374
The SparkFun Qwiic PIR Motion binary sensor uses PIR sensors to detect motion. It communicates over I²C. There are two models currently available. One uses the `Panasonic EKMC4607112K sensor <https://cdn.sparkfun.com/assets/7/2/a/4/3/EKMC460711xK_Spec.pdf>`__, and the other uses the `Panasonic EKMB1107112 sensor <https://cdn.sparkfun.com/assets/c/e/8/7/5/EKMB110711x_Spec.pdf>`__.
You can configure a debounce mode to reduce noise and false detections. See :ref:`debounce-modes` for the available options.
To use the sensor, first set up an :ref:`I²C Bus <i2c>` and connect the sensor to the specified pins.
.. code-block:: yaml
# Example configuration entry
binary_sensor:
- platform: qwiic_pir
name: "Qwiic PIR Motion Sensor"
Configuration variables:
------------------------
- **debounce_mode** (*Optional*, enum): How the component debounces the motion sensor's signal. Must be one of ``HYBRID``, ``NATIVE``, or ``RAW``. See :ref:`debounce-modes` for details. Defaults to ``HYBRID``.
- **debounce** (*Optional*, :ref:`config-time`): Only valid when using ``NATIVE`` debounce mode. Configures the debounce time on the sensor to reduce noise and false detections. Defaults to ``1ms``.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. _debounce-modes:
Debounce Modes
**************
There are three options for ``debounce_mode``.
- ``HYBRID``:
- Use a combination of the raw sensor reading and the sensor's native event detection to determine state.
- Very reliable for detecting both object's being detected and no longer detected.
- Use binary sensor filters to reduce noise and false detections.
- ``NATIVE``:
- Use the sensor's native event detection to debounce the signal.
- Logic follows `SparkFun's reference example implementation <https://github.com/sparkfun/SparkFun_Qwiic_PIR_Arduino_Library/blob/master/examples/Example2_PrintPIRStatus/Example2_PrintPIRStatus.ino>`__.
- May be unreliable at detecting when an object is removed, especially at high debounce rates.
- Binary sensor filters are not necessary to reduce noise and false detections.
- ``RAW``:
- Use the raw state of the PIR sensor as reported by the firmware.
- May miss a very short motion detection events if ESPHome's loop time is slow.
- Use binary sensor filters to reduce noise and false detections.
See Also
--------
- :doc:`/components/binary_sensor/index`
- :apiref:`qwiic_pir/qwiic_pir.h`
- `SparkFun Qwiic PIR Library <https://github.com/sparkfun/SparkFun_Qwiic_PIR_Arduino_Library>`__ by `SparkFun <https://www.sparkfun.com/>`__
- :ghedit:`Edit`

38
components/ble_client.rst
View File

@ -5,33 +5,31 @@ BLE Client
:description: Configuration of the BLE client on ESP32.
:image: bluetooth.svg
The ``ble_client`` component enables connections to Bluetooth
Low Energy devices in order to query and control them. This
component does not expose any sensors or output components itself,
but merely manages connections to them for use by other components.
The ``ble_client`` component enables connections to Bluetooth Low Energy devices in order to query and
control them. This component does not expose any sensors or output components itself, but merely manages
connections to them for use by other components.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. note::
The BLE software stack on the ESP32 consumes a significant
amount of RAM on the device. As such, you may experience
frequent crashes due to out-of-memory if you enable many
other components.
A maximum of three devices is supported due to limitations in the ESP32 BLE stack. If you wish to
connect more devices, use additional ESP32 boards.
A maximum of three devices is supported due to limitations in the
ESP32 BLE stack. If you wish to connect more devices, use additional
ESP32 boards.
This component supports devices that require a 6 digit PIN code for authentication.
This component supports devices that require a 6 digit PIN code
for authentication.
Currently, devices connected with the client cannot be
supported by other components based on :doc:`/components/esp32_ble_tracker`
as they listen to advertisements which are only sent by devices
Currently, devices connected with the client cannot be supported by other components based on
:doc:`/components/esp32_ble_tracker` as they listen to advertisements which are only sent by devices
without an active connection.
Despite the last point above, the ``ble_client`` component requires
the ``esp32_ble_tracker`` component in order to discover available
client devices.
Despite the last point above, the ``ble_client`` component requires the ``esp32_ble_tracker`` component in order
to discover available client devices.
.. code-block:: yaml

7
components/canbus.rst
View File

@ -171,12 +171,11 @@ There are several forms to use it:
- canbus.send: 'hello'
# Templated, return type is std::vector<uint8_t>
- canbus.send: !lambda
return {0x00, 0x20, 0x42};
- canbus.send: !lambda return {0x00, 0x20, 0x42};
Configuration variables:
- **data** (**Required**, binary data): Data to transmit, up to 8 bytes or
- **data** (**Required**, binary data, :ref:`templatable <config-templatable>`): Data to transmit, up to 8 bytes or
characters are supported by can bus per frame.
- **canbus_id** (*Optional*): Optionally set the can bus id to use for transmitting
the frame. Not needed if you are using only 1 can bus.
@ -353,7 +352,7 @@ Standard IDs and Extended IDs can coexist on the same segment.
data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]
- canbus.send:
# Standard ID by default
can_id: 0y100
can_id: 0x100
data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]
canbus:

2
components/climate/bang_bang.rst
View File

@ -70,6 +70,8 @@ Configuration variables:
------------------------
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity.
This is used for information only and does not influence temperature control.
- **default_target_temperature_low** (**Required**, float): The default low target temperature for
the control algorithm. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (**Required**, float): The default high target temperature for

62
components/climate/climate_ir.rst
View File

@ -33,6 +33,8 @@ submit a feature request (see FAQ).
+---------------------------------------+---------------------+----------------------+
| Fujitsu General | ``fujitsu_general`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`GREE<gree_ir>` | ``gree`` | |
+---------------------------------------+---------------------+----------------------+
| Hitachi | ``hitachi_ac344`` | yes |
| | ``hitachi_ac424`` | |
+---------------------------------------+---------------------+----------------------+
@ -42,6 +44,8 @@ submit a feature request (see FAQ).
+---------------------------------------+---------------------+----------------------+
| Mitsubishi | ``mitsubishi`` | |
+---------------------------------------+---------------------+----------------------+
| Noblex | ``noblex`` | yes |
+---------------------------------------+---------------------+----------------------+
| TCL112, Fuego | ``tcl112`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`Toshiba<toshiba>` | ``toshiba`` | yes |
@ -52,6 +56,8 @@ submit a feature request (see FAQ).
+---------------------------------------+---------------------+----------------------+
| :ref:`Whynter<whynter>` | ``whynter`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`ZH/LT-01<zhlt01>` | ``zhlt01`` | yes |
+---------------------------------------+---------------------+----------------------+
This component requires that you have configured a :doc:`/components/remote_transmitter`.
@ -322,6 +328,62 @@ Configuration variables:
supports_heat: true
.. _gree_ir:
``gree`` Climate
---------------------
Additional configuration is available for this model.
Configuration variables:
- **model** (*Required*, string): GREE has a few different protocols depending on model. One of these will work for you.
- ``generic``
- ``yan``
- ``yaa``
- ``yac``
.. code-block:: yaml
# Example configuration entry
climate:
- platform: gree
name: "AC"
sensor: room_temperature
model: yan
.. _zhlt01:
``zhlt01`` Climate
---------------------
ZH/LT-01 is a remote control that is used with many locally branded split airconditioners.
Supported brands include:
- Eurom
- Chigo
- Tristar
- Tecnomaster
- Elgin
- Geant
- Tekno
- Topair
- Proma
- Sumikura
- JBS
- Turbo Air
- Nakatomy
- Celestial Air
- Ager
- Blueway
- Airlux
No additional configuration is required for this model.
See Also
--------

10
components/climate/custom.rst
View File

@ -1,6 +1,16 @@
Custom Climate
==============
.. warning::
Custom components are deprecated, not recommended for new configurations
and will be removed from ESPHome in a future release.
Please look at creating a real ESPHome component and "importing" it into your
configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom climate devices in ESPHome
using the C++ (Arduino) API.

5
components/climate/haier.rst
View File

@ -106,7 +106,10 @@ Configuration variables:
- **protocol** (*Optional*, string): Defines protocol of communication with AC. Possible values: hon or smartair2. Default value is smartair2.
- **name** (**Required**, string): The name of the climate device.
- **wifi_signal** (*Optional*, boolean): If true - send wifi signal level to AC.
- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. Default value is 150ms.
- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. Default value is 200ms.
- **alternative_swing_control** (*Optional*, boolean): (supported by smartAir2 only) If true - use alternative values to control swing mode. Use only if the original control method is not working for your AC.
- **control_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the control packet. Can help with some newer models of ACs that use bigger packets. Default value: 10.
- **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 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.

41
components/climate/index.rst
View File

@ -15,6 +15,10 @@ and can be put in different modes like ``HEAT``, ``COOL``, ``HEAT_COOL`` or ``OF
Climate Device UI in Home Assistant.
.. note::
Not all climate components support all possible features. Check the corresponding documentation page for details on what is supported.
.. _config-climate:
Base Climate Configuration
@ -30,6 +34,15 @@ All climate platforms in ESPHome inherit from the climate configuration schema.
min_temperature: 18
max_temperature: 25
temperature_step: 0.1
min_humidity: 30%
max_humidity: 99%
- platform: ...
visual:
min_temperature: 18
max_temperature: 25
temperature_step:
target_temperature: 0.5
current_temperature: 0.1
Configuration variables:
@ -55,6 +68,11 @@ Configuration variables:
- **target_temperature** (**Required**, float): The granularity for target temperature
- **current_temperature** (**Required**, float): The granularity for current temperature
- **min_humidity** (*Optional*, percentage): The minimum humidity the climate device can reach.
Used to set the range of the frontend gauge.
- **max_humidity** (*Optional*, percentage): The maximum humidity the climate device can reach.
Used to set the range of the frontend gauge.
Advanced options:
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
@ -74,6 +92,8 @@ MQTT options:
climate device action changes to.
- **current_temperature_state_topic** (*Optional*, string): The topic to publish
current temperature changes to.
- **current_humidity_state_topic** (*Optional*, string): The topic to publish
current humidity changes to.
- **fan_mode_state_topic** (*Optional*, string): The topic to publish
fan mode changes to.
- **fan_mode_command_topic** (*Optional*, string): The topic to receive
@ -102,19 +122,12 @@ MQTT options:
lower target temperature changes to.
- **target_temperature_low_command_topic** (*Optional*, string): The topic to receive
lower target temperature commands on.
- **target_humidity_state_topic** (*Optional*, string): The topic to publish
target humidity changes to.
- **target_humidity_command_topic** (*Optional*, string): The topic to receive
target humidity commands on.
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
.. code-block:: yaml
climate:
- platform: ...
visual:
min_temperature: 18
max_temperature: 25
temperature_step:
target_temperature: 0.5
current_temperature: 0.1
Climate Automation
------------------
@ -152,6 +165,8 @@ Configuration variables:
lower target temperature of a climate device with a two-point target temperature.
- **target_temperature_high** (*Optional*, float, :ref:`templatable <config-templatable>`): Set the
higher target temperature of a climate device with a two-point target temperature.
- **target_humidity** (*Optional*, float, :ref:`templatable <config-templatable>`): Set the
target humidity of a climate device.
- **preset** (*Optional*, string, :ref:`templatable <config-templatable>`): Set the preset
of the climate device. One of ``ECO``, ``AWAY``, ``BOOST``, ``COMFORT``, ``HOME``, ``SLEEP``,
``ACTIVITY``.
@ -181,12 +196,16 @@ advanced stuff.
id(my_climate).mode
// Current temperature, type: float (degrees)
id(my_climate).current_temperature
// Current humidity, type: float (percentage)
id(my_climate).current_humidity
// Target temperature, type: float (degrees)
id(my_climate).target_temperature
// Lower Target temperature, type: float (degrees)
id(my_climate).target_temperature_low
// High Target temperature, type: float (degrees)
id(my_climate).target_temperature_high
// Target humidity, type: float (percentage)
id(my_climate).target_humidity
// Fan mode, type: FanMode (enum)
id(my_climate).fan_mode
// Custom Fan mode, type: string

6
components/climate/pid.rst
View File

@ -53,6 +53,8 @@ Configuration variables:
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current
temperature.
- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity.
This is used for information only and does not influence temperature control.
- **default_target_temperature** (**Required**, float): The default target temperature (setpoint)
for the control algorithm. This can be dynamically set in the frontend later.
- **heat_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output <config-output>`
@ -68,9 +70,9 @@ Configuration variables:
Defaults to ``0``.
- **kd** (*Optional*, float): The factor for the derivative term of the PID controller.
Defaults to ``0``.
- **min_integral** (*Optional*, float): The maximum value of the integral term multiplied by
- **min_integral** (*Optional*, float): The minimum value of the integral term multiplied by
``ki`` to prevent windup. Defaults to ``-1``.
- **max_integral** (*Optional*, float): The minimum value of the integral term multiplied by
- **max_integral** (*Optional*, float): The maximum value of the integral term multiplied by
``ki`` to prevent windup. Defaults to ``1``.
- **starting_integral_term** (*Optional*, float): Set the initial output, by priming the integral
term. This is useful for when your system is rebooted and you don't want to wait

2
components/climate/thermostat.rst
View File

@ -168,6 +168,8 @@ Configuration Variables:
The thermostat controller uses the sensor to determine whether it should heat or cool.
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity.
This is used for information only and does not influence temperature control.
Heating and Cooling Actions
***************************

18
components/copy.rst
View File

@ -193,6 +193,24 @@ Configuration variables:
- **name** (**Required**, string): The name of the text sensor.
- All other options from :ref:`Text Sensor <config-text_sensor>`.
Copy Text
---------
.. code-block:: yaml
# Example configuration entry
text:
- platform: copy
source_id: source_text
name: "Copy of source_text"
Configuration variables:
************************
- **source_id** (**Required**, :ref:`config-id`): The text that should be mirrored.
- **name** (**Required**, string): The name of the number.
- All other options from :ref:`Text <config-text>`.
See Also
--------

10
components/cover/custom.rst
View File

@ -1,6 +1,16 @@
Custom Cover
============
.. warning::
Custom components are deprecated, not recommended for new configurations
and will be removed from ESPHome in a future release.
Please look at creating a real ESPHome component and "importing" it into your
configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom covers in ESPHome
using the C++ (Arduino) API.

109
components/cover/he60r.rst Normal file
View File

@ -0,0 +1,109 @@
HE60R Garage Door Opener
========================
.. seo::
:description: Setting up a Chamberlain HomEntry HE60R and similar garage door openers
:image: he60r.jpg
.. figure:: images/he60r.jpg
:align: right
The ``he60r`` cover platform allows you to control a HomEntry HE60R
garage door opener. These units were made by Chamberlain and sold through Bunnings. It is *likely* that this
component will also work with other older Chamberlain garage door openers. It is not currently compatible with
newer Chamberlain units that use the Security+ 2.0 protocol.
This component makes use of the HE60R keypad communication interface. This is a single-wire half duplex serial
connection and requires a :ref:`uart` component to be configured. The uart **must** be set to 1200 baud, EVEN parity. See
below for a sample hardware interface.
.. code-block:: yaml
# Example configuration entry
uart:
- id: door_uart
baud_rate: 1200
parity: even
stop_bits: 1
tx_pin: REPLACEME
rx_pin: REPLACEME
cover:
platform: he60r
id: garage_door
name: Garage Door
Configuration variables:
------------------------
- **open_duration** (*Optional*, :ref:`config-time`): The time required for the door to fully open from the closed position. Default 15s.
- **close_duration** (*Optional*, :ref:`config-time`): The time required for the door to fully close from the open position. Default 15s.
- All other options from :ref:`Cover <config-cover>`.
The open and close duration serve to estimate the position to provide feedback during travel and for partial open/close
requests. These can be adjusted according to your door's actual operation. Enabling DEBUG logging will report the
actual open and close times which will help to refine these timings.
Hardware Connection
-------------------
A sample circuit is shown below which also draws power from the HE60R - note that the 3.3V regulator must
be a switching type, a linear regulator would draw too much current and run hot. You can of course simply power
the ESP32 via USB from 5V. This circuit also includes a manual control button connected to a GPIO.
Any microcontroller board supported by ESPHome should be suitable for this application.
.. figure:: images/he60r-sch.jpg
:target: /_images/he60r-sch.jpg
Note that this circuit inverts the TX line. A configuration for this would look something like:
.. code-block:: yaml
# Example configuration entry
uart:
- id: door_uart
baud_rate: 1200
parity: even
stop_bits: 1
tx_pin:
number: REPLACEME
inverted: true
rx_pin: REPLACEME
cover:
platform: he60r
id: garage_door
name: Garage Door
binary_sensor:
- platform: gpio
pin:
number: REPLACEME
inverted: true
mode:
input: true
pullup: true
name: "Garage Door Manual Button"
# debounce the switch
filters:
- delayed_on: 50ms
- delayed_off: 50ms
on_press:
then:
- cover.toggle: garage_door
See Also
--------
- :doc:`index`
- :ref:`automation`
- :ref:`gpio-binary-sensor`
- :ghedit:`Edit`

BIN
components/cover/images/he60r-sch.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 101 KiB

BIN
components/cover/images/he60r.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

2
components/cover/template.rst
View File

@ -52,6 +52,8 @@ Configuration variables:
be performed when the remote requests the cover to be closed.
- **stop_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be stopped.
- **toggle_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests to toggle the the cover.
- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
any command sent to the template cover will immediately update the reported state and no lambda
needs to be used. Defaults to ``false``.

267
components/dfrobot_sen0395.rst Normal file
View File

@ -0,0 +1,267 @@
DFRobot mmWave Radar
====================
.. seo::
:description: Instructions for setting up DFRobot mmWave Radar
:image: dfrobot_sen0395.jpg
:keywords: mmWave
The `DFRobot mmWave Radar <https://wiki.dfrobot.com/mmWave_Radar_Human_Presence_Detection_SKU_SEN0395>`__
(aka ``SEN0395``) is a 24GHz radar which can be used for human presence detection. It can detect tiny movements
and compared to a PIR sensor **it can detect presence continuously**. This can be useful, for example, to turn
the lights on when you enter a room, keep them on as long as you are there (without waving your hands at the
sensor) and turn them off almost immediately after you leave the room.
It is possible to use this sensor with only a single GPIO pin; however, if you wish to change its settings,
a :doc:`/components/uart` component (and its requisite GPIO pins) is required in your device's configuration.
.. figure:: images/dfrobot_sen0395-full.jpg
:align: center
:width: 75%
DFRobot mmWave Radar / presence detection sensor
.. code-block:: yaml
# Example configuration entry
dfrobot_sen0395:
binary_sensor:
# Information coming from uart bus
- platform: dfrobot_sen0395
name: Mmwave Detected via UART
# Information coming from dedicated gpio (IO2)
- platform: gpio
name: Mmwave Detected via GPIO
device_class: motion
pin:
number: REPLACEME
mode: INPUT_PULLDOWN
switch:
# Switch to turn on/off detection
- platform: dfrobot_sen0395
name: Mmwave Active
.. _dfrobot_sen0395-component:
Hub Component
-------------
You only need to have the hub component (``dfrobot_sen0395:`` entry) defined if you want to change the sensor's
settings or read its state via the UART. A :doc:`/components/binary_sensor/gpio` alone is sufficient if you only want
to determine presence/occupancy. When you define ``dfrobot_sen0395:`` you'll need to have a ``uart:`` entry in
your configuration with both the TX and RX pins defined and the baud rate must be set to ``115200``.
Multiple instances of this component may be defined if multiple :doc:`/components/uart` components are available:
.. code-block:: yaml
dfrobot_sen0395:
- id: mmWave_1
uart_id: uart_1
- id: mmWave_2
uart_id: uart_2
...
Configuration variables:
************************
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Necessary if you want
to define multiple instances of this component.
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :doc:`/components/uart` if you want
to use multiple UART buses.
.. _dfrobot_sen0395-binary_sensor:
Binary Sensor
-------------
.. _dfrobot_sen0395-via_gpio:
Via GPIO
********
To determine presence, you can simply use a :doc:`/components/binary_sensor/gpio` and connect a single GPIO pin
from your processor to the IO2 pin of the mmWave radar. Using a dedicated GPIO pin may offer an advantage since
it may wake the processor from sleep.
If you don't want/need to change the radar's settings and only need to determine presence/occupancy, the
``dfrobot_sen0395:`` and ``uart:`` components are not necessary.
.. code-block:: yaml
binary_sensor:
- platform: gpio
name: Presence Detected via GPIO
device_class: motion
pin:
number: REPLACEME
mode: INPUT_PULLDOWN
.. _dfrobot_sen0395-via_uart:
Via UART
********
Connecting the sensor via the serial connection (UART) allows both changing its settings as well as reading its state.
Note, however, that the UART peripheral cannot wake the processor; if you plan on sleeping the processor, you'll likely
still need to use the :ref:`GPIO pin <dfrobot_sen0395-via_gpio>` approach described above (in addition to the UART).
First, setup a :doc:`/components/uart` and :ref:`dfrobot_sen0395-component` and then use its binary sensor platform
to create individual binary sensors for each presence sensor.
.. code-block:: yaml
binary_sensor:
- platform: dfrobot_sen0395
name: Presence Detected via UART
Configuration variables:
************************
- **dfrobot_sen0395_id** (*Optional*, :ref:`config-id`): The ID of the DFRobot mmWave component defined above.
Required when multiple instances of the ``dfrobot_sen0395`` component are defined.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. _dfrobot_sen0395-switch:
Switch
------
:ref:`Switch components <config-switch>` are used to enable/disable various module features/functions.
.. code-block:: yaml
switch:
- platform: dfrobot_sen0395
dfrobot_sen0395_id: mmWave
type: sensor_active
name: mmWave Active
Configuration variables:
************************
- **dfrobot_sen0395_id** (*Optional*, :ref:`config-id`): The ID of the DFRobot mmWave component defined above.
Required when multiple instances of the ``dfrobot_sen0395`` component are defined.
- **type** (**Required**): One of:
- ``presence_via_uart``: when enabled, the module sends presence information via both the serial connection and
GPIO pin; when disabled, presense is indicated only via the GPIO pin.
- ``sensor_active``: when enabled, presence detection is reported; when disabled, presense will not be reported.
- ``start_after_boot``: when enabled, the sensor will start immediately after power-on; when disabled, the sensor
must be manually started.
- ``turn_on_led``: when enabled, the mmWave sensor's LED blinks during operation; when disabled, the LED will always
remain off.
- All other options from :ref:`Switch <config-switch>`.
.. _dfrobot_sen0395-actions:
Actions
-------
.. _dfrobot_sen0395-action_settings:
``dfrobot_sen0395.settings`` Action
***********************************
.. warning::
Each change to the configuration of the mmWave radar triggers a write to its internal flash/EEPROM.
Write cycles to this memory are limited, so avoid the practice of changing settings frequently.
Determine the appropriate settings for your device and avoid changing them unless absolutely necessary.
The DFRobot mmWave Radar has several settings which can be changed. These settings are saved in non-volatile memory
and do not need to be set on each boot.
The settings action allows changing of any number of the mmWave radar's internal parameters/settings. With this
action, any unspecified parameters will remain unchanged. All settings are tempatable.
.. code-block:: yaml
on_...:
- dfrobot_sen0395.settings:
factory_reset: true
detection_segments:
# Define between one and four segments
- [0cm, 3m]
- [5.1m, 6.6m]
output_latency:
delay_after_detect: 0s
delay_after_disappear: 0s
sensitivity: 7
Configuration variables:
````````````````````````
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the mmWave sensor on which settings should be
changed. If only one radar is defined, this is optional.
- **factory_reset** (*Optional*, boolean): If set to true, a factory reset of the sensor will be performed (before
changing other options if present). Ignored if not set or set to ``false``.
- **detection_segments** (*Optional*, list): A list of detection segments. A segment specifies from where to where
detection should trigger. One to four segments and ranges from 0cm to 9m may be specified. Distances should be
defined in steps of 15cm. Note that the specified ranges are rounded internally. Segments can be defined in a
one or two dimensional list. Pairs of values must be defined (from distance to distance). The default is one
range from 0cm to 3m.
**Examples**
.. code-block:: yaml
detection_segments:
- [0cm, 3m]
- [5.1m, 6.6m]
In the above example, if a person was present in the range between 0cm and 3m (distance from the sensor) or
between 5.1m and 6.6m the sensor would trigger (meaning a person was detected). If a person is present
between 3.1m and 5m or 6.7m and 9m it would not trigger.
.. code-block:: yaml
detection_segments:
- !lambda |-
return 0;
- !lambda |-
return return id(mwave_max_distance).state;
Section values can be defined using lambdas, so you can set the distances depending on other entities. Distances
are defined as a float in meters (10cm = 0.1). If you return a negative value (-1) the segment will not be set.
- **output_latency** (*Optional*, dictionary):
- **delay_after_detect** (**Required**, :ref:`config-time`): Time to wait before signaling that a person was
detected. Specify in steps of 25 ms. Factory default is 2.5s. Value is tempatable: Return seconds value
(100 ms = 0.1). Returning -1 keeps the value unchanged.
- **delay_after_disappear** (**Required**, :ref:`config-time`): Time to wait before signaling that a person
is no longer detected. Specify in steps of 25 ms. Factory default is 10 s. Value is tempatable: Return seconds
value (100 ms = 0.1). Returning -1 keeps the value unchanged.
- **sensitivity** (*Optional*, int): Set the sensitivity of the sensor. Ranges from 0 to 9. Value is tempatable:
Return 0-9. Returning -1 keeps the value unchanged.
``dfrobot_sen0395.reset`` Action
********************************
Restart the sensor.
.. code-block:: yaml
on_...:
dfrobot_sen0395.reset:
Configuration variables:
````````````````````````
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the mmWave component. Useful when multiple instances of this component are defined.
See Also
--------
- :ref:`UART bus <uart>`
- :ref:`Binary Sensor <config-binary_sensor>`
- :ref:`config-id`
- `DFRobot mmWave Radar Wiki page <https://wiki.dfrobot.com/mmWave_Radar_Human_Presence_Detection_SKU_SEN0395>`__
- :ghedit:`Edit`

64
components/display/ili9xxx.rst
View File

@ -1,4 +1,3 @@
ILI9xxx TFT LCD Series
======================
@ -14,6 +13,7 @@ With this display driver you can control the following displays:
- ILI9341
- ILI9342
- ILI9481
- ILI9481-18 (ILI9481 in 18 bit, i.e. 262K color, mode)
- ILI9486
- ILI9488
- ILI9488_A (alternative gamma configuration for ILI9488)
@ -21,6 +21,7 @@ With this display driver you can control the following displays:
- S3BOX
- S3BOX_LITE
- ST7796
- ST7789V
- TFT 2.4
- TFT 2.4R
@ -36,7 +37,7 @@ ILI9341 (`datasheet <https://cdn-shop.adafruit.com/datasheets/ILI9341.pdf>`__,
displays from the same chip family with ESPHome. As this is a somewhat higher resolution display and may require pins
beyond the typical SPI connections, it is better suited for use with the ESP32.
**Note:** To use 16bit instead of 8bit colors use a esp32 with enough PSRAM the display.
**Note:** use of 16 bit colors requires double the amount of RAM as 8 bit, and may need PSRAM to be available.
.. figure:: images/ili9341-full.jpg
:align: center
@ -62,15 +63,13 @@ Configuration variables:
- **model** (**Required**): The model of the display. Options are:
- ``M5STACK``, ``TFT 2.4``, ``TFT 2.4R``, ``S3BOX``, ``S3BOX_LITE``
- ``ILI9341``, ``ILI9342``, ``ILI9481``, ``ILI9486``, ``ILI9488``, ``ILI9488_A`` (alternative gamma configuration for ILI9488), ``ST7796``
.. note:: According to its documentation, the ESP32 S3 Box Lite has an ST7789V display driver. We've found, however, that it works with the ILIxxxx component here, instead. This could change in the future.
- ``M5STACK``, ``TFT 2.4``, ``TFT 2.4R``, ``S3BOX``, ``S3BOX_LITE``, ``ST7789V``
- ``ILI9341``, ``ILI9342``, ``ILI9486``, ``ILI9488``, ``ILI9488_A`` (alternative gamma configuration for ILI9488)
- ``ILI9481``, ``ILI9481-18`` (18 bit mode)
- ``ST7789V``, ``ST7796``
- **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **rotation** (*Optional*): Set the rotation of the display. Everything drawn in the ``lambda:`` will be rotated
per this option. One of ``0°`` (default), ``90°``, ``180°``, or ``270°``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
@ -83,10 +82,33 @@ Configuration variables:
- ``NONE`` (default)
- ``GRAYSCALE``
- ``IMAGE_ADAPTIVE``
- **color_order** (*Optional*): Should be one of ``bgr`` (default) or ``rgb``.
- **color_palette_images** (*Optional*): A list of image files that will be used to generate the color pallet for the display. This should only be used in conjunction with ``-color_palette: IMAGE_ADAPTIVE`` above. The images will be analysed at compile time and a custom color pallet will be created based on the most commonly occuring colors. A typical setting would be a sample image that represented the fully populated display. This can significantly improve the quality of displayed images. Note that these images are not stored on the ESP device, just the 256byte color pallet created from them.
- **dimensions** (*Optional*): Dimensions of the screen with WIDTHxHEIGHT. Usually not needed since ``model:`` has good defaults.
- **dimensions** (*Optional*): Dimensions of the screen, specified either as *width* **x** *height* (e.g ``320x240``) or with separate config keys. If not provided the dimensions will be determined by the model selected.
- **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`` (default), ``20MHz``, ``10MHz``, ``5MHz``, ``2MHz``, ``1MHz``, ``200kHz``, ``75kHz`` or ``1kHz``. If you have multiple ILI9xxx displays they must all use the same **data_rate**.
- **invert_display** (*Optional*): With this boolean option you can invert the some of the display colors manual. **Note** some of the displays have this option set automatically to true and can't be changed.
- **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.
**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``
Configuration examples
**********************
@ -172,6 +194,28 @@ To configure an image adaptive color pallet to show greater than 8 bit color dep
lambda: |-
it.image(0, 0, id(myimage));
Using the ``transform`` options to hardware rotate the display on a Lilygo T-Embed. This has an st7789v but only uses 170 pixels of the 240 width.
This config rotates the display into landscape mode using the driver chip.
.. code-block:: yaml
display:
- platform: ili9xxx
model: st7789v
height: 170
width: 320
offset_height: 35
offset_width: 0
transform:
swap_xy: true
mirror_x: false
mirror_y: true
color_order: bgr
data_rate: 80MHz
cs_pin: 10
dc_pin: GPIO13
reset_pin: GPIO9
See Also
--------

2
components/display/images/lcd_gpio.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 186 KiB

After

Width:  |  Height:  |  Size: 186 KiB

84
components/display/index.rst
View File

@ -24,6 +24,11 @@ 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
@ -180,6 +185,11 @@ Next, create a ``font:`` section in your configuration:
- file: "fonts/tom-thumb.bdf"
id: tomthumb
- file: 'gfonts://Material+Symbols+Outlined'
id: icon_font_50
size: 50
glyphs: ["\U0000e425"] # mdi-timer
display:
# ...
@ -192,7 +202,8 @@ Configuration variables:
**Google Fonts**:
Each Google Font will be downloaded once and cached for future use.
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:
@ -231,7 +242,7 @@ Configuration variables:
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>4.0.0,<10.0.0"``.
``pip install "pillow==10.1.0"``.
.. _display-static_text:
@ -396,10 +407,10 @@ You can display current time using a time component. Please see the example :ref
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
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.
With ``start_clipping(left, top, right, bottom);`` start you the clipping process and when you are done drawing in that region
With ``start_clipping(left, top, right, bottom);`` start you the clipping process and when you are done drawing in that region
you can stop the clipping process with ``end_clipping();`` . You can nest as many ``start_clipping();`` as you want as long
you end them as many times as well.
@ -409,7 +420,7 @@ you end them as many times as well.
- platform: ...
# ...
id: my_binary_sensor
color:
- name: my_red
red: 100%
@ -428,12 +439,12 @@ you end them as many times as well.
it.printf(0, 0, id(my_font), id(my_red), "State: %s", id(my_binary_sensor).state ? "ON" : "OFF");
it.end_clipping();
After you started clipping you can manipulate the region with ``extend_clipping(left, top, right, bottom);``
After you started clipping you can manipulate the region with ``extend_clipping(left, top, right, bottom);``
and ``shrink_clipping(left, top, right, bottom);`` within previous set clipping region.
With ``get_clipping();`` you get a ``Rect`` object back with the latest set clipping region.
.. code-block:: cpp
.. code-block:: cpp
class Rect {
int16_t x; ///< X/Left coordinate
@ -667,6 +678,13 @@ Use this component to store graphical images on the device, you can then draw th
id: alert
resize: 80x80
.. code-block:: yaml
image:
- file: https://esphome.io/_images/logo.png
id: esphome_logo
resize: 200x162
Configuration variables:
- **file** (**Required**, string):
@ -674,7 +692,8 @@ Configuration variables:
- **Local files**: The path (relative to where the .yaml file is) of the image file.
- **Material Design Icons**: Specify the `Material Design Icon <https://pictogrammers.com/library/mdi/>`_
id in the format ``mdi:icon-name``, and that icon will automatically be downloaded and added to the configuration.
- **Remote files**: The URL of the image file.
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later
in your display code.
- **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT``
@ -951,6 +970,55 @@ You can then switch between these with three different actions:
Additionally the old page will be given as the variable ``from`` and the new one as the variable ``to``.
.. _troubleshooting:
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
the best way to help you, **a picture of the result of this script is very helpful.**
Should you `create an issue <https://github.com/esphome/issues/issues>`__ in GitHub regarding your display, please
be sure to **include a link to where you purchased it** so that we can validate the configuration you've used.
.. code-block:: yaml
display:
- platform: ...
...
lambda: |-
int shift_x = (it.get_width()-310)/2;
int shift_y = (it.get_height()-256)/2;
for(auto i = 0; i<256; i++) {
it.horizontal_line(shift_x+ 0,i+shift_y,50, my_red.fade_to_white(i));
it.horizontal_line(shift_x+ 50,i+shift_y,50, my_red.fade_to_black(i));
it.horizontal_line(shift_x+105,i+shift_y,50, my_green.fade_to_white(i));
it.horizontal_line(shift_x+155,i+shift_y,50, my_green.fade_to_black(i));
it.horizontal_line(shift_x+210,i+shift_y,50, my_blue.fade_to_white(i));
it.horizontal_line(shift_x+260,i+shift_y,50, my_blue.fade_to_black(i));
}
it.rectangle(shift_x+ 0, 0+shift_y, shift_x+ 310, 256+shift_y, my_yellow);
color:
- id: my_blue
blue: 100%
- id: my_red
red: 100%
- id: my_green
green: 100%
- id: my_white
red: 100%
blue: 100%
green: 100%
- id: my_yellow
hex: ffff00
See Also
--------

8
components/display/lcd_display.rst
View File

@ -90,10 +90,10 @@ faster refresh, especially in conjunction with an :ref:`LCD Menu <lcd_menu>`.
- platform: lcd_gpio
dimensions: 20x4
data_pins:
- D0
- D1
- D2
- D3
- GPIO32
- GPIO33
- GPIO5
- GPIO17
enable_pin: D4
rs_pin: D5
lambda: |-

33
components/display/nextion.rst
View File

@ -64,12 +64,15 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **tft_url** (*Optional*, string): The URL to download the TFT file from for updates. See :ref:`Nextion Upload <nextion_upload_tft>`.
- **touch_sleep_timeout** (*Optional*, int): Sets internal No-touch-then-sleep timer in seconds.
- **start_up_page** (*Optional*, int): Sets the page to display when ESPHome connects to the Nextion. (Nextion shows page 0 on start-up by default).
- **wake_up_page** (*Optional*, int): Sets the page to display after waking up
- **auto_wake_on_touch** (*Optional*, boolean): Sets if Nextion should auto-wake from sleep when touch press occurs.
- **exit_reparse_on_start** (*Optional*, boolean): Request the Nextion exit Active Reparse Mode before setup of the display. Defaults to ``false``.
- **on_setup** (*Optional*, :ref:`Action <config-action>`): An action to be performed after ESPHome connects to the Nextion. See :ref:`Nextion Automation <nextion-on_setup>`.
- **on_sleep** (*Optional*, :ref:`Action <config-action>`): An action to be performed when the Nextion goes to sleep. See :ref:`Nextion Automation <nextion-on_sleep>`.
- **on_wake** (*Optional*, :ref:`Action <config-action>`): An action to be performed when the Nextion wakes up. See :ref:`Nextion Automation <nextion-on_sleep>`.
- **on_page** (*Optional*, :ref:`Action <config-action>`): An action to be performed after a page change. See :ref:`Nextion Automation <nextion-on_page>`.
- **on_touch** (*Optional*, :ref:`Action <config-action>`): An action to be performed after a touch event (press or release). See :ref:`Nextion Automation <nextion-on_touch>`.
.. _display-nextion_lambda:
@ -197,7 +200,8 @@ With Nextion displays, it's possible to define several automation actions. Depen
This automation will be triggered once ESP establishes a connection with Nextion. This happens after a boot up and may take some
noticeable time (e.g. hundreds of milliseconds) to establish a connection over UART. Typical use scenario for this automation is choosing of the initial
page to display depending on some runtime conditions or simply showing a page with a non-zero index (Nextion shows page 0 by default).
page to display depending on some runtime conditions or simply showing a page with a non-zero index (Nextion shows page 0 by default and ESPHome will
use ``start_up_page`` on connection, if set).
.. code-block:: yaml
@ -235,7 +239,7 @@ for that and :ref:`force-update <nextion_update_all_components>` the on-screen c
***********
This automation is triggered when a page is changed on the Nextion display. This includes both ESP and Nextion initiated page changes.
ESP initiates a page change by calling ``goto_page("page_name")`` function. Nextion can change pages as a reaction to user's activity (e.g. clicks) or using a timer.
ESP initiates a page change by calling ``goto_page("page_name")`` or ``goto_page(page_id)`` function. Nextion can change pages as a reaction to user's activity (e.g. clicks) or using a timer.
In either case, this automation can be helpful to update on-screen controls for the newly displayed page.
If you fully own your Nextoin HMI design and follow the best practice of setting the components' vscope to global in the Nextion Editor, you'll probably never need this trigger.
@ -257,6 +261,31 @@ Once you know the page id, it's time to update the components. Two strategies wo
break;
}
.. _nextion-on_touch:
``on_touch``
************
This automation is triggered when a component is pressed or released on the Nextion display.
The following arguments will be available:
- ``page_id``: Contains the id (integer) of the page where the touch happened.
- ``component_id``: Contains the id (integer) of the component touched. It's required that the component have "Send Component ID" enabled either for "Touch Press Event" and/or "Touch Release Event".
- ``touch_event``: It will be ``true`` for a "press" event, or ``false`` for a "release" event.
.. code-block:: yaml
on_touch:
then:
lambda: |-
ESP_LOGD("nextion.on_touch", "Nextion touch event detected!");
ESP_LOGD("nextion.on_touch", "Page Id: %i", page_id);
ESP_LOGD("nextion.on_touch", "Component Id: %i", component_id);
ESP_LOGD("nextion.on_touch", "Event type: %s", touch_event ? "Press" : "Release");
.. _nextion_upload_tft_file:
Uploading A TFT File

15
components/display/ssd1306.rst
View File

@ -12,7 +12,9 @@ Over I²C
The ``ssd1306_i2c`` display platform allows you to use
SSD1306 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf>`__,
`Adafruit <https://www.adafruit.com/product/326>`__), SSD1305 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1305.pdf>`__)
`Adafruit <https://www.adafruit.com/product/326>`__), SSD1305 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1305.pdf>`__),
SH1107 (`datasheet <https://cdn-learn.adafruit.com/assets/assets/000/094/580/original/SH1107_datasheet.pdf>`__,
`Adafruit <https://www.adafruit.com/product/4650>`__)
and SH1106 (`datasheet <https://www.elecrow.com/download/SH1106%20datasheet.pdf>`__,
`electrodragon <https://www.electrodragon.com/product/1-3-12864-blue-oled-display-iicspi/>`__)
displays with ESPHome. Note that this component is for displays that are connected via the :ref:`I²C Bus <i2c>`.
@ -58,6 +60,7 @@ Configuration variables:
- ``SH1106 96x16``
- ``SH1106 64x48``
- ``SH1107 128x64``
- ``SH1107 128x128``
- ``SSD1305 128x32``
- ``SSD1305 128x64``
@ -71,8 +74,8 @@ Configuration variables:
Defaults to ``false``.
- **flip_x** (*Optional*, boolean): Flip the horizontal axis on the screen. Defaults to ``true``.
- **flip_y** (*Optional*, boolean): Flip the vertical axis on the screen. Defaults to ``true``.
- **offset_x** (*Optional*, int): Set this option if some horizontal pixel is missing. Numbers are only allowed between ``-32~32``. Defaults to ``0``.
- **offset_y** (*Optional*, int): Set this option if some vertical pixel is missing. Numbers are only allowed between ``-32~32``. Defaults to ``0``.
- **offset_x** (*Optional*, int): Set this option if some horizontal pixel is missing. Numbers are only allowed between ``0~128``. Defaults to ``0``.
- **offset_y** (*Optional*, int): Set this option if some vertical pixel is missing. Numbers are only allowed between ``0~128``. Defaults to ``0``.
- **invert** (*Optional*, boolean): Invert all pixel state on the display. Defaults to ``false``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
@ -138,6 +141,7 @@ Configuration variables:
- ``SH1106 96x16``
- ``SH1106 64x48``
- ``SH1107 128x64``
- ``SH1107 128x128``
- ``SSD1305 128x32``
- ``SSD1305 128x64``
@ -152,8 +156,8 @@ Configuration variables:
Defaults to ``false``.
- **flip_x** (*Optional*, boolean): Flip the horizontal axis on the screen. Defaults to ``true``.
- **flip_y** (*Optional*, boolean): Flip the vertical axis on the screen. Defaults to ``true``.
- **offset_x** (*Optional*, int): Set this option if some horizontal pixel is missing. Numbers are only allowed between ``-32~32``. Defaults to ``0``.
- **offset_y** (*Optional*, int): Set this option if some vertical pixel is missing. Numbers are only allowed between ``-32~32``. Defaults to ``0``.
- **offset_x** (*Optional*, int): Set this option if some horizontal pixel is missing. Numbers are only allowed between ``0~128``. Defaults to ``0``.
- **offset_y** (*Optional*, int): Set this option if some vertical pixel is missing. Numbers are only allowed between ``0~128``. Defaults to ``0``.
- **invert** (*Optional*, boolean): Invert all pixel state on the display. Defaults to ``false``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
@ -168,6 +172,7 @@ See Also
- :doc:`index`
- :apiref:`ssd1306_base/ssd1306_base.h`
- `SH110x Library <https://github.com/adafruit/Adafruit_SH110x>`__ by `Adafruit <https://www.adafruit.com/>`__
- `SSD1306 Library <https://github.com/adafruit/Adafruit_SSD1306>`__ by `Adafruit <https://www.adafruit.com/>`__
- `SSD1305 Library <https://github.com/adafruit/Adafruit_SSD1305>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

4
components/display/tm1637.rst
View File

@ -46,8 +46,6 @@ Configuration variables:
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``1s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. _display-tm1637_lambda:
Binary Sensor
-------------
@ -79,6 +77,8 @@ Configuration variables:
0 to 15.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. _display-tm1637_lambda:
Rendering Lambda
----------------

206
components/display_menu/graphical_display_menu.rst Normal file
View File

@ -0,0 +1,206 @@
.. _graphical_display_menu:
Graphical Display Menu
======================
.. seo::
:description: Instructions for setting up a simple hierarchical menu on displays.
:image: lcd_menu.png
The component provides an infrastructure for setting up a hierarchical menu
on graphical displays. This offers the user an interactive method to display
labels, control entities like ``switch``, ``select``, ``number`` available locally on the
ESPHome node, without the requirement of a network connection.
.. figure:: images/graphical_display_menu.jpg
:align: center
:width: 60.0%
Overview
--------
The integration implements the :ref:`Display Menu <display_menu>` integration providing
a hierarchical menu primarily intended to be controlled either by a rotary encoder
with a button or a five-button joystick controller.
The component needs to be connected to an instance of a display supporting ESPHome's rendering
engine such as :doc:`E-Paper displays </components/display/waveshare_epaper>` or :doc:`OLED displays </components/display/ssd1306>`.
.. code-block:: yaml
# Example configuration entry
graphical_display_menu:
id: my_graphical_display_menu
display: my_display_component
on_redraw:
then:
component.update: my_dispay_component
active: false
mode: rotary
items:
...
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **display** (*Optional*, :ref:`config-id`): ID of the display to render to. See
:ref:`drawing_modes` for more details
- **font** (:ref:`Font <display-fonts>`): Specifies the font to use
- **foreground_color** (*Optional*, :ref:`config-color`): Specifies the foreground color to use.
Defaults to COLOR_ON
- **background_color** (*Optional*, :ref:`config-color`): Specifies the background color to use.
Defaults to COLOR_OFF
Automations:
- **on_redraw** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the menu needs to be redrawn. This can be useful if your display has slow refresh rates.
For example E-Ink displays that are used with `display_interval: never`
Additional configuration is described in the :ref:`Display Menu <display_menu>` component.
.. _drawing_modes:
Drawing Modes
-------------
Pop Up Mode
***********
When a **display** is specified the menu will create a :ref:`page <display-pages>` as part of the initialisation. It will render to the entire
of the display when invoked. This is useful when you may want to use the display for other purposes but show a menu in response to user
interaction.
Advanced Drawing Mode
*********************
If you do not specify a **display** when setting up a menu you will be responsible for controlling drawing of the menu. This also allows you to
render the menu to a smaller portion than the available screen size. It May be useful in situations where you want to display a menu as part of a
larger user interface (for example rendering a sensor graph and a control menu next to it)
.. code-block:: yaml
# Example configuration entry
graphical_display_menu:
- id: my_menu
# Note: No display specified
active: true
display:
- platform: waveshare_epaper
id: my_display_component
pages:
- id: advanced_drawing_mode_page
lambda: |-
const auto display_width = it.get_width();
const auto display_height = it.get_height();
auto half_display_width = (int)(display_width / 2.0f);
// This will render the menu to the right half of the screen leaving the left half for other drawing purposes
// Arguments: it.menu(x, y, menu, width, height);
it.menu(half_display_width, 0, id(my_menu), half_display_width, display_height);
Controlling Menu Item Rendering
-------------------------------
By default menu items with a value will be rendered between a set of parenthesis. This can be
controlled via the `menu_item_value` parameter.
- **menu_item_value** (*Optional*, :ref:`config-lambda`): Specifies how to render values for
menu items that have values (eg. Selects, numbers). Defaults to rendering the value as
"(value here)". Receives a MenuItemValueArguments as the argument`it`.
.. code-block:: yaml
graphical_display_menu:
menu_item_value: !lambda |-
// Will render your menu item value as "My menu label ~my value here~"" normally and "My menu label *my value here*" when in edit mode
std::string label = " ";
if (it->is_item_selected && it->is_menu_editing) {
label.append("*");
label.append(it->item->get_value_text());
label.append("*");
} else {
label.append("~");
label.append(it->item->get_value_text());
label.append("~");
}
return label;
.. note::
Ensure that all characters you use in the menu_item_value are available glyphs for your :ref:`font <display-fonts>`
User Interaction Example
------------------------
The below example is a more complete example showing how you might use a rotary encoder and button to display/hide the menu and move through the available options
.. code-block:: yaml
# Example configuration entry
display:
- platform: waveshare_epaper
id: my_display_component
pages:
- id: graph_page
lambda: |-
it.print(0, 0, id(my_font), "My menu is not currently active");
font:
- file: ...
id: my_font
size: 16
graphical_display_menu:
id: my_graphical_display_menu
display: my_display_component
on_redraw:
then:
component.update: my_dispay_component
active: false
mode: rotary
items:
- type: Label
text: Menu Item 1
- type: Label
text: Menu Item 2
# Rotary encoder to provide navigation
sensor:
- platform: rotary_encoder
...
filters:
debounce: 30ms
on_anticlockwise:
- display_menu.up: my_graphical_display_menu
on_clockwise:
- display_menu.down: my_graphical_display_menu
# A debounced GPIO push button is used to 'click'
binary_sensor:
- platform: gpio
...
filters:
- delayed_on: 30ms
- delayed_off: 30ms
on_press:
- if:
condition:
display_menu.is_active: my_graphical_display_menu
then:
- display_menu.enter: my_graphical_display_menu
else:
- display_menu.show: my_graphical_display_menu
See Also
--------
- :ref:`Display Menu <display_menu>`
- :ref:`Display <display-engine>`
- :ref:`display-fonts`
- :ref:`display-pages`
- :apiref:`graphical_display_menu/graphical_display_menu.h`
- :ghedit:`Edit`

BIN
components/display_menu/images/graphical_display_menu.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 101 KiB

138
components/emc2101.rst Normal file
View File

@ -0,0 +1,138 @@
EMC2101 Fan Controller and Temperature sensor
=============================================
.. seo::
:description: Instructions for setting up EMC2101 fan controller and temperature sensor in ESPHome.
:image: emc2101.jpg
:keywords: EMC2101
The ``emc2101`` component allows you to control a cooling fan from ESPHome (`datasheet <https://ww1.microchip.com/downloads/aemDocuments/documents/MSLD/ProductDocuments/DataSheets/EMC2101-Data-Sheet-DS20006703.pdf>`__). It also provides temperature
sensors and a tachometer. The fan can be controlled either by a PWM signal or by outputing a DC voltage
using its DAC.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
.. figure:: images/emc2101-full.png
:align: center
:width: 50.0%
EMC2101 Fan Controller and Temperature sensor
.. note::
Original image at https://learn.adafruit.com/assets/97827 created by
by user `Bryan Siepert <https://learn.adafruit.com/u/siddacious>`__ under
`Creative Commons BY-SA 3.0 <https://creativecommons.org/licenses/by-sa/3.0/>`__ and modified
for this documentation.
EMC2101 Component
-----------------
.. code-block:: yaml
# Example configuration entry
emc2101:
pwm:
resolution: 8
Configuration variables:
************************
- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x4C``.
- **inverted** (*Optional*, boolean): Inverts the output so 0 means 100% duty cycle and 1 means 0%. Defaults to ``false``.
- **pwm** (*Optional*): Enable PWM output.
- **resolution** (*Optional*, int): Determines effective resolution and the frequency of the PWM signal. Defaults to ``23``.
- **divider** (*Optional*, int): Value for the frequency divider. Defaults to ``1``.
- **dac** (*Optional*): Enable DAC output.
- **conversion_rate** (*Optional*, string): The number of digital to analog conversions perfomed per second. One of ``1/16``, ``1/8``,
``1/4``, ``1/2``, ``1``, ``2``, ``4``, ``8``, ``16``, ``32``. Defaults to ``16``.
The PWM signal frequency is determined by the following formula:
.. math::
\text{PWM Frequency} = \frac{360KHz}{2 \times resolution \times divider}
And the PWM resolution, the steps in the duty cycle, is calculated by the following formula:
.. math::
\text{PWM resolution} = \frac{100\%}{2 \times resolution}
So, with the default values the PWM signal will have a frequency of 7.83KHz and a resolution of 2.17%. The maximum
resolution value is ``31`` which will configure a frequency of 5.81KHz with a resolution of 1.61%.
EMC2101 Output
--------------
.. code-block:: yaml
output:
- platform: emc2101
id: fan_duty_cycle
Configuration variables:
************************
- **id** (**Required**, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components.
.. note::
When using the ``emc2101`` output with a :doc:`/components/fan/speed` it is advised to configure the **speed_count**
as twice the **resolution** so the number of speeds in the fan matches the number of steps in the fan controller.
EMC2101 Sensors
---------------
.. code-block:: yaml
sensor:
- platform: emc2101
internal_temperature:
id: internal_temperature_sensor
name: "Internal Temperature Sensor"
speed:
id: speed_sensor
name: "Speed Sensor"
duty_cycle:
id: duty_cycle_sensor
name: "Duty Cycle Sensor"
update_interval: 5s
Configuration variables:
************************
- **internal_temperature** (*Optional*): The internal temperature sensor.
All options from :ref:`Sensor <config-sensor>`.
- **external_temperature** (*Optional*): The external temperature sensor. More accurate but it needs an additional transistor to be installed.
All options from :ref:`Sensor <config-sensor>`.
- **speed** (*Optional*): The fan speed sensor in RPMs.
All options from :ref:`Sensor <config-sensor>`.
- **duty_cycle** (*Optional*): Duty cycle sensor.
All options from :ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
See Also
--------
- :ref:`config-sensor`
- :doc:`/components/fan/speed`
- :apiref:`emc2101/emc2101.h`
- :ghedit:`Edit`

9
components/esp32.rst
View File

@ -23,13 +23,18 @@ Configuration variables:
choose a generic board from Espressif such as ``esp32dev``.
- **framework** (*Optional*): Options for the underlying framework used by ESPHome.
See :ref:`esp32-arduino_framework` and :ref:`esp32-espidf_framework`.
- **flash_size** (*Optional*, string): The amount of flash memory available on the ESP32 board/module. One of ``2MB``,
``4MB``, ``8MB``, ``16MB`` or ``32MB``. Defaults to ``4MB``. **Warning: specifying a size larger than that available
on your board will cause the ESP32 to fail to boot.**
- **partitions** (*Optional*, filename): The name of (optionally including the path to) the file containing the
partitioning scheme to be used. When not specified, partitions are automatically generated based on ``flash_size``.
- **variant** (*Optional*, string): The variant of the ESP32 that is used on this board. One of ``esp32``,
``esp32s2``, ``esp32s3``, ``esp32c3`` and ``esp32h2``. Defaults to the variant that is detected from the board, if
``esp32s2``, ``esp32s3``, ``esp32c3`` and ``esp32h2``. Defaults to the variant that is detected from the board; if
a board that's unknown to ESPHome is used, this option is mandatory.
.. note::
Support for the ESP32-S2 and ESP32-C3 is still in development and there could be issues.
Support for ESP32 variants such as the S2, S3 and C3 is still in development and there could be issues.
GPIO Pin Numbering
------------------

63
components/esp32_ble.rst
View File

@ -8,6 +8,14 @@ BLE Component
The ``esp32_ble`` component in ESPHome sets up the Bluetooth LE stack on the device so that a :doc:`esp32_ble_server`
can run.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml
# Example configuration
@ -26,6 +34,61 @@ Configuration variables:
- ``keyboard_display`` - A keyboard and a display
- ``display_yes_no`` - A display to show PIN codes and buttons to confirm or deny the connection
- **enable_on_boot** (*Optional*, boolean): If enabled, the BLE interface will be enabled on boot. Defaults to ``true``.
``ble.disable`` Action
-----------------------
This action turns off the BLE interface on demand.
.. code-block:: yaml
on_...:
then:
- ble.disable:
.. note::
The configuration option ``enable_on_boot`` can be set to ``false`` if you do not want BLE to be enabled on boot.
``ble.enable`` Action
----------------------
This action turns on the BLE interface on demand.
.. code-block:: yaml
on_...:
then:
- ble.enable:
.. note::
The configuration option ``enable_on_boot`` can be set to ``false`` if you do not want BLE to be enabled on boot.
.. _ble-enabled_condition:
``ble.enabled`` Condition
--------------------------
This :ref:`Condition <config-condition>` checks if BLE is currently enabled or not.
.. code-block:: yaml
on_...:
- if:
condition: ble.enabled
then:
- ble.disable:
else:
- ble.enable:
The lambda equivalent for this is ``id(ble_id).is_active()``.
See Also
--------

7
components/esp32_ble_beacon.rst
View File

@ -9,6 +9,13 @@ The ``esp32_ble_beacon`` component creates a Bluetooth Low Energy Beacon with yo
Beacons are BLE devices that repeatedly just send out a pre-defined packet of data. This packet
can then be received by devices like smartphones and can then be used to track a phone's location.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml

8
components/esp32_ble_server.rst
View File

@ -9,6 +9,14 @@ The ``esp32_ble_server`` component in ESPHome sets up a simple BLE GATT server t
manufacturer and board. This component allows other components to create their own services to expose
data and control.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml
# Example configuration

18
components/esp32_ble_tracker.rst
View File

@ -5,11 +5,19 @@ ESP32 Bluetooth Low Energy Tracker Hub
:description: Instructions for setting up ESP32 bluetooth low energy device trackers using ESPHome.
:image: bluetooth.svg
The ``esp32_ble_tracker`` component creates a global hub so that you can track bluetooth low
energy devices using your ESP32 node.
The ``esp32_ble_tracker`` component creates a global hub so that you can track bluetooth low energy devices
using your ESP32 node.
See :ref:`Setting up devices <esp32_ble_tracker-setting_up_devices>`
for information on how you can find out the MAC address of a device and track it using ESPHome.
See :ref:`Setting up devices <esp32_ble_tracker-setting_up_devices>` for information on how you can determine
the MAC address of a device and track it using ESPHome.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml
@ -139,7 +147,7 @@ Configuration variables:
``on_ble_manufacturer_data_advertise`` Trigger
************************************************
This automation will be triggered when a Bluetooth advertising with manufcaturer data is received. A
This automation will be triggered when a Bluetooth advertising with manufacturer data is received. A
variable ``x`` of type ``std::vector<uint8_t>`` is passed to the automation for use in lambdas.
.. code-block:: yaml

53
components/esp32_camera.rst
View File

@ -162,6 +162,7 @@ Automations:
when a stream starts.
- **on_stream_stop** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when a stream stops.
- **on_image** (*Optional*, :ref:`Automation <automation>`): An automation called when image taken. Image is available as ``image`` variable of type :apistruct:`esp32_camera::CameraImageData`.
Test Setting:
@ -176,6 +177,12 @@ Test Setting:
Configuration for Ai-Thinker Camera
-----------------------------------
.. warning::
GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM.
Using this GPIO for other purposes (eg as a button) will trigger the watchdog.
Further information on pin notes can be found here: https://github.com/raphaelbs/esp32-cam-ai-thinker/blob/master/docs/esp32cam-pin-notes.md
.. code-block:: yaml
# Example configuration entry
@ -251,6 +258,25 @@ Configuration for M5Stack Timer Camera X/F
name: My Camera
# ...
Confguration for M5Stack M5CameraF New
--------------------------------------
.. code-block:: yaml
# Example configuration entry as per https://docs.m5stack.com/en/unit/m5camera_f_new
esp32_camera:
external_clock:
pin: GPIO27
frequency: 20MHz
i2c_pins:
sda: GPIO22
scl: GPIO23
data_pins: [GPIO32, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
vsync_pin: GPIO25
href_pin: GPIO26
pixel_clock_pin: GPIO21
reset_pin: GPIO15
Configuration for Wrover Kit Boards
-----------------------------------
@ -436,6 +462,33 @@ Configuration for ESP-EYE
name: My Camera
# ...
Configuration for ESP32S3_EYE on `Freenove ESP32-S3-DevKitC-1 <https://github.com/Freenove/Freenove_ESP32_S3_WROOM_Board>`_
---------------------------------------------------------------------------------------------------------------------------
.. code-block:: yaml
# Example configuration entry
external_components:
- source:
type: git
url: https://github.com/MichaKersloot/esphome_custom_components
components: [ esp32_camera ]
esp32_camera:
external_clock:
pin: GPIO15
frequency: 20MHz
i2c_pins:
sda: GPIO4
scl: GPIO5
data_pins: [GPIO11, GPIO9, GPIO8, GPIO10, GPIO12, GPIO18, GPIO17, GPIO16]
vsync_pin: GPIO6
href_pin: GPIO7
pixel_clock_pin: GPIO13
# Image settings
name: My Camera
# ...
See Also
--------

9
components/esp32_improv.rst
View File

@ -6,10 +6,17 @@ Improv via BLE
:image: improv-social.png
The ``esp32_improv`` component in ESPHome implements the open `Improv standard <https://www.improv-wifi.com/>`__
for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy to receive the credentials.
for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy (BLE) to receive the credentials.
The ``esp32_improv`` component will automatically set up the :doc:`BLE Server <esp32_ble>`.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml

3
components/esphome.rst
View File

@ -15,6 +15,7 @@ where you specify the **name** of the node.
esphome:
name: livingroom
comment: Living room ESP32 controller
area: Living Room
esp32:
board: nodemcu-32s
@ -32,6 +33,8 @@ Configuration variables:
- **friendly_name** (*Optional*, string): This is the name sent to the frontend. It is used
by Home Assistant as the integration name, device name, and is automatically prefixed to entities
where necessary.
- **area** (*Optional*, string): This is the area sent to the frontend. It is used
by Home Assistant as the area / zone which the node belongs to.
Advanced options:

10
components/ethernet.rst
View File

@ -222,7 +222,17 @@ Configuration examples
clk_mode: GPIO17_OUT
phy_addr: 1
**LILYGO T-ETH-Lite**:
.. code-block:: yaml
ethernet:
type: RTL8201
mdc_pin: GPIO23
mdio_pin: GPIO18
clk_mode: GPIO0_IN
phy_addr: 0
power_pin: GPIO12
See Also
--------

62
components/external_components.rst
View File

@ -8,6 +8,8 @@ External Components
You can easily import community or personal components using the external components feature.
Bundled components can be overridden using this feature.
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
.. code-block:: yaml
external_components:
@ -91,15 +93,15 @@ Given the above example of ``my_components``, the folder structure must look lik
├── node2.yaml
└── my_components
├── my_component1
  │   ├── __init__.py
  │   ├── component1.cpp
  │   ├── component1.h
  │   └── sensor.py
  └── my_component2
     ├── __init__.py
     ├── component2.cpp
     ├── component2.h
     └── switch.py
│ ├── __init__.py
│ ├── component1.cpp
│ ├── component1.h
│ └── sensor.py
└── my_component2
├── __init__.py
├── component2.cpp
├── component2.h
└── switch.py
.. _external-components_git:
@ -119,16 +121,16 @@ For repositories where you share one or a few components:
.. code-block:: text
components
  ├── my_component1
  │   ├── __init__.py
  │   ├── component1.cpp
  │   ├── component1.h
  │   └── sensor.py
  └── my_component2
     ├── __init__.py
     ├── component2.cpp
     ├── component2.h
     └── switch.py
├── my_component1
│ ├── __init__.py
│ ├── component1.cpp
│ ├── component1.h
│ └── sensor.py
└── my_component2
├── __init__.py
├── component2.cpp
├── component2.h
└── switch.py
example_component1.yaml <- not required but recommended
README.md
@ -140,17 +142,17 @@ repository:
esphome
├── components
│   ├── my_component1
│   │   ├── __init__.py
│   │   ├── component1.cpp
│   │   ├── component1.h
│   │   └── sensor.py
│   ├── my_component2
│   │   ├── __init__.py
│   │   ├── component2.cpp
│   │   ├── component2.h
│   │   └── switch.py
│  ...
│ ├── my_component1
│ │ ├── __init__.py
│ │ ├── component1.cpp
│ │ ├── component1.h
│ │ └── sensor.py
│ ├── my_component2
│ │ ├── __init__.py
│ │ ├── component2.cpp
│ │ ├── component2.h
│ │ └── switch.py
│ ...
...
HTTP git repositories in general are supported with this configuration:

3
components/fan/hbridge.rst
View File

@ -38,7 +38,7 @@ The ``hbridge`` fan platform allows you to use a compatible *h-bridge* (L298N, D
pin_a: motor_forward_pin
pin_b: motor_reverse_pin
# enable_pin: motor_enable
decay_mode: slow # slow decay mode (braking) or fast decay (coasting).
decay_mode: slow # slow decay mode (coasting) or fast decay (braking).
Configuration variables:
------------------------
@ -56,6 +56,7 @@ Configuration variables:
will allow 1% increments in the output. Defaults to ``100``.
- **name** (**Required**, string): The name for this fan.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`).
- All other options from :ref:`Fan Component <config-fan>`.
.. _fan-hbridge_brake_action:

35
components/fan/index.rst
View File

@ -79,6 +79,8 @@ Automation triggers:
when the fan is turned off. See :ref:`fan-on_turn_on_off_trigger`.
- **on_speed_set** (*Optional*, :ref:`Action <config-action>`): An automation to perform
when the fan speed is set/changed. See :ref:`fan-on_speed_set_trigger`.
- **on_preset_set** (*Optional*, :ref:`Action <config-action>`): An automation to perform
when the fan preset mode is set/changed. See :ref:`fan-on_preset_set_trigger`.
.. _fan-toggle_action:
@ -147,7 +149,7 @@ Increments through speed levels of the fan with the given ID when executed. If t
id: fan_1
off_speed_cycle: true
# Shorthand:
- fan.cycle_speed:: fan_1
- fan.cycle_speed: fan_1
Configuration options:
@ -206,6 +208,21 @@ This trigger is activated each time the fan speed is changed. It will fire when
on_speed_set:
- logger.log: "Fan Speed was changed!"
.. _fan-on_preset_set_trigger:
``fan.on_preset_set`` Trigger
-----------------------------
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.
.. code-block:: yaml
fan:
- platform: speed # or any other platform
# ...
on_preset_set:
- logger.log: "Fan preset mode was changed!"
Lambda calls
------------
@ -256,6 +273,17 @@ advanced stuff (see the full API Reference for more info).
// Fan direction is reverse, do something else here
}
- ``preset_mode``: Retrieve the current preset mode of the fan.
.. code-block:: yaml
// Within lambda, get the fan preset mode and conditionally do something
if (id(my_fan).preset_mode == "auto") {
// Fan preset mode is "auto", do something here
} else {
// Fan preset mode is not "auto", do something else here
}
- ``turn_off()``/``turn_on()``/``toggle()``: Manually turn the fan ON/OFF from code.
Similar to the ``fan.turn_on``, ``fan.turn_off``, and ``fan.toggle`` actions,
but can be used in complex lambda expressions.
@ -273,6 +301,11 @@ advanced stuff (see the full API Reference for more info).
call.set_direction(FanDirection::REVERSE);
call.perform();
// Set a preset mode
auto call = id(my_fan).turn_on();
call.set_preset_mode("auto");
call.perform();
// Toggle the fan on/off
auto call = id(my_fan).toggle();
call.perform();

1
components/fan/speed.rst
View File

@ -34,6 +34,7 @@ Configuration variables:
to calculate the percentages for each speed. E.g. ``2`` means that you have 50% and 100% while ``100``
will allow 1% increments in the output. Defaults to ``100``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`).
- All other options from :ref:`Fan Component <config-fan>`.
See Also

BIN
components/images/dfrobot_sen0395-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
components/images/emc2101-full.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 540 KiB

BIN
components/images/micronova_optocouplers.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
components/images/micronova_serial.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 730 KiB

BIN
components/images/micronova_serial_layout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 KiB

BIN
components/images/pylontech.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
components/images/rj45_pinout.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

1
components/index.rst
View File

@ -27,4 +27,5 @@ Components
speaker/index
time/index
alarm_control_panel/index
text/index
*

6
components/libretiny.rst
View File

@ -6,7 +6,7 @@ LibreTiny Platform
:image: libretiny.svg
This component contains platform-specific options for the `LibreTiny <https://docs.libretiny.eu/>`__ platform.
It provides support for the following microcontrollers:
It provides support for the following microcontrollers, commonly used in Tuya devices, amongst others:
- **BK72xx**: BK7231T, BK7231N
- **RTL87xx**: RTL8710BN, RTL8710BX
@ -49,7 +49,7 @@ Configuration variables:
- :ref:`Advanced options <advanced-options>`
- **family** (*Optional*, boolean): The family of LibreTiny-supported microcontrollers that is used on this board.
- **family** (*Optional*, string): The family of LibreTiny-supported microcontrollers that is used on this board.
One of ``bk7231n``, ``bk7231t``, ``rtl8710b``, ``rtl8720c``, ``bk7251``, ``bk7231q``.
Defaults to the variant that is detected from the board, if a board that's unknown to ESPHome is used,
this option is mandatory. **It's recommended not to include this option**.
@ -58,8 +58,6 @@ Configuration variables:
Support for the LibreTiny platform is still in development and there could be issues or missing components.
In particular, **MQTT is not supported yet**, because of reported stability issues.
Please report any issues on `LibreTiny GitHub <https://github.com/kuba2k2/libretiny>`__.
Getting Started

10
components/light/custom.rst
View File

@ -1,6 +1,16 @@
Custom Light Output
===================
.. warning::
Custom components are deprecated, not recommended for new configurations
and will be removed from ESPHome in a future release.
Please look at creating a real ESPHome component and "importing" it into your
configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom lights in ESPHome
using the C++ (Arduino) API.

12
components/light/index.rst
View File

@ -492,11 +492,21 @@ This effect makes a pulsating light. The period can be defined by ``update_inter
name: "Slow Pulse"
# transition_length: 1s # defaults to 1s
update_interval: 2s
- pulse:
name: "Asymmetrical Pulse"
transition_length:
on_length: 1s
off_length: 500ms
update_interval: 1.5s
Configuration variables:
- **name** (*Optional*, string): The name of the effect. Defaults to ``Pulse``.
- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``1s``.
- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition.
Defaults to ``1s``. Can be a single time or split for on and off using these nested options.
- **on_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned on.
- **off_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned off.
- **update_interval** (*Optional*, :ref:`config-time`): The interval when the new transition is started. Defaults to ``1s``.
- **min_brightness** (*Optional*, percentage): The minimum brightness value. Defaults to ``0%``
- **max_brightness** (*Optional*, percentage): The maximum brightness value. Defaults to ``100%``

4
components/light/spi_led_strip.rst
View File

@ -8,8 +8,8 @@ SPI LED Strip Light
The ``spi_led_strip`` light platform drives one or more SPI interfaced RGB LEDs. These LEDs are often used in strips, where
each LED is individually addressable. This component requires an SPI interface to be configured.
This component has been tested with APA102 LEDs and should also work with HD107 and SK9822 type LEDs, or any others
with a similar interface - SPI, 8 bits per colour and BGR ordering.
This component has been tested with APA102 LEDs and the P9813 LED driver. It should also work with HD107 and SK9822 type
LEDs, or any others with a similar interface - SPI, 8 bits per colour and BGR ordering.
.. figure:: images/apa102.jpg
:align: center

110
components/logger.rst
View File

@ -35,8 +35,8 @@ Advanced settings:
- **tx_buffer_size** (*Optional*, int): The size of the buffer used
for log messages. Decrease this if you’re having memory problems.
Defaults to ``512``.
- **hardware_uart** (*Optional*, string): The Hardware UART to use for logging.
Defaults to ``UART0``.
- **hardware_uart** (*Optional*, string): The Hardware UART to use for logging. The default varies depending on
the specific processor/chip and framework you are using. See the :ref:`table below <logger-default_hardware_interfaces>`.
- **esp8266_store_log_strings_in_flash** (*Optional*, boolean): If set to false, disables storing
log strings in the flash section of the device (uses more memory). Defaults to true.
- **on_message** (*Optional*, :ref:`Automation <automation>`): An action to be
@ -52,23 +52,99 @@ Advanced settings:
Hardware UARTs
--------------
The logger component makes use of platform-specific hardware UARTs for serial logging.
By default, the logger will occupy ``UART0``. The ESP32 has three hardware UARTs, all of
which can be used for both transmit and receive. The ESP8266 only has two hardware UARTs,
one of which is transmit-only. The ESP8266 ``UART0`` can also be 'swapped' to TX/RX on the
CTS/RTS pins, if you need to use GPIO1 and GPIO3 for something else. Note that the common
NodeMCU boards have their USB-UART Adapters fixed to the default GPIOs used by ``UART0``,
so if you use anything else you will not get log messages over the on-board USB.
The logger component makes use of platform-specific hardware UARTs for serial logging. For example, the ESP32
has three hardware UARTs, all of which can be used for both transmit and receive. The ESP8266 only has two
hardware UARTs, one of which is transmit-only. The ESP8266's ``UART0`` can also be "swapped" to TX/RX on the
CTS/RTS pins in the event that you need to use GPIO1 and GPIO3 for something else.
Possible Hardware UART configurations:
Note that many common boards have their USB-to-serial adapters fixed to the default GPIOs used by ``UART0``,
so if you use any other configuration you will not get log messages over the on-board USB.
- ``UART0`` - TX: GPIO1, RX: GPIO3
- ``UART0_SWAP`` - TX: GPIO15, RX: GPIO13 (Only on ESP8266)
- ``UART1`` - TX: GPIO2, RX: None (Only on ESP8266)
- ``UART1`` - TX: GPIO9, RX: GPIO10 (Only on ESP32)
- ``UART2`` - TX: GPIO16, RX: GPIO17 (Only on ESP32 but not ESP32S2, ESP32S3 or ESP32C3)
- ``USB_CDC`` - uses the USB CDC driver (Only on ESP32S2 and ESP32S3)
- ``USB_SERIAL_JTAG`` - uses the USB Serial/JTAG driver (Only on ESP32S3 and ESP32C3)
Default UART GPIO Pins
**********************
.. list-table::
:header-rows: 1
* -
- ``UART0``
- ``UART0_SWAP``
- ``UART1``
- ``UART2``
- ``USB_CDC``
- ``USB_SERIAL_JTAG``
* - ESP8266
- TX: 1, RX: 3
- TX: 15, RX: 13
- TX: 2, RX: N/A
- N/A
- N/A
- N/A
* - ESP32
- TX: 1, RX: 3
- N/A
- TX: 9, RX: 10
- TX: 16, RX: 17
- N/A
- N/A
* - ESP32-C3
- TX: 21, RX: 20
- N/A
- Undefined
- N/A
- N/A
- 18/19
* - ESP32-S2
- TX: 43, RX: 44
- N/A
- TX: 17, RX: 18
- N/A
- 19/20
- N/A
* - ESP32-S3
- TX: 43, RX: 44
- N/A
- TX: 17, RX: 18
- Undefined
- 19/20
- 19/20
*Undefined* means that the logger component cannot use this harware UART at this time.
.. _logger-default_hardware_interfaces:
Default Hardware Interfaces
---------------------------
Because of the wide variety of boards and processors/chips available, we've selected varying default
hardware interfaces for logging. Many newer boards based on ESP32 variants (such as the C3, S2 and S3)
are using the ESP's on-board USB hardware peripheral while boards based on older processors (such as
the original ESP32 or ESP8266) continue to use USB-to-serial bridge ICs for communication.
.. list-table::
:header-rows: 1
* -
- Arduino
- ESP-IDF
* - ESP8266
- ``UART0``
- N/A
* - ESP32
- ``UART0``
- ``UART0``
* - ESP32-C3
- ``USB_CDC``
- ``USB_SERIAL_JTAG``
* - ESP32-S2
- ``USB_CDC``
- ``USB_CDC``
* - ESP32-S3
- ``USB_CDC``
- ``USB_SERIAL_JTAG``
* - RP2040
- ``USB_CDC``
- N/A
.. _logger-log_levels:

4
components/mcp23Sxx.rst
View File

@ -2,11 +2,11 @@ MCP23Sxx I/O Expander
=====================
.. seo::
:description: Instructions for setting up MCP23S08, MCP23S16 or MCP23S17 digital port expander in ESPHome. This is exactly the same API as the MCP230XX I/O Expander except talks on the SPI bus
:description: Instructions for setting up MCP23S08, MCP23S16 or MCP23S17 digital port expander in ESPHome. This series features exactly the same API as the MCP230xx I/O Expander (I²C)
:image: mcp230xx.svg
The Microchip MCP23Sxx series of general purpose, parallel I/O expansion for SPI bus applications.
This is exactly the same API as the MCP23SXX I/O Expander except talks on the SPI bus
This series features exactly the same API as the MCP230xx I/O Expander (I²C).
**Supported Variants :**

227
components/micronova.rst Normal file
View File

@ -0,0 +1,227 @@
MicroNova based pellet stove
============================
.. seo::
:description: Instructions for setting up a MicroNova board based pellet stove in ESPHome.
The MicroNova component allows you to integrate a pellet stove with a MicroNova board in ESPHome.
It uses :ref:`UART <uart>` for communication.
The :ref:`UART <uart>` must be configured with a baud rate 1200, 8 data bits, 2 stop bits, no parity, no flow control.
.. warning::
MicroNova bords come in various flavours. This code is only tested on an ExtraFlame Ketty Evo 2.0 stove. The protocol is not
documented but has been reverse engineerd by others. See the links below for all the info that helped me.
The different sensors, buttons and stove switch may require specific **memory_location** and **memory_address** parameters that
match your MicroNova specific board.
Also, switching your stove on or off can behave different on the various MicroNova flavours.
Use this integration at your own risk.
Connecting your stove
---------------------
Most MicroNova based pellet stoves have a serial output. In most cases this output has 4 pins: GND, 5v, 20V and DATA.
.. figure:: images/micronova_serial.png
:align: center
:width: 50.0%
.. figure:: images/micronova_serial_layout.png
:align: center
:width: 50.0%
You will have to build a simple circuit to interface with your stove. It is based on optocouplers for galvanic separation and logic
level shifting between 5v and 3V3.
.. figure:: images/micronova_optocouplers.png
:align: center
:width: 100.0%
Optocoupler interface circuit (credit: philibertc)
See the references below for all the details about te circuit.
You can use the 5V output from the stove to power the ESP module, but you will have to put a voltage regulator in between to
get 3v3.
Component/Hub
-------------
.. code-block:: yaml
micronova:
enable_rx_pin: REPLACEME
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **enable_rx_pin** (**Required**, :ref:`config-pin`): Output pin to be used to switch the line between RX and TX.
- **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked.
Defaults to 60 seconds.
.. note::
For all text sensors, sensors, numbers, buttons and switches hereafter most of the the default **memory_location** and **memory_address** parameters will work so you should
not specify them. However your Micronova boad may require you to specify alternate values. So every text sensor, button,
switch or number accepts these parameters:
- **memory_location** (*Optional*): The memory location where the parameter must be read. For most stoves this is 0x00 for RAM
or 0x20 for EPROM.
- **memory_address** (*Optional*): The address where the parameter is stored.
Text Sensors
------------
.. code-block:: yaml
text_sensor:
- platform: micronova
stove_state:
name: Stove status
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **stove_state** (*Optional*): The current stove state.
All options from :ref:`Text Sensor <config-text_sensor>`.
Sensors
-------
.. code-block:: yaml
sensor:
- platform: micronova
room_temperature:
name: Room temperature
fumes_temperature:
name: Fumes temperature
stove_power:
name: Stove power level
fan_speed:
fan_rpm_offset: 240
name: Fan RPM
water_temperature:
name: Water temperature
water_pressure:
name: Water pressure
memory_address_sensor:
memory_location: 0x20
memory_address: 0x7d
name: Custom Address sensor
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **room_temperature** (*Optional*): Sensor that reads the stoves ambient room temperature.
All options from :ref:`Sensor <config-sensor>`.
- **fumes_temperature** (*Optional*): Fumes temperature.
All options from :ref:`Sensor <config-sensor>`.
- **stove_power** (*Optional*): Current stove power.
All options from :ref:`Sensor <config-sensor>`.
- **fan_speed** (*Optional*): Current fan speed. The raw value from the stove is multiplied by 10 + ``fan_rpm_offset``.
- **fan_rpm_offset** (*Optional*, integer): Offset the reported RPM value. Must be between 0 and 255. Defaults to 0.
- All other options from :ref:`Sensor <config-sensor>`.
- **water_temperature** (*Optional*): Internal boiler water termperature.
All options from :ref:`Sensor <config-sensor>`.
- **water_pressure** (*Optional*): Internal boiler water pressure.
All options from :ref:`Sensor <config-sensor>`.
- **memory_address_sensor** (*Optional*): Can be any **memory_location** / **memory_address** you want to track. Usefull
when you don't know where the parameter is for your stove is.
All options from :ref:`Sensor <config-sensor>`.
Numbers
-------
.. code-block:: yaml
number:
- platform: micronova
thermostat_temperature:
name: Thermostat temperature
step: 0.5
power_level:
name: Thermostat temperature
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **thermostat_temperature** (*Optional*): Number that holds the current stove thermostat value.
- **step** (*Optional*): Temperature step. This value is used to multiply/devide the raw value when setting/reading the **thermostat_temperature**
- All other options from :ref:`Number <config-number>`.
- **power_level** (*Optional*): Number that sets/reads the requested stove power.
All options from :ref:`Number <config-number>`.
.. note::
Besides **memory_location** and **memory_address** you can specify a specific **memory_write_location** parameter.
This parameter is a hex value for the **memory_location** where the new thermostat value must be written.
- **memory_write_location** (*Optional*): The **memory_location** where to write the new thermostat value.
Buttons
-------
.. code-block:: yaml
button:
- platform: micronova
custom_button:
name: Custom button
memory_location: 0x20
memory_address: 0x7d
memory_data: 0x08
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **custom_button** (*Optional*): Write the hex value **memory_data** to a **memory_location** and **memory_address**
All options from :ref:`Button <config-button>`.
.. note::
Besides **memory_location** and **memory_address** you must specify a specific **memory_data** parameter.
- **memory_data** (*Required*): The hex value to be written to the **memory_location** and **memory_address**.
Switches
--------
.. code-block:: yaml
switch:
- platform: micronova
stove:
name: Stove on/off switch
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **stove** (*Optional*): Turn the stove on or off. This switch will also reflect the current stove state.
If the **stove_state** is "Off" the switch will be off, in all other states, the switch wil be on.
All options from :ref:`Switch <config-switch>`.
.. note::
Besides **memory_location** and **memory_address** you can specify specific **memory_data_on** and **memory_data_off** parameters.
These parameters contain the hex value to be written to the **memory_location** and **memory_address** when the switch
turns on or off.
- **memory_data_on** (*Optional*): The data to write when turning the switch on.
- **memory_data_off** (*Optional*): The data to write when turning the switch off.
See Also
--------
- `ridiculouslab micronova <https://www.ridiculouslab.com/arguments/iot/stufa/micronova_en.php>`__
- `philibertc / micronova_controller <https://github.com/philibertc/micronova_controller/>`__
- `eni23 / micronova-controller <https://github.com/eni23/micronova-controller>`__
- :ghedit:`Edit`

13
components/microphone/i2s_audio.rst
View File

@ -5,8 +5,17 @@ I²S Audio Microphone
:description: Instructions for setting up I²S based microphones in ESPHome.
:image: i2s_audio.svg
The ``i2s_audio`` microphone platform allows you to receive audio via the the
:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
The ``i2s_audio`` microphone platform allows you to receive audio via the the :doc:`/components/i2s_audio`.
This platform only works on ESP32 based chips.
.. warning::
Audio and voice components consume a significant amount of resources (RAM, CPU) on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. In particular, Bluetooth/BLE components are known to cause issues when used in
combination with Voice Assistant and/or other audio components.
.. code-block:: yaml

16
components/modbus.rst
View File

@ -7,9 +7,9 @@ Modbus Component
:description: Instructions for setting up Modbus in ESPHome.
:keywords: Modbus
The Modbus protocol is used by many consumer and industrial devices for communication.
The ModBUS protocol is used by many consumer and industrial devices for communication.
This component allows components in ESPHome to communicate to those devices.
Modbus requires a :ref:`UART Bus <uart>` to communicate.
ModBUS requires a :ref:`UART Bus <uart>` to communicate.
.. code-block:: yaml
@ -23,13 +23,18 @@ Modbus requires a :ref:`UART Bus <uart>` to communicate.
Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
to use multiple UART buses.
- **flow_control_pin** (*Optional*, :ref:`config-pin`): The pin used to switch flow control.
This is useful for RS485 transceivers that do not have automatic flow control switching,
like the common MAX485.
- **send_wait_time** (*Optional*, :ref:`config-time`): Time in milliseconds before a new modbus command is sent if an answer from a previous command is pending. Defaults to 250 ms.
If multiple modbus devices are attached increasing this value can help avoiding to to overlapping reads.
When 2 devices are sending a command at the same the response read from uart can't be assigned to the proper design.
- **send_wait_time** (*Optional*, :ref:`config-time`): Time in milliseconds before the next ModBUS command is sent if an answer from a previous command is pending. Defaults to 250 ms.
If multiple ModBUS devices are attached to the same bus increasing this value can help avoiding to to overlapping reads.
When two devices are sending a command at the same time the response read from UART can't be assigned to the proper design.
This value defines the maximum queuing time for a command before it is send anyways.
- **disable_crc** (*Optional*, boolean): Ignores a bad CRC if set to ``true``. Defaults to ``false``
@ -44,7 +49,6 @@ See Also
- :doc:`/components/switch/modbus_controller`
- :doc:`/components/number/modbus_controller`
- :doc:`/components/output/modbus_controller`
- `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) <https://devices.esphome.io/devices/epever_mptt_tracer_an>`__
- `Modbus RTU Protocol Description <https://www.modbustools.com/modbus.html>`__
- :ref:`uart`
- :apiref:`modbus/modbus.h`

326
components/modbus_controller.rst
View File

@ -2,28 +2,31 @@ Modbus Controller
=================
.. seo::
:description: Instructions for setting up the Modbus Controller component.
:description: Instructions for setting up the ModBUS Controller component.
:image: modbus.png
The ``modbus_controller`` component creates a RS485 connection to control a modbus device
The ``modbus_controller`` component creates a RS485 connection to control a ModBUS slave device, letting your ESPHome node to act as a ModBUS master.
You can access the coils and registers from your slave ModBUS device as sensors, switches or various other ESPHome components and present them to your favorite Home Automation system.
.. figure:: /images/modbus.png
:align: center
:width: 25%
The ``modbus_controller`` component uses the modbus component
The ``modbus_controller`` component relies on the :doc:`/components/modbus`.
Hardware setup
--------------
A RS 485 module connected to an ESP32, for example:
You need an RS485 transceiver module:
.. figure:: /images/rs485.jpg
See `How is this RS485 Module Working? <https://electronics.stackexchange.com/questions/244425/how-is-this-rs485-module-working>`__ on stackexchange for more details
See `How is this RS485 module working? <https://electronics.stackexchange.com/questions/244425/how-is-this-rs485-module-working>`__ on stackexchange for more details.
The controller connects to the UART of the MCU. For ESP32 GPIO PIN 16 to TXD PIN 17 to RXD are the default ports but any other pins can be used as well. 3.3V to VCC and GND to GND.
The transceiver connects to the UART of the MCU. For ESP32, pin ``16`` to ``TXD`` and pin ``17`` to ``RXD`` are the default ones but any other pins can be used as well. ``3.3V`` to ``VCC`` and naturally ``GND`` to ``GND``.
On the bus side, you need 120 Ohm termination resistors at the ends of the bus cable as per ModBUS standard. Some transceivers have this already solderes onboard, and some slave devices may have them preinstalled with a jumper or a dip switch.
.. note::
@ -31,7 +34,7 @@ The controller connects to the UART of the MCU. For ESP32 GPIO PIN 16 to TXD PI
For hardware serial only a limited set of pins can be used. Either ``tx_pin: GPIO1`` and ``rx_pin: GPIO3`` or ``tx_pin: GPIO15`` and ``rx_pin: GPIO13``.
The disadvantage of using the hardware uart is that you can't use serial logging because the serial logs would be sent to the modbus device and cause errors.
The disadvantage of using the hardware uart is that you can't use serial logging because the serial logs would be sent to the ModBUS device and cause errors.
Serial logging can be disabled by setting ``baud_rate: 0``.
@ -48,29 +51,27 @@ The controller connects to the UART of the MCU. For ESP32 GPIO PIN 16 to TXD PI
Configuration variables:
------------------------
- **modbus_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the modbus hub.
- **modbus_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the ``modbus`` hub.
- **address** (**Required**, :ref:`config-id`): The modbus address of the device
Specify the modbus device address of the.
- **address** (**Required**, :ref:`config-id`): The ModBUS address of the slave device
- **command_throttle** (*Optional*, :ref:`config-time`): minimum time in between 2 requests to the device. Default is 0ms
Because some modbus devices limit the rate of requests the interval between sending requests to the device can be modified.
- **command_throttle** (*Optional*, :ref:`config-time`): minimum time in between 2 requests to the device. Default is ``0ms``.
Some ModBUS slave devices limit the rate of requests from the master, the interval between sending requests can be altered.
- **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked.
Defaults to 60 seconds.
- **offline_skip_updates** (*Optional*, integer): When a controller doesn't respond to a command, it is
- **offline_skip_updates** (*Optional*, integer): When a slave doesn't respond to a command, it is
marked as offline, you can specify how many updates will be skipped while it is offline. If using a bus with multiple
controllers, this avoids waiting for timeouts allowing to read other controllers in the same bus. When the controller
slaves, this avoids waiting for timeouts allowing to read other slaves in the same bus. When the slave
responds to a command, it'll be marked online again.
Example
-------
The following code create a modbus_controller hub talking to a modbus device at address 1 with 115200 bps
The following code creates a ``modbus_controller`` hub talking to a ModBUS device at address ``1`` with ``115200`` bps
Modbus sensors can be directly defined (inline) under the modbus_controller hub or as standalone components
ModBUS sensors can be directly defined (inline) under the ``modbus_controller`` hub or as standalone components
Technically there is no difference between the "inline" and the standard definitions approach.
.. code-block:: yaml
@ -88,8 +89,7 @@ Technically there is no difference between the "inline" and the standard definit
modbus_controller:
- id: epever
## the Modbus device addr
address: 0x1
address: 0x1 ## address of the ModBUS slave device on the bus
modbus_id: modbus1
setup_priority: -10
@ -100,7 +100,7 @@ Technically there is no difference between the "inline" and the standard definit
id: rtc_clock
internal: true
register_type: holding
address: 0x9013
address: 0x9013 ## address of the register inside the ModBUS slave device
register_count: 3
raw_encode: HEXBYTES
response_size: 6
@ -208,7 +208,6 @@ To gather some of these bits as binary sensors in ESPHome, use ``bitmask``:
Protocol decoding example
-------------------------
@ -298,9 +297,8 @@ Protocol decoding example
accuracy_decimals: 0
To minimize the required transactions all registers with the same base address are read in one request.
The response is mapped to the sensor based on register_count and offset in bytes.
The response is mapped to the sensor based on ``register_count`` and offset in bytes. For example:
**Request**
@ -331,7 +329,7 @@ The response is mapped to the sensor based on register_count and offset in bytes
+--------+------------+--------------------+--------------------------------------------+
| offset | data | value (type) | description |
+========+============+====================+============================================+
| H | 0x1 (01) | | device address |
| H | 0x1 (01) | | device address |
+--------+------------+--------------------+--------------------------------------------+
| H | 0x4 (04) | | function code |
+--------+------------+--------------------+--------------------------------------------+
@ -379,161 +377,157 @@ The response is mapped to the sensor based on register_count and offset in bytes
+--------+------------+--------------------+--------------------------------------------+
.. note::
Note
----
Write support is only implemented for switches and selects.
However the C++ code provides the required API to write to a ModBUS device.
Write support is only implemented for switches and selects.
However the C++ code provides the required API to write to a modbus device.
These methods can be called from a lambda.
Here is an example how to set config values to for an EPEVER Trace AN controller.
The code synchronizes the localtime of MCU to the epever controller
The time is set by writing 12 bytes to register 0x9013.
Then battery charge settings are sent.
.. code-block:: yaml
esphome:
on_boot:
## configure controller settings at setup
## make sure priority is lower than setup_priority of modbus_controller
priority: -100
then:
- lambda: |-
// get local time and sync to controller
time_t now = ::time(nullptr);
struct tm *time_info = ::localtime(&now);
int seconds = time_info->tm_sec;
int minutes = time_info->tm_min;
int hour = time_info->tm_hour;
int day = time_info->tm_mday;
int month = time_info->tm_mon + 1;
int year = time_info->tm_year % 100;
esphome::modbus_controller::ModbusController *controller = id(epever);
// if there is no internet connection localtime returns year 70
if (year != 70) {
// create the payload
std::vector<uint16_t> rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour),
uint16_t((year << 8) | month)};
// Create a modbus command item with the time information as the payload
esphome::modbus_controller::ModbusCommandItem set_rtc_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9013, 3, rtc_data);
// Submit the command to the send queue
epever->queue_command(set_rtc_command);
ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month,
year + 2000);
}
// Battery settings
// Note: these values are examples only and apply my AGM Battery
std::vector<uint16_t> battery_settings1 = {
0, // 9000 Battery Type 0 = User
0x0073, // 9001 Battery Cap 0x55 == 115AH
0x012C, // 9002 Temp compensation -3V /°C/2V
0x05DC, // 9003 0x5DC == 1500 Over Voltage Disconnect Voltage 15,0
0x058C, // 9004 0x58C == 1480 Charging Limit Voltage 14,8
0x058C, // 9005 Over Voltage Reconnect Voltage 14,8
0x05BF, // 9006 Equalize Charging Voltage 14,6
0x05BE, // 9007 Boost Charging Voltage 14,7
0x0550, // 9008 Float Charging Voltage 13,6
0x0528, // 9009 Boost Reconnect Charging Voltage 13,2
0x04C4, // 900A Low Voltage Reconnect Voltage 12,2
0x04B0, // 900B Under Voltage Warning Reconnect Voltage 12,0
0x04BA, // 900c Under Volt. Warning Volt 12,1
0x04BA, // 900d Low Volt. Disconnect Volt. 11.8
0x04BA // 900E Discharging Limit Voltage 11.8
};
// Boost and equalization periods
std::vector<uint16_t> battery_settings2 = {
0x0000, // 906B Equalize Duration (min.) 0
0x0075 // 906C Boost Duration (aka absorb) 117 mins
};
esphome::modbus_controller::ModbusCommandItem set_battery1_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() ,
battery_settings1);
esphome::modbus_controller::ModbusCommandItem set_battery2_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(),
battery_settings2);
delay(200) ;
controller->queue_command(set_battery1_command);
delay(200) ;
controller->queue_command(set_battery2_command);
ESP_LOGI("ModbusLambda", "EPSOLAR Battery set");
uart:
id: mod_bus
tx_pin: 19
rx_pin: 18
baud_rate: 115200
stop_bits: 1
modbus:
#flow_control_pin: 23
send_wait_time: 200ms
id: mod_bus_epever
modbus_controller:
- id: epever
## the Modbus device addr
address: 0x1
modbus_id: mod_bus_epever
command_throttle: 0ms
setup_priority: -10
update_interval: ${updates}
sensor:
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_voltage
name: "array_rated_voltage"
address: 0x3000
unit_of_measurement: "V"
register_type: read
value_type: U_WORD
accuracy_decimals: 1
filters:
- multiply: 0.01
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_current
name: "array_rated_current"
address: 0x3001
unit_of_measurement: "A"
register_type: read
value_type: U_WORD
accuracy_decimals: 2
filters:
- multiply: 0.01
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_power
name: "array_rated_power"
address: 0x3002
unit_of_measurement: "W"
register_type: read
value_type: U_DWORD_R
accuracy_decimals: 1
filters:
- multiply: 0.01
These methods can be called from a lambda.
Here is an example how to set config values to for an EPEVER Trace AN controller.
The code synchronizes the localtime of MCU to the epever controller
The time is set by writing 12 bytes to register 0x9013.
Then battery charge settings are sent.
.. code-block:: yaml
esphome:
on_boot:
## configure controller settings at setup
## make sure priority is lower than setup_priority of modbus_controller
priority: -100
then:
- lambda: |-
// get local time and sync to controller
time_t now = ::time(nullptr);
struct tm *time_info = ::localtime(&now);
int seconds = time_info->tm_sec;
int minutes = time_info->tm_min;
int hour = time_info->tm_hour;
int day = time_info->tm_mday;
int month = time_info->tm_mon + 1;
int year = time_info->tm_year % 100;
esphome::modbus_controller::ModbusController *controller = id(epever);
// if there is no internet connection localtime returns year 70
if (year != 70) {
// create the payload
std::vector<uint16_t> rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour),
uint16_t((year << 8) | month)};
// Create a ModBUS command item with the time information as the payload
esphome::modbus_controller::ModbusCommandItem set_rtc_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9013, 3, rtc_data);
// Submit the command to the send queue
epever->queue_command(set_rtc_command);
ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month,
year + 2000);
}
// Battery settings
// Note: these values are examples only and apply my AGM Battery
std::vector<uint16_t> battery_settings1 = {
0, // 9000 Battery Type 0 = User
0x0073, // 9001 Battery Cap 0x55 == 115AH
0x012C, // 9002 Temp compensation -3V /°C/2V
0x05DC, // 9003 0x5DC == 1500 Over Voltage Disconnect Voltage 15,0
0x058C, // 9004 0x58C == 1480 Charging Limit Voltage 14,8
0x058C, // 9005 Over Voltage Reconnect Voltage 14,8
0x05BF, // 9006 Equalize Charging Voltage 14,6
0x05BE, // 9007 Boost Charging Voltage 14,7
0x0550, // 9008 Float Charging Voltage 13,6
0x0528, // 9009 Boost Reconnect Charging Voltage 13,2
0x04C4, // 900A Low Voltage Reconnect Voltage 12,2
0x04B0, // 900B Under Voltage Warning Reconnect Voltage 12,0
0x04BA, // 900c Under Volt. Warning Volt 12,1
0x04BA, // 900d Low Volt. Disconnect Volt. 11.8
0x04BA // 900E Discharging Limit Voltage 11.8
};
// Boost and equalization periods
std::vector<uint16_t> battery_settings2 = {
0x0000, // 906B Equalize Duration (min.) 0
0x0075 // 906C Boost Duration (aka absorb) 117 mins
};
esphome::modbus_controller::ModbusCommandItem set_battery1_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() ,
battery_settings1);
esphome::modbus_controller::ModbusCommandItem set_battery2_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(),
battery_settings2);
delay(200) ;
controller->queue_command(set_battery1_command);
delay(200) ;
controller->queue_command(set_battery2_command);
ESP_LOGI("ModbusLambda", "EPSOLAR Battery set");
uart:
id: mod_bus
tx_pin: 19
rx_pin: 18
baud_rate: 115200
stop_bits: 1
modbus:
#flow_control_pin: 23
send_wait_time: 200ms
id: mod_bus_epever
modbus_controller:
- id: epever
## the Modbus device addr
address: 0x1
modbus_id: mod_bus_epever
command_throttle: 0ms
setup_priority: -10
update_interval: ${updates}
sensor:
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_voltage
name: "array_rated_voltage"
address: 0x3000
unit_of_measurement: "V"
register_type: read
value_type: U_WORD
accuracy_decimals: 1
filters:
- multiply: 0.01
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_current
name: "array_rated_current"
address: 0x3001
unit_of_measurement: "A"
register_type: read
value_type: U_WORD
accuracy_decimals: 2
filters:
- multiply: 0.01
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_power
name: "array_rated_power"
address: 0x3002
unit_of_measurement: "W"
register_type: read
value_type: U_DWORD_R
accuracy_decimals: 1
filters:
- multiply: 0.01
See Also
--------
- :doc:`/components/sensor/modbus_controller`
- :doc:`/components/modbus`
- :doc:`/components/binary_sensor/modbus_controller`
- :doc:`/components/text_sensor/modbus_controller`
- :doc:`/components/switch/modbus_controller`
- :doc:`/components/number/modbus_controller`
- :doc:`/components/output/modbus_controller`
- `ModBUS RTU Protocol Description <https://www.modbustools.com/modbus.html>`__
- `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) <https://devices.esphome.io/devices/epever_mptt_tracer_an>`__
- `Modbus RTU Protocol Description <https://www.modbustools.com/modbus.html>`__
- `Genvex, Nibe, Alpha-Innotec heat recovery ventilation <https://devices.esphome.io/devices/Genvex-Nibe-AlphaInnotec-heat-recovery-ventilation>`__
- :ghedit:`Edit`

13
components/mqtt.rst
View File

@ -60,8 +60,9 @@ Configuration variables:
`Abbreviations <https://www.home-assistant.io/docs/mqtt/discovery/>`__
in discovery messages. Defaults to ``true``.
- **topic_prefix** (*Optional*, string): The prefix used for all MQTT
messages. Should not contain trailing slash. Defaults to
``<APP_NAME>``.
messages. Should not contain trailing slash. Defaults to ``<APP_NAME>``.
Use ``null`` to disable publishing or subscribing of any MQTT topic unless
it is explicitly configured.
- **log_topic** (*Optional*, :ref:`mqtt-message`): The topic to send MQTT log
messages to. Use ``null`` if you want to disable sending logs to MQTT.
@ -373,9 +374,17 @@ Configuration variables:
- **state_topic** (*Optional*, string): The topic to publish state
updates to. Defaults to
``<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state``.
ESPHome will always publish a manually configured state topic, even if
the component is internal. Use ``null`` to disable publishing the
component's state.
- **command_topic** (*Optional*, string): The topic to subscribe to for
commands from the remote. Defaults to
``<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/command``.
ESPHome will always subscribe to a manually configured command topic,
even if the component is internal. Use ``null`` to disable subscribing
to the component's command topic.
- **command_retain** (*Optional*, boolean): Whether MQTT command messages
sent to the device should be retained or not. Default to ``false``.

15
components/output/ble_client.rst
View File

@ -5,12 +5,17 @@ BLE Client Binary Output
:description: Writes a binary value to a BLE device.
:image: bluetooth.svg
The ``ble_client`` component is a output that can
write a binary value to service characteristics of
BLE devices.
The ``ble_client`` component is a output that can write a binary value to service characteristics of BLE devices.
For more information on BLE services and characteristics, see
:doc:`/components/ble_client`.
For more information on BLE services and characteristics, see :doc:`/components/ble_client`.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml

10
components/output/custom.rst
View File

@ -1,6 +1,16 @@
Custom Output
=============
.. warning::
Custom components are deprecated, not recommended for new configurations
and will be removed from ESPHome in a future release.
Please look at creating a real ESPHome component and "importing" it into your
configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
This integration can be used to create custom binary and float :doc:`outputs </components/output/index>`
in ESPHome using the C++ (Arduino) API.

12
components/output/mcp4728.rst
View File

@ -11,6 +11,9 @@ The MCP4728 output component allows to use `12bit external quad DAC
<https://www.adafruit.com/product/4470>`__
in order to have analog outputs on any board by using :ref:`I²C <i2c>`. Devices default address is ``0x60``.
If you only have one, it is not necessary to explicitly specify the ``mcp4728:`` component in the config unless you need to change the parameters.
It will be automatically created with the default settings if you use it.
.. code-block:: yaml
# Example configuration entry
@ -23,13 +26,12 @@ in order to have analog outputs on any board by using :ref:`I²C <i2c>`. Devices
# Set the component with default (address: 0x60 / global I²C)
mcp4728:
- platform: mcp4728
id: dac_output
- id: dac_output
Configuration variables:
------------------------
- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
- **id** (*Optional*, :ref:`config-id`): The id to use for this output component.
- **address** (*Optional*, int): Manually specify the I2C address of
the DAC. Defaults to ``0x60``.
- **store_in_eeprom** (*Optional*, boolean): Use SEQ_WRITE mode to also write to EEPROM sequentially. Defaults to ``false``.
@ -57,14 +59,12 @@ The MCP4728 output component exposes 4 MCP4728 channels of a global :ref:`MCP472
power_down: gnd_1k
- platform: mcp4728
id: ac_dimmer_3
mcp4728_id: dac_output
channel: C
vref: internal
gain: X1
power_down: normal # default
- platform: mcp4728
id: ac_dimmer_4
mcp4728_id: dac_output
channel: D
vref: internal
gain: X2
@ -96,5 +96,7 @@ When ``vref=internal``, output voltage will range from 0.000V to 2.048V with ``g
See Also
--------
- :doc:`/components/output/index`
- :doc:`/components/output/esp32_dac`
- :apiref:`mcp4728/mcp4728.h`
- :ghedit:`Edit`

32
components/pca9554.rst
View File

@ -6,16 +6,21 @@ PCA9554 I/O Expander
:image: ../images/pca9554a.jpg
The PCA9554 component allows you to use **PCA9554**, **PCA9554A** or **PCA9536** I/O expanders in ESPHome.
It uses :ref:`I²C Bus <i2c>` for communication.
The PCA9554 component allows you to use a variety of Texas Instrument I/O expanders in ESPHome using the
:ref:`I²C Bus <i2c>` for communication.
Devices tested as working with this component include **PCA9554**, **PCA9554A**, **PCA9536** and **PCA9535**.
Equivalent TI I/O expanders with the same command interface and up to 16 I/O pins such as the **TCA9554**
and **TCA9535** should also work.
.. figure:: ../images/pca9554a.jpg
:align: center
PCA9554A I/O Expander chip
Once configured, you can use any of the **8** pins (PCA9554, PCA9554A) or **4** pins (PCA9536) as
pins for your projects. Within ESPHome they emulate a real internal GPIO pin
Once configured, you can use any of the **16** (PCA9535), **8** (PCA9554, PCA9554A) or **4** (PCA9536) pins
within your projects. Within ESPHome they emulate a real internal GPIO pin
and can therefore be used with many of ESPHome's components such as the GPIO
binary sensor or GPIO switch.
@ -23,19 +28,21 @@ binary sensor or GPIO switch.
The 7 bit I²C device address ranges are:
- PCA9554: ``0x20`` to ``0x27``
- PCA9554 and PCA9535: ``0x20`` to ``0x27``
- PCA9554A: ``0x38`` to ``0x3F``
- PCA9536: ``0x41``
For the PCA9554 and PCA9554A, the actual choice of the I²C device address depends on state of the 3 address pins.
For the PCA9535, PCA9554 and PCA9554A, the actual choice of the I²C device address depends on state of the 3 address pins.
Please refer to the individual datasheets linked at the bottom of the page for further details to set the address.
Up to eight PCA9554 and an additional eight PCA9554A devices can reside on the same I²C bus.
Up to eight PCA9535 or PCA9554 and an additional eight PCA9554A devices can reside on the same I²C bus.
Please note that only one PCA9536 device is allowed per I²C bus due to its fixed address.
The PCA9554 and PCA9554A provide 8 bits of GPIO's (pin numbers 0-7).
The PCA9535 provides 16 bits of GPIOs (pin numbers 0-15).
The PCA9554 and PCA9554A provide 8 bits of GPIOs (pin numbers 0-7).
The PCA9536 provides 4 bits of GPIO's (pin numbers 0-3).
The PCA9536 provides 4 bits of GPIOs (pin numbers 0-3).
Any option accepting a :ref:`Pin Schema <config-pin_schema>` can theoretically be used, but some more
complicated components that do communication through this I/O expander will not work.
@ -67,6 +74,12 @@ Configuration variables:
- **id** (**Required**, :ref:`config-id`): The id to use for this ``pca9554`` component.
- **address** (*Optional*, int): The I²C address of the driver.
Defaults to ``0x20``.
- **pin_count** (*Optional*, int): The number of bits implemented in the expander. Defaults to 8. This should be set
to 16 when using a PCA9535 and 4 when using a PCA95367.
.. note::
A PCA9535 will not work (even on the lower 8 bits) unless the **pin_count** is set to 16.
@ -88,6 +101,7 @@ See Also
- :doc:`binary_sensor/gpio`
- `PCA9554 datasheet <https://www.ti.com/lit/ds/symlink/pca9554.pdf>`__
- `PCA9554A datasheet <https://www.ti.com/lit/ds/symlink/pca9554a.pdf>`__
- `PCA9535 datasheet <https://www.ti.com/lit/ds/symlink/pca9535.pdf>`__
- `PCA9536 datasheet <https://www.ti.com/lit/ds/symlink/pca9536.pdf>`__
- :apiref:`pca9554/pca9554.h`
- :ghedit:`Edit`

4
components/power_supply.rst
View File

@ -37,6 +37,10 @@ Configuration variables:
- **keep_on_time** (*Optional*, :ref:`config-time`): The time the
power supply should be kept enabled after the last output that used
it has been switch off. Defaults to ``10s``.
- **enable_on_boot** (*Optional*, bool): If the power supply should be enabled when the power supply
component is setup. Defaults to false. The startup delay will be applied (other component setup will be blocked
until the delay has elapsed.) This is useful for power supplies that will never be turned off and avoids the need
to specifically configure the power supply in a different component.
See the :ref:`output component base configuration <config-output>`
for information on how to apply the power supply for a specific output.

197
components/pylontech.rst Normal file
View File

@ -0,0 +1,197 @@
Pylontech Battery
=================
.. seo::
:description: Instructions for setting up Pylontech Battery in ESPHome.
:image: pylontech.jpg
The Pylontech component allows you to pull data from Pylontech Batteries into ESPHome.
It uses :ref:`UART <uart>` for communication.
Once configured, you can use sensors as described below for your projects.
.. figure:: images/pylontech.jpg
:align: center
:width: 50.0%
Pylontech Batteries
Hardware Setup
--------------
You can connect to Pylontech Batteries using the port labeled "Console".
Any connections via CAN or RS485 (e.g. to an inverter) are untouched and remain functional.
The console port offers a RS232 interface using a RJ10 or RJ45 connector.
The voltage levels are *not* TTL-compatible. A RS232 transceiver must be placed between the Batteries and the ESPHome device.
MAX3232-based transceivers have been tested and work well.
If you have multiple batteries you need to connect to the master battery's console port.
.. list-table:: Pylontech RJ45 Console Port (US2000C, US3000C)
:header-rows: 1
* - RJ45 Pin
- Function
- Connect to
* - 3
- Pylontech TX
- ESPHome RX via transceiver
* - 6
- Pylontech RX
- ESPHome TX via transceiver
* - 8
- GND
- GND
.. figure:: images/rj45_pinout.jpg
:align: center
:width: 70.0%
RJ45 pinout
.. list-table:: Pylontech RJ10 Console Pinout (US2000B)
:header-rows: 1
* - RJ410 Pin
- Function
- Connect to
* - 2
- Pylontech RX
- ESPHome TX via transceiver
* - 3
- Pylontech TX
- ESPHome RX via transceiver
* - 4
- GND
- GND
Component/Hub
-------------
.. code-block:: yaml
# Example configuration entry
pylontech:
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **id** (**Required**, :ref:`config-id`): The id to use for this Pylontech component.
- **uart_id** (*Optional*): The uart Bus ID
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
Sensor
------
All values are reported for every Pylontech battery individually.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: pylontech
battery: 1
voltage:
name: "Battery1 Voltage"
current:
name: "Battery1 Current"
coulomb:
name: "Battery1 State of Charge"
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **pylontech_id** (*Optional*): Manually specify the ID of the pylontech instance if there are multiple.
- **battery** (**Required**): Which battery to monitor. 1 stands for the main battery, 2..6 for child batteries.
- **voltage** (*Optional*): Voltage of the battery. All options from :ref:`Sensor <config-sensor>`.
- **current** (*Optional*): Current flowing into the battery. Negative when discharging. All options from :ref:`Sensor <config-sensor>`.
- **coulomb** (*Optional*): State of Charge in percent. All options from :ref:`Sensor <config-sensor>`.
- **temperature** (*Optional*): Temperature. All options from :ref:`Sensor <config-sensor>`.
- **temperature_low** (*Optional*): Historic minimum temperature. All options from :ref:`Sensor <config-sensor>`.
- **temperature_high** (*Optional*): Historic maximum temperature. All options from :ref:`Sensor <config-sensor>`.
- **voltage_low** (*Optional*): Historic minimum voltage. All options from :ref:`Sensor <config-sensor>`.
- **voltage_high** (*Optional*): Historic maximum voltage. All options from :ref:`Sensor <config-sensor>`.
- **mos_temperature** (*Optional*): Temperature of the mosfets. All options from :ref:`Sensor <config-sensor>`.
Text Sensor
-----------
.. code-block:: yaml
# Example configuration entry
text_sensor:
- platform: pylontech
pylontech_id: pylontech0
battery: 1
base_state:
id: bat1_base_state
name: "Battery1 Base State"
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **pylontech_id** (**Optional**): Manually specify the ID of the pylontech instance if there are multiple.
- **battery** (**Required**): Which battery to monitor. 1 stands for the main battery, 2..6 for child batteries.
- **base_state** (*Optional*): Base state. Usually reads ``Dischg``, ``Charge`` or ``Idle``. All options from :ref:`Text Sensor <config-text_sensor>`.
- **voltage_state** (*Optional*): Voltage state. Usually reads ``Normal``. All options from :ref:`Text Sensor <config-text_sensor>`.
- **current_state** (*Optional*): Current state. Usually reads ``Normal``. All options from :ref:`Text Sensor <config-text_sensor>`.
- **temperature_state** (*Optional*): Temperature state. Usually reads ``Normal``. All options from :ref:`Text Sensor <config-text_sensor>`.
Energy Monitoring
-----------------
By combining :doc:`template sensors </components/sensor/template>` and :doc:`integration sensors </components/sensor/integration>`
one can monitor the energy flowing into and out of all batteries combined, ready for `Homeassistant Energy Monitoring <https://www.home-assistant.io/docs/energy/battery/>`__.
.. code-block:: yaml
sensor:
- platform: template
id: pylontech_power
name: "Pylontech power"
unit_of_measurement: W
lambda: |-
auto pwr1 = id(bat1_voltage).state * id(bat1_current).state;
auto pwr2 = id(bat2_voltage).state * id(bat2_current).state;
auto pwr = pwr1 + pwr2;
id(combined_charge_power).publish_state(max(pwr, 0.0f));
id(combined_discharge_power).publish_state(max(-pwr, 0.0f));
return pwr;
update_interval: 5s
device_class: power
state_class: measurement
- platform: template
id: combined_charge_power
- platform: template
id: combined_discharge_power
- platform: integration
name: "Pylontech charging"
sensor: combined_charge_power
time_unit: h
state_class: total_increasing
device_class: energy
unit_of_measurement: "Wh"
- platform: integration
name: "Pylontech discharging"
sensor: combined_discharge_power
time_unit: h
state_class: total_increasing
device_class: energy
unit_of_measurement: "Wh"
See Also
--------
- `Pylontech-Battery-Monitoring <https://github.com/irekzielinski/Pylontech-Battery-Monitoring>`__
- `nodered-pylontech-console-reader <https://github.com/juanhaywood/nodered-pylontech-console-reader>`__
- :ref:`uart`
- :ghedit:`Edit`

9
components/remote_receiver.rst
View File

@ -31,6 +31,7 @@ Configuration variables:
Set to ``all`` to dump all available codecs:
- **aeha**: Decode and dump AEHA infrared codes.
- **byronsx**: Decode and dump Byron SX doorbell RF codes.
- **canalsat**: Decode and dump CanalSat infrared codes.
- **canalsatld**: Decode and dump CanalSatLD infrared codes.
- **coolix**: Decode and dump Coolix infrared codes.
@ -81,6 +82,9 @@ Automations:
- **on_aeha** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
AEHA remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::AEHAData`
is passed to the automation for use in lambdas.
- **on_byronsx** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Byron SX doorbell RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::ByronSXData`
is passed to the automation for use in lambdas.
- **on_canalsat** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
CanalSat remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::CanalSatData`
is passed to the automation for use in lambdas.
@ -209,6 +213,11 @@ Remote code selection (exactly one of these has to be included):
- **data** (**Required**, 3-35 bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_aeha`
for more info. Usually you only need to copy this directly from the dumper output.
- **byronsx**: Trigger on a decoded Byron SX Doorbell RF remote code with the given data.
- **address** (**Required**, int): The 8-bit ID code to trigger on, see dumper output for more info.
- **command** (**Optional**, int): The 4-bit command to listen for. If omitted, will match on any command.
- **canalsat**: Trigger on a decoded CanalSat remote code with the given data.
- **device** (**Required**, int): The device to trigger on, see dumper output for more info.

38
components/remote_transmitter.rst
View File

@ -99,7 +99,25 @@ Configuration variables:
AEHA refers to the Association for Electric Home Appliances in Japan, a format used by Panasonic and many other companies.
.. _remote_transmitter-transmit_canalsat:
.. _remote_transmitter-transmit_byronsx:
``remote_transmitter.transmit_byronsx`` Action
**********************************************
This :ref:`action <config-action>` sends a Byron Doorbell RF protocol code to a remote transmitter.
.. code-block:: yaml
on_...:
- remote_transmitter.transmit_byronsx:
address: '0x4f'
command: '0x2'
Configuration variables:
- **address** (**Required**, int): The 8-bit ID to send, see dumper output for more info.
- **command** (**Required**, int): The command to send, see dumper output for more info.
- All other options from :ref:`remote_transmitter-transmit_action`... _remote_transmitter-transmit_canalsat:
``remote_transmitter.transmit_canalsat`` Action
***********************************************
@ -207,7 +225,7 @@ This :ref:`action <config-action>` sends a Draton Digistat RF remote code to a r
- remote_transmitter.transmit_drayton:
address: '0x6180'
channel: '0x12'
command: '0x02'
command: '0x02'
Configuration variables:
@ -350,6 +368,8 @@ This :ref:`action <config-action>` sends an NEC infrared remote code to a remote
In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC standard.
Therefore, if the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above.
For example, address: 0x84ED, command: 0x13EC becomes 0xB721 and 0x37C8 respectively.
Additionally, ESPHome does not automatically generate parity bits or pad values to 2 bytes.
So, in order to send command 0x0, you need to use 0xFF00 (0x00 being the command and 0xFF being the logical inverse).
.. code-block:: yaml
@ -357,11 +377,13 @@ This :ref:`action <config-action>` sends an NEC infrared remote code to a remote
- remote_transmitter.transmit_nec:
address: 0x1234
command: 0x78AB
command_repeats: 1
Configuration variables:
- **address** (**Required**, int): The address to send, see dumper output for more details.
- **command** (**Required**, int): The NEC command to send.
- **address** (**Required**, int): The 16-bit address to send, see dumper output for more details.
- **command** (**Required**, int): The 16-bit NEC command to send.
- **command_repeats** (*Optional*, int): The number of times the command bytes are sent in one transmission. Defaults to `1`.
- All other options from :ref:`remote_transmitter-transmit_action`.
``remote_transmitter.transmit_nexa`` Action
@ -943,7 +965,7 @@ earlier, create a new template switch that sends the RF code when triggered:
- remote_transmitter.transmit_rc_switch_raw:
code: '100010000000000010111110'
protocol: 2
repeat:
repeat:
times: 10
wait_time: 0s
@ -963,9 +985,9 @@ in the frontend. Click on it and you should see the remote signal being transmit
.. note::
Some devices require that the transmitted code be repeated for the signal to be picked up
as valid. Also the interval between repetitions can be important. Check that the pace of
repetition logs are consistent between the remote controller and the transmitter node.
Some devices require that the transmitted code be repeated for the signal to be picked up
as valid. Also the interval between repetitions can be important. Check that the pace of
repetition logs are consistent between the remote controller and the transmitter node.
You can adjust the ``repeat:`` settings accordingly.

37
components/rtttl.rst
View File

@ -3,6 +3,7 @@ Rtttl Buzzer
.. seo::
:description: Instructions for setting up a buzzer to play tones and rtttl songs with ESPHome.
**NEW:** Or play the song using the I2S speaker.
:image: buzzer.jpg
The ``rtttl``, component allows you to easily connect a passive piezo buzzer to your microcontroller
@ -15,8 +16,8 @@ and play monophonic songs. It accepts the Ring Tone Text Transfer Language, rttt
Buzzer Module
Overview
--------
Overview Using a passive buzzer
-------------------------------
It's important that your buzzer is a **passive** one, if it beeps when you feed it with 3.3V then it is not
a passive one and this library will not work properly.
@ -29,22 +30,42 @@ The tone generator needs a PWM capable output to work with, currently only the
# Example configuration entry
output:
- platform: ledc
pin: GPIO22
- platform: ...
id: rtttl_out
...
rtttl:
output: rtttl_out
id: my_rtttl
Overview Using the I2S speaker
------------------------------
The tone generator can instead be used with a :doc:`Speaker </components/speaker/index>` to output the audio.
.. code-block:: yaml
# Example configuration entry
speaker:
- platform: ...
id: my_speaker
...
rtttl:
speaker: my_speaker
id: my_rtttl
Configuration variables:
------------------------
- **output** (**Required**, :ref:`config-id`): The id of the :ref:`float output <output>` to use for
- **output** (**Exclusive**, :ref:`config-id`): The id of the :ref:`float output <output>` to use for
this buzzer.
- **speaker** (**Exclusive**, :ref:`config-id`): The id of the :ref:`speaker <i2s_audio>` to play the song on.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **on_finished_playback** (*Optional*, :ref:`Automation <automation>`): An action to be
performed when playback is finished.
Note: You can only use the **output** or **speaker** variable, not both at the same time.
``rtttl.play`` Action
---------------------
@ -103,7 +124,7 @@ Common beeps
You can do your own beep patterns too! Here's a short collection so you can just use right away or tweak them to your like:
.. code-block:: yaml
.. code-block::
two_short:d=4,o=5,b=100:16e6,16e6
long:d=1,o=5,b=100:e6
@ -160,6 +181,8 @@ Sample code
See Also
--------
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/ledc`
- :doc:`/components/speaker/index`
- :apiref:`rtttl/rtttl.h`
- :ghedit:`Edit`

2
components/select/index.rst
View File

@ -357,7 +357,7 @@ Setting up three options and set component state to selected option value.
- "Option1"
- "Option2"
- "Option3"
initial_option: "OFF"
initial_option: "Option1"
optimistic: true
set_action:
- logger.log:

46
components/sensor/a02yyuw.rst Normal file
View File

@ -0,0 +1,46 @@
A02YYUW Waterproof Ultrasonic Sensor
====================================
.. seo::
:description: Instructions for setting up A02YYUW waterproof ultrasonic distance sensor in ESPHome.
:image: a02yyuw.jpg
:keywords: ultrasonic, DFRobot, A02YYUW
This sensor allows you to use A02YYUW waterproof ultrasonic sensor by DFRobot
(`datasheet <https://wiki.dfrobot.com/_A02YYUW_Waterproof_Ultrasonic_Sensor_SKU_SEN0311>`__)
with ESPHome to measure distances. This sensor can measure
ranges between 3 centimeters and 450 centimeters with a resolution of 1 milimeter.
Since this sensor reads multiple times per second, :ref:`sensor-filters` are highly recommended.
To use the sensor, first set up an :ref:`uart` with a baud rate of 9600 and connect the sensor to the specified pin.
.. figure:: images/a02yyuw-full.jpg
:align: center
:width: 50.0%
A02YYUW Waterproof Ultrasonic Distance Sensor.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: "a02yyuw"
name: "Distance"
Configuration variables:
------------------------
- **name** (**Required**, string): The name of the sensor.
- **uart_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`UART bus <uart>` you wish to use for this sensor.
Use this if you want to use multiple UART buses at once.
- All other options from :ref:`Sensor <config-sensor>`.
See Also
--------
- :ref:`sensor-filters`
- :ref:`uart`
- :apiref:`a02yyuw/a02yyuw.h`
- :ghedit:`Edit`

211
components/sensor/ade7953.rst
View File

@ -15,7 +15,7 @@ ADE7953 Power Sensor
The ``ade7953`` sensor platform allows you to use ADE7953 single phase energy metering ICs
(`datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/ADE7953.pdf>`__)
with ESPHome. These are commonly found in **Shelly 2.5** devices.
with ESPHome. These are commonly found in **Shelly** devices.
This sensor can measure voltage and has two channels for reading current and active power (A & B).
@ -23,42 +23,235 @@ This sensor can measure voltage and has two channels for reading current and act
SAFETY HAZARD: Some devices such as Sonoff POWs/Shelly/etc, have the digital GND connected directly to mains voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent any use of the dangerous digital pins.
The :ref:`I²C Bus <i2c>` is
required to be set up in your configuration for this sensor to work.
The :ref:`I²C Bus <i2c>`
or :ref:`SPI Bus <spi>`
is required to be set up in your configuration for this sensor to work.
Over I²C
--------
.. code-block:: yaml
# Example configuration entry
# Example configuration entry for i2c
sensor:
- platform: ade7953
- platform: ade7953_i2c
irq_pin: GPIO16
voltage:
name: ADE7953 Voltage
frequency:
name: ADE7953 Frequency
current_a:
name: ADE7953 Current A
current_b:
name: ADE7953 Current B
power_factor_a:
name: "ADE7953 Power Factor A"
power_factor_b:
name: "ADE7953 Power Factor B"
apparent_power_a:
name: "ADE7953 Apparent Power A"
apparent_power_b:
name: "ADE7953 Apparent Power B"
active_power_a:
name: ADE7953 Active Power A
active_power_b:
name: ADE7953 Active Power B
update_interval: 60s
reactive_power_a:
name: "ADE7953 Reactive Power A"
reactive_power_b:
name: "ADE7953 Reactive Power B"
Configuration variables:
------------------------
************************
- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x38``.
- **irq_pin** (*Optional*, :ref:`config-pin`): The pin connected to the ADE7935 IRQ line (if connected)
- **voltage** (*Optional*): Use the voltage value of the sensor in volt. All options from
- **voltage** (*Optional*): Use the voltage value of the sensor in volts. All options from
:ref:`Sensor <config-sensor>`.
- **frequency** (*Optional*): Use the frequency value of the sensor in hertzs. All options from
:ref:`Sensor <config-sensor>`.
- **current_a** (*Optional*): Use the current value of the A channel in amperes. All options from
:ref:`Sensor <config-sensor>`.
- **current_b** (*Optional*): Use the current value of the B channel in amperes. All options from
:ref:`Sensor <config-sensor>`.
- **power_factor_a** (*Optional*): Use the power factor of the A channel in percentage. All options from
:ref:`Sensor <config-sensor>`.
- **power_factor_b** (*Optional*): Use the power factor of the B channel in percentage. All options from
:ref:`Sensor <config-sensor>`.
- **aparent_power_a** (*Optional*): Use the apparent power value of the A channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **aparent_power_b** (*Optional*): Use the apparent power value of the B channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **active_power_a** (*Optional*): Use the power value of the A channel in watts. All options from
:ref:`Sensor <config-sensor>`.
- **active_power_b** (*Optional*): Use the power value of the B channel in watts. All options from
:ref:`Sensor <config-sensor>`.
- **reactive_power_a** (*Optional*): Use the rective power value of the A channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **reactive_power_b** (*Optional*): Use the rective power value of the B channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **voltage_pga_gain** (*Optional*, mapping): Set the input PGA voltage amplification. Defaults to ``1x``. Possible values are:
- ``1x``
- ``2x``
- ``4x``
- ``8x``
- ``16x``
- ``22x``
- **current_pga_gain_a** (*Optional*, mapping): Set the input PGA current amplification of the A channel. Defaults to ``1x``. Possible values are:
- ``1x``
- ``2x``
- ``4x``
- ``8x``
- ``16x``
- ``22x``
- **current_pga_gain_b** (*Optional*, mapping): Set input PGA current amplification of the B channel. Defaults to ``1x``. Possible values are:
- ``1x``
- ``2x``
- ``4x``
- ``8x``
- ``16x``
- **voltage_gain** (*Optional*, int): Set the voltage amplification. Defaults to ``0x400000``.
- **current_gain_a** (*Optional*, int): Set the current amplification of the A channel. Defaults to ``0x400000``.
- **current_gain_b** (*Optional*, int): Set the current amplification of the B channel. Defaults to ``0x400000``.
- **active_power_gain_a** (*Optional*, int): Set the active power amplification of the A channel. Defaults to ``0x400000``.
- **active_power_gain_b** (*Optional*, int): Set the active power amplification of the B channel. Defaults to ``0x400000``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
Over SPI
--------
.. code-block:: yaml
# Example configuration entry for SPI (taken from a Shelly Pro 4PM)
sensor:
- platform: ade7953_spi
cs_pin: GPIO04
irq_pin: GPIO35
current_pga_gain_a: 2x
current_pga_gain_b: 2x
current_gain_a: 0x600000
current_gain_b: 0x600000
voltage:
name: "Voltage"
filters:
- delta: 1
frequency:
name: ADE7953 Frequency
filters:
- delta: 0.1
current_a:
name: "Current A"
filters:
- delta: 0.01
current_b:
name: "Current B"
filters:
- delta: 0.01
power_factor_a:
name: "Power Factor A"
filters:
- delta: 5
power_factor_b:
name: "ADE7953 Power Factor B"
filters:
- delta: 5
apparent_power_a:
name: "Apparent Power A"
filters:
- delta: 1
apparent_power_b:
name: "Apparent Power B"
filters:
- delta: 1
active_power_a:
name: "Power A"
id: active_power_1
# active_power is inverted, so multiply by -1
filters:
- multiply: -1
- delta: 1
active_power_b:
name: "Power B"
id: active_power_2
# active_power is inverted, so multiply by -1
filters:
- multiply: -1
- delta: 1
reactive_power_a:
name: "Reactive Power A"
filters:
- delta: 1
reactive_power_b:
name: "Reactive Power B"
filters:
- delta: 1
Configuration variables:
************************
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The chip select pin.
- **irq_pin** (*Optional*, :ref:`config-pin`): The pin connected to the ADE7935 IRQ line (if connected)
- **voltage** (*Optional*): Use the voltage value of the sensor in volts. All options from
:ref:`Sensor <config-sensor>`.
- **frequency** (*Optional*): Use the frequency value of the sensor in hertzs. All options from
:ref:`Sensor <config-sensor>`.
- **current_a** (*Optional*): Use the current value of the A channel in amperes. All options from
:ref:`Sensor <config-sensor>`.
- **current_b** (*Optional*): Use the current value of the B channel in amperes. All options from
:ref:`Sensor <config-sensor>`.
- **power_factor_a** (*Optional*): Use the power factor of the A channel in percentage. All options from
:ref:`Sensor <config-sensor>`.
- **power_factor_b** (*Optional*): Use the power factor of the B channel in percentage. All options from
:ref:`Sensor <config-sensor>`.
- **aparent_power_a** (*Optional*): Use the apparent power value of the A channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **aparent_power_b** (*Optional*): Use the apparent power value of the B channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **active_power_a** (*Optional*): Use the power value of the A channel in watts. All options from
:ref:`Sensor <config-sensor>`.
- **active_power_b** (*Optional*): Use the power value of the B channel in watts. All options from
:ref:`Sensor <config-sensor>`.
- **reactive_power_a** (*Optional*): Use the rective power value of the A channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **reactive_power_b** (*Optional*): Use the rective power value of the B channel in volt ampers. All options from
:ref:`Sensor <config-sensor>`.
- **voltage_pga_gain** (*Optional*, mapping): Set the input PGA voltage amplification. Defaults to ``1x``. Possible values are:
- ``1x``
- ``2x``
- ``4x``
- ``8x``
- ``16x``
- ``22x``
- **current_pga_gain_a** (*Optional*, mapping): Set the input PGA current amplification of the A channel. Defaults to ``1x``. Possible values are:
- ``1x``
- ``2x``
- ``4x``
- ``8x``
- ``16x``
- ``22x``
- **current_pga_gain_b** (*Optional*, mapping): Set input PGA current amplification of the B channel. Defaults to ``1x``. Possible values are:
- ``1x``
- ``2x``
- ``4x``
- ``8x``
- ``16x``
- **voltage_gain** (*Optional*, int): Set the voltage amplification. Defaults to ``0x400000``.
- **current_gain_a** (*Optional*, int): Set the current amplification of the A channel. Defaults to ``0x400000``.
- **current_gain_b** (*Optional*, int): Set the current amplification of the B channel. Defaults to ``0x400000``.
- **active_power_gain_a** (*Optional*, int): Set the active power amplification of the A channel. Defaults to ``0x400000``.
- **active_power_gain_b** (*Optional*, int): Set the active power amplification of the B channel. Defaults to ``0x400000``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
Use with Shelly 2.5
@ -84,7 +277,7 @@ Additionally, the device has an ::doc:`NTC temperature sensor <ntc>`.
scl: GPIO14
sensor:
- platform: ade7953
- platform: ade7953_i2c
irq_pin: GPIO16
voltage:
name: Shelly Voltage

10
components/sensor/aht10.rst
View File

@ -4,10 +4,10 @@ AHT10 Temperature+Humidity Sensor
.. seo::
:description: Instructions for setting up AHT10 temperature and humidity sensors
:image: aht10.jpg
:keywords: aht10 aht20 aht21 dht20
:keywords: aht10 aht20 dht20
The ``aht10`` Temperature+Humidity sensor allows you to use your AHT10
(`datasheet <http://www.aosong.com/userfiles/files/media/aht10%E8%A7%84%E6%A0%BC%E4%B9%A6v1_1%EF%BC%8820191015%EF%BC%89.pdf>`__), AHT20 (`datasheet <https://cdn-learn.adafruit.com/assets/assets/000/091/676/original/AHT20-datasheet-2020-4-16.pdf?1591047915>`__), AHT21 (`datasheet <https://asairsensors.com/wp-content/uploads/2021/09/Data-Sheet-AHT21-Humidity-and-Temperature-Sensor-ASAIR-V1.0.03.pdf>`__) :ref:`I²C <i2c>`-based sensor with ESPHome.
(`datasheet <http://www.aosong.com/userfiles/files/media/aht10%E8%A7%84%E6%A0%BC%E4%B9%A6v1_1%EF%BC%8820191015%EF%BC%89.pdf>`__) or AHT20 (`datasheet <https://cdn-learn.adafruit.com/assets/assets/000/091/676/original/AHT20-datasheet-2020-4-16.pdf?1591047915>`__) :ref:`I²C <i2c>`-based sensor with ESPHome.
The DHT20 (`datasheet <https://cdn.sparkfun.com/assets/8/a/1/5/0/DHT20.pdf>`__) sensor has the packaging of the :doc:`dht` series, but has the AHT20 inside and is speaking :ref:`I²C <i2c>` as well.
@ -30,6 +30,7 @@ The DHT20 (`datasheet <https://cdn.sparkfun.com/assets/8/a/1/5/0/DHT20.pdf>`__)
# Example configuration entry
sensor:
- platform: aht10
variant: AHT10
temperature:
name: "Living Room Temperature"
humidity:
@ -39,6 +40,11 @@ The DHT20 (`datasheet <https://cdn.sparkfun.com/assets/8/a/1/5/0/DHT20.pdf>`__)
Configuration variables:
------------------------
- **variant** (*Optional*, enum): Set the variant of the device in use. Defaults to ``AHT10``.
- ``AHT10`` - For AHT10 devices.
- ``AHT20`` - For AHT20 devices.
- **temperature** (**Required**): The information for the temperature sensor.
- **name** (**Required**, string): The name for the temperature sensor.

1
components/sensor/airthings_ble.rst
View File

@ -53,6 +53,7 @@ Configuration example:
sensor:
- platform: airthings_wave_plus
name: wave_plus
ble_client_id: airthings01
update_interval: 5min # default
battery_update_interval: 24h # default

15
components/sensor/ble_client.rst
View File

@ -5,11 +5,18 @@ BLE Client Sensor
:description: Fetch numeric values from BLE devices.
:image: bluetooth.svg
The ``ble_client`` component is a sensor platform that can
query BLE devices for RSSI or specific values of service characteristics.
The ``ble_client`` component is a sensor platform that can query BLE devices for RSSI or specific
values of service characteristics.
For more information on BLE services and characteristics, see
:doc:`/components/ble_client`.
For more information on BLE services and characteristics, see :doc:`/components/ble_client`.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml

8
components/sensor/ble_rssi.rst
View File

@ -10,6 +10,14 @@ The ``ble_rssi`` sensor platform lets you track the RSSI value or signal strengt
BLE device. See :ref:`the binary sensor setup <esp32_ble_tracker-setting_up_devices>` for
instructions for setting up this platform.
.. warning::
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
audio components are most likely to cause issues.
.. code-block:: yaml
# Example configuration entry

62
components/sensor/bme680.rst
View File

@ -103,6 +103,68 @@ configure this amount. Possible oversampling values:
- ``8x``
- ``16x`` (default)
.. _bme680-advanced-configuration:
Advanced Configuration
----------------------
Add indoor air quality (IAQ) calculation and IAQ label, based on the values in the `BME680 BSEC component </components/sensor/bme680_bsec.html?highlight=bme680#index-for-air-quality-iaq-measurement>`__ index.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: bme680
temperature:
name: "BME680 Temperature"
oversampling: 16x
pressure:
name: "BME680 Pressure"
humidity:
id: "humidity"
name: "BME680 Humidity"
gas_resistance:
id: "gas_resistance"
name: "BME680 Gas Resistance"
address: 0x77
update_interval: 60s
- platform: template
name: "BME680 Indoor Air Quality"
id: iaq
icon: "mdi:gauge"
# caulculation: comp_gas = log(R_gas[ohm]) + 0.04 log(Ohm)/%rh * hum[%rh]
lambda: |-
return log(id(gas_resistance).state) + 0.04 * id(humidity).state;
text_sensor:
- platform: template
name: "BME680 IAQ Classification"
icon: "mdi:checkbox-marked-circle-outline"
lambda: |-
if (int(id(iaq).state) <= 50) {
return {"Excellent"};
}
else if (int(id(iaq).state) <= 100) {
return {"Good"};
}
else if (int(id(iaq).state) <= 150) {
return {"Lightly polluted"};
}
else if (int(id(iaq).state) <= 200) {
return {"Moderately polluted"};
}
else if (int(id(iaq).state) <= 250) {
return {"Heavily polluted"};
}
else if (int(id(iaq).state) <= 350) {
return {"Severely polluted"};
}
else if (int(id(iaq).state) <= 500) {
return {"Extremely polluted"};
}
else {
return {"unknown"};
}
See Also
--------

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.3 KiB

After

Width:  |  Height:  |  Size: 6.2 KiB

10
components/sensor/custom.rst
View File

@ -1,6 +1,16 @@
Custom Sensor Component
=======================
.. warning::
Custom components are deprecated, not recommended for new configurations
and will be removed from ESPHome in a future release.
Please look at creating a real ESPHome component and "importing" it into your
configuration with :doc:`/components/external_components`.
You can find some basic documentation on creating your own components
at :ref:`contributing_to_esphome`.
.. seo::
:description: Instructions for setting up Custom C++ sensors with ESPHome.
:image: language-cpp.svg

3
components/sensor/dsmr.rst
View File

@ -419,6 +419,9 @@ or a transistor-based circuit are not feasible options. Here's an example circui
.. figure:: images/dsmr-request-pin-circuit-example.png
When using a type of MCU that provides 5V on the GPIO outputs instead of 3.3V, then use a 330 Ohm
resistor instead of the 200 Ohm resistor.
.. _sensor-dsmr-improving_reader_results:
Improving reader results

110
components/sensor/ens160.rst Normal file
View File

@ -0,0 +1,110 @@
ENS160 Sensor
=============
.. seo::
:description: Instructions for setting up ENS160 air-quality sensors
:keywords: ENS160
The ``ens160`` sensor platform allows you to use your ENS160
(`datasheet <https://www.sciosense.com/wp-content/uploads/documents/SC-001224-DS-7-ENS160-Datasheet.pdf>`__) air-quality sensors with ESPHome. The :ref:`I²C <i2c>` component is
required to be set up in your configuration for this sensor to work.
.. note::
On first power-up of the ENS160 sensor, there is a 1 hour initial startup delay before readings will be available.
For subsequent starts or reboots, there is a 3 minute warm up period before readings are available. Also, be aware that the
ENS160 can take up to 1 second for sucessive data measurements to be ready.
.. figure:: images/ens160.jpg
:align: center
:width: 80.0%
ENS160 Air Quality Sensor.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: ens160
eco2:
name: "ENS160 eCO2"
tvoc:
name: "ENS160 Total Volatile Organic Compounds"
aqi:
name: "ENS160 Air Quality Index"
update_interval: 60s
address: 0x53
compensation:
temperature: id_temperature_sensor
humidity: id_humidity_sensor
Configuration variables:
------------------------
- **eco2** (**Required**): Configuration for the eCO2 sensor.
- **name** (**Required**, string): The name for the eCO2 sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **tvoc** (**Required**): Configuration for the TVOC sensor.
- **name** (**Required**, string): The name for the TVOC sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **aqi** (*Optional*): Configuration for the air quality index sensor.
- **name** (**Required**, string): The name for the AQI sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``. The update interval should be greater than the measurement
frequency of the ENS160 which is up to 1 second.
Advanced:
- **address** (*Optional*, int): Manually specify the I²C address of
the sensor. Defaults to ``0x53``. Another address can be ``0x52``.
- **compensation** (*Optional*): The block containing sensors used for compensation.
Temperature and humidity compensation improves the accuracy of sensor readings. Without compensation, the
ENS160 internally assumes 25°C temperature and 50% humidity, with readings noticeably diverting from real changes without compensation in temperature and humidity.
- **temperature** (**Required**, :ref:`config-id`): The ID of an external temperature sensor.
- **humidity** (**Required**, :ref:`config-id`): The ID of an external humidity sensor.
Example Text Sensor configuration
---------------------------------
The Air Quality Index(AQI) from this sensor is a number between 1 and 5. The ENS160
(`datasheet <https://www.sciosense.com/wp-content/uploads/documents/SC-001224-DS-7-ENS160-Datasheet.pdf>`__) states that
"The AQI-UBA air quality index is derived from a guideline by the German Federal Environmental
Agency based on a TVOC sum signal". The following is an example configuration to convert the numeric ENS160 AQI to the rating text.
.. code-block:: yaml
text_sensor:
- platform: template
name: "ENS160 Air Quality Rating"
lambda: |-
switch ( (int) (id(ens160_air_quality_index).state) ) {
case 1: return {"Excellent"};
case 2: return {"Good"};
case 3: return {"Moderate"};
case 4: return {"Poor"};
case 5: return {"Unhealthy"};
default: return {"Not Available"};
}
See Also
--------
- :ref:`sensor-filters`
- :doc:`ccs811`
- :doc:`sgp30`
- :apiref:`ens160/ens160.h`
- :ghedit:`Edit`

142
components/sensor/hlw8012.rst
View File

@ -124,6 +124,148 @@ when SEL=1 voltage is measured. To accommodate this change use the following con
name: "BL0937 Power"
update_interval: 60s
Calibration
-----------
What you need:
- Your ESPHome power measurement plug
- A calibrated power meter that can measure voltage, current, power and power factor
- A large resistive load like an electric heater or kettle, ideally over 1000W
Steps:
- Find the currently used calibration values for ``current_resistor`` and ``voltage_divider`` in your device's YAML configuration or upload a new firmware with some known calibration values to the ESP.
- Plug the ESP power measurement plug into the calibrated power meter.
- Plug the load into the ESP plug.
- Turn on the load and make sure the power factor (PF) displayed on the power meter is 1.0. If it's not, you need to pick a different load.
- Wait for the readings to settle on both the power meter and the ESP.
- Write down the voltage reading of the power meter and the ESP at the same time.
- Write down the power reading of the power meter and the ESP at the same time.
- Write down the current reading of the power meter and the ESP at the same time.
- Use the calculator below to calculate the new calibration values for the ESP. These values will help it accurately measure power, voltage and current in the future.
- Upload the new values to the ESP.
Calibration values on the ESP:
.. raw:: html
<table>
<tr><td>voltage_divider:</td><td><input type="text" inputmode="numeric" value="2351" id="voltage-divider" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"></td></tr>
<tr><td>current_resistor:</td><td><input type="text" inputmode="numeric" value="0.001" id="current-resistor" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"></td></tr>
<tr><td>current_multiply:</td><td><input type="text" inputmode="numeric" value="1" id="current-multiply" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"></td></tr>
</table>
ESP measurements:
.. raw:: html
<table>
<tr><td>Voltage:</td><td><input type="text" inputmode="numeric" id="sensor-voltage" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> V</td></tr>
<tr><td>Power:</td><td><input type="text" inputmode="numeric" id="sensor-power" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> W</td></tr>
<tr><td>Current:</td><td><input type="text" inputmode="numeric" id="sensor-current" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> A</td></tr>
</table>
Power meter measurements:
.. raw:: html
<table>
<tr><td>Voltage:</td><td><input type="text" inputmode="numeric" id="real-voltage" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> V</td></tr>
<tr><td>Power:</td><td><input type="text" inputmode="numeric" id="real-power" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> W</td></tr>
<tr><td>Current:</td><td><input type="text" inputmode="numeric" id="real-current" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> A</td></tr>
</table>
New calibration values:
.. raw:: html
<table>
<tr><td>voltage_divider:</td><td><input type="text" id="voltage-divider-new" onclick="this.focus();this.select()" style="width: 100px; max-width: 75vw;" readonly="readonly"></td></tr>
<tr><td>current_resistor:</td><td><input type="text" id="current-resistor-new" onclick="this.focus();this.select()" style="width: 100px; max-width: 75vw;" readonly="readonly"></td></tr>
<tr><td>current_multiply:</td><td><input type="text" id="current-multiply-new" onclick="this.focus();this.select()" style="width: 100px; max-width: 75vw;" readonly="readonly"></td></tr>
</table>
New ESP measurements:
.. raw:: html
<table>
<tr><td>Voltage:</td><td><input type="text" id="sensor-voltage-new" style="width: 100px; max-width: 75vw;" readonly="readonly"> V</td></tr>
<tr><td>Power:</td><td><input type="text" id="sensor-power-new" style="width: 100px; max-width: 75vw;" readonly="readonly"> W</td></tr>
<tr><td>Current:</td><td><input type="text" id="sensor-current-new" style="width: 100px; max-width: 75vw;" readonly="readonly"> A</td></tr>
</table>
<script>
function calc() {
let voltage_divider = parseFloat(document.getElementById("voltage-divider").value.replace(",", "."))
let current_resistor = parseFloat(document.getElementById("current-resistor").value.replace(",", "."))
let current_multiply = parseFloat(document.getElementById("current-multiply").value.replace(",", "."))
let real_voltage = parseFloat(document.getElementById("real-voltage").value.replace(",", "."))
let real_power = parseFloat(document.getElementById("real-power").value.replace(",", "."))
let real_current = parseFloat(document.getElementById("real-current").value.replace(",", "."))
let sensor_voltage = parseFloat(document.getElementById("sensor-voltage").value.replace(",", "."))
let sensor_power = parseFloat(document.getElementById("sensor-power").value.replace(",", "."))
let sensor_current = parseFloat(document.getElementById("sensor-current").value.replace(",", "."))
let calc_voltage = (document.getElementById("real-voltage").value !== "" || document.getElementById("sensor-voltage").value !== "")
let calc_power = (document.getElementById("real-power").value !== "" || document.getElementById("sensor-power").value !== "")
let calc_current = (document.getElementById("real-current").value !== "" || document.getElementById("sensor-current").value !== "")
let voltage_divider_new = voltage_divider;
let current_resistor_new = current_resistor;
let current_multiply_new = current_multiply;
if (calc_voltage) {
voltage_divider_new *= real_voltage / sensor_voltage;
}
if (calc_power) {
if (calc_voltage) {
current_resistor_new *= (sensor_power / sensor_voltage) / (real_power / real_voltage);
} else {
current_resistor_new *= sensor_power / real_power;
}
}
if (calc_current) {
if (calc_power) {
current_multiply_new *= (real_current / sensor_current) * (current_resistor_new / current_resistor);
} else {
current_resistor_new *= sensor_current / real_current;
}
}
document.getElementById("voltage-divider-new").value = voltage_divider_new;
document.getElementById("current-resistor-new").value = current_resistor_new;
document.getElementById("current-multiply-new").value = current_multiply_new;
let sensor_voltage_new = sensor_voltage * voltage_divider_new / voltage_divider
let sensor_power_new = sensor_power * (voltage_divider_new / current_resistor_new) / (voltage_divider / current_resistor)
let sensor_current_new = sensor_current * (current_multiply_new / current_resistor_new) / (current_multiply / current_resistor)
document.getElementById("sensor-voltage-new").value = Number(sensor_voltage_new.toFixed(8));
document.getElementById("sensor-power-new").value = Number(sensor_power_new.toFixed(8));
document.getElementById("sensor-current-new").value = Number(sensor_current_new.toFixed(8));
}
</script>
Example Config:
.. code-block:: yaml
substitutions:
voltage_divider: "2351"
current_resistor: "0.001"
current_multiply: "1.0"
sensor:
- platform: hlw8012
current_resistor: ${current_resistor}
voltage_divider: ${voltage_divider}
current:
name: "HLW8012 Current"
filters:
- multiply: ${current_multiply}
voltage:
name: "HLW8012 Voltage"
power:
name: "HLW8012 Power"
energy:
name: "HLW8012 Energy"
update_interval: 60s
See Also
--------

62
components/sensor/honeywellabp2_i2c.rst Normal file
View File

@ -0,0 +1,62 @@
Honeywell ABP 2 Pressure Sensors
================================
.. seo::
:description: Instructions for setting up Honeywell ABP2 Pressure sensors
:image: honeywellabp.jpg
:keywords: Honeywell ABP2
The ``honeywellabp2_i2c`` sensor platform allows you to use your Honeywell ABP
(`website <https://sps.honeywell.com/us/en/products/advanced-sensing-technologies/healthcare-sensing/board-mount-pressure-sensors/basic-abp2-series>`__,
`datasheet <https://prod-edam.honeywell.com/content/dam/honeywell-edam/sps/siot/en-us/products/sensors/pressure-sensors/board-mount-pressure-sensors/basic-abp2-series/documents/sps-siot-abp2-series-datasheet-32350268-en.pdf?download=false>`_)
pressure and temperature sensors with ESPHome. The :ref:`I2C <i2c>` is
required to be set up in your configuration for this sensor to work
.. figure:: images/honeywellabp.jpg
:align: center
:width: 50.0%
Honeywell ABP Pressure and Temperature Sensor.
.. code-block:: yaml
sensor:
- platform: honeywellabp2_i2c
pressure:
name: "Honeywell2 pressure"
min_pressure: 0
max_pressure: 16000
transfer_function: "A"
temperature:
name: "Honeywell2 temperature"
Configuration variables:
------------------------
The values for ``min_pressure`` and ``max_pressure`` and ``transfer_function`` can be found in the device datasheet for the specific device.
These are used to calculate the pressure reading published by the sensor. Some sensors measure pressure in ``bar`` or ``Psi``;
set ``min_pressure`` and ``max_pressure`` to the measurement range, ``transfer_function`` to ``A`` or ``B`` and ``unit_of_measurement`` to the appropriate unit for your device.
- **pressure** (*Optional*): The information for the pressure sensor.
- **min_pressure** (**Required**, int or float): Minimum pressure for the pressure sensor.
- **max_pressure** (**Required**, int or float): Maximum pressure for the pressure sensor.
- **transfer_function** (**Required**, "A" or "B"): Transfer function used by the pressure sensor.
- All other options from :ref:`Sensor <config-sensor>`.
Some sensors do not have temperature sensing ability, see datasheet. In some cases the sensor may return a valid temperature even though the
datasheet indicates that the sensor does not measure temperature.
- **temperature** (*Optional*): The information for the temperature sensor.
All options from :ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
See Also
--------
- :ref:`sensor-filters`
- :apiref:`honeywellabp/honeywellabp2.h`
- :ghedit:`Edit`

51
components/sensor/iaqcore.rst Normal file
View File

@ -0,0 +1,51 @@
AMS iAQ-Core Indoor Air Quality Sensor
======================================
.. seo::
:description: Instructions for setting up the iAQ-Core sensor.
:image: iaqcore.jpg
:keywords: co2, tvoc, i2c
The AMS iAQ-Core sensor allows you to use your
(`datasheet <https://www.sciosense.com/wp-content/uploads/documents/iaQ-Core-Datasheet.pdf>`__)
sensors with ESPHome.
.. figure:: images/iaqcore.jpg
:align: center
:width: 30.0%
AMS iAQ-Core Indoor Air Quality Sensor.
The iAQ-Core sensor module is used to measure VOC levels and provide CO2 equivalent and TVOC equivalent predictions. The data is available via I²C bus.
To use the sensor, first set up an :ref:`I²C Bus <i2c>` and connect the sensor to the specified pins.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: iaqcore
address: 0x5A
update_interval: 60s
co2:
name: "iAQ Core CO2 Sensor"
tvoc:
name: "iAQ Core TVOC Sensor"
Configuration variables:
------------------------
- **i2c_id** (*Optional*, ID): The id of the I²C Bus.
- **address** (*Optional*, int): Manually specifiy the I²C address of the sensor. Defaults to ``0x5A``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
- **co2** (*Optional*): The configuration for the CO2 sensor. All options from
:ref:`Sensor <config-sensor>`.
- **tvoc** (*Optional*): The configuration for the TVOC sensor. All options from
:ref:`Sensor <config-sensor>`.
See Also
--------
- :ref:`sensor-filters`
- :doc:`/components/sensor/index`
- :ghedit:`Edit`

BIN
components/sensor/images/6897d.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
components/sensor/images/a02yyuw-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
components/sensor/images/dsmr-request-pin-circuit-example.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 41 KiB

Some files were not shown because too many files have changed in this diff Show More