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

Merge branch 'current' into current

This commit is contained in:
H. Árkosi Róbert 2022-11-28 09:29:40 +01:00 committed by GitHub
parent 21da19bdfa 41e8a82c79
commit 256fb1a3d7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
96 changed files with 13831 additions and 901 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doxygen
View File

@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 2022.9.4
PROJECT_NUMBER = 2022.11.3
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a

2
Makefile
View File

@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
ESPHOME_REF = 2022.9.4
ESPHOME_REF = 2022.11.3
.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify

3
_redirects
View File

@ -3,3 +3,6 @@
# Moved components
# e.g: /components/sensors/abc.html /components/sensors/xyz.html 301
/components/sensor/sgp40.html /components/sensor/sgp4x.html 301
/components/binary_sensor/xpt2046.html /components/touchscreen/xpt2046.html 301
/devices/esp8266.html /components/esp8266.html
/devices/esp32.html /components/esp32.html

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 59 KiB

2
_static/version
View File

@ -1 +1 @@
2022.9.4
2022.11.3

4
_static/webserver-v1.js
View File

@ -23,7 +23,7 @@ source.addEventListener('log', function (e) {
log.innerHTML += '<span class="' + klass + '">' + e.data.substr(7, e.data.length - 11) + "</span>\n";
});
actions = [
const actions = [
["switch", ["toggle"]],
["light", ["toggle"]],
["fan", ["toggle"]],
@ -31,7 +31,7 @@ actions = [
["button", ["press"]],
["lock", ["lock", "unlock", "open"]],
];
multi_actions = [
const multi_actions = [
["select", "option"],
["number", "value"],
];

2
_static/webserver-v1.min.js vendored
View File

@ -1 +1 @@
const source=new EventSource("/events");source.addEventListener("log",function(t){const e=document.getElementById("log");let n=[["","e"],["","w"],["","i"],["","c"],["","d"],["","v"]],o="";for(const e of n)t.data.startsWith(e[0])&&(o=e[1]);""==o&&(e.innerHTML+=t.data+"\n"),e.innerHTML+='<span class="'+o+'">'+t.data.substr(7,t.data.length-11)+"</span>\n"}),actions=[["switch",["toggle"]],["light",["toggle"]],["fan",["toggle"]],["cover",["open","close"]],["button",["press"]],["lock",["lock","unlock","open"]]],multi_actions=[["select","option"],["number","value"]],source.addEventListener("state",function(t){const e=JSON.parse(t.data);document.getElementById(e.id).children[1].innerText=e.state});const states=document.getElementById("states");let row,i=0;for(;row=states.rows[i];i++)if(row.children[2].children.length){for(const t of actions)if(row.classList.contains(t[0])){let e=row.id.substr(t[0].length+1);for(let n=0;n<row.children[2].children.length&&n<t[1].length;n++)row.children[2].children[n].addEventListener("click",function(){const o=new XMLHttpRequest;o.open("POST","/"+t[0]+"/"+e+"/"+t[1][n],!0),o.send()})}for(const t of multi_actions)if(row.classList.contains(t[0])){let e=row.id.substr(t[0].length+1);row.children[2].children[0].addEventListener("change",function(){const n=new XMLHttpRequest;n.open("POST","/"+t[0]+"/"+e+"/set?"+t[1]+"="+encodeURIComponent(this.value),!0),n.send()})}}
const source=new EventSource("/events");source.addEventListener("log",function(t){const e=document.getElementById("log");let n=[["","e"],["","w"],["","i"],["","c"],["","d"],["","v"]],o="";for(const e of n)t.data.startsWith(e[0])&&(o=e[1]);""==o&&(e.innerHTML+=t.data+"\n"),e.innerHTML+='<span class="'+o+'">'+t.data.substr(7,t.data.length-11)+"</span>\n"});const actions=[["switch",["toggle"]],["light",["toggle"]],["fan",["toggle"]],["cover",["open","close"]],["button",["press"]],["lock",["lock","unlock","open"]]];const multi_actions=[["select","option"],["number","value"]];source.addEventListener("state",function(t){const e=JSON.parse(t.data);document.getElementById(e.id).children[1].innerText=e.state});const states=document.getElementById("states");let row,i=0;for(;row=states.rows[i];i++)if(row.children[2].children.length){for(const t of actions)if(row.classList.contains(t[0])){let e=row.id.substr(t[0].length+1);for(let n=0;n<row.children[2].children.length&&n<t[1].length;n++)row.children[2].children[n].addEventListener("click",function(){const o=new XMLHttpRequest;o.open("POST","/"+t[0]+"/"+e+"/"+t[1][n],!0),o.send()})}for(const t of multi_actions)if(row.classList.contains(t[0])){let e=row.id.substr(t[0].length+1);row.children[2].children[0].addEventListener("change",function(){const n=new XMLHttpRequest;n.open("POST","/"+t[0]+"/"+e+"/set?"+t[1]+"="+encodeURIComponent(this.value),!0),n.send()})}}

139
changelog/2022.10.0.rst Normal file
View File

@ -0,0 +1,139 @@
ESPHome 2022.10.0 - 19th October 2022
=====================================
.. seo::
:description: Changelog for ESPHome 2022.10.0.
:image: /_static/changelog-2022.10.0.png
:author: Jesse Hills
:author_twitter: @jesserockz
.. imgtable::
:columns: 2
BLE Client RSSI Sensor, components/sensor/ble_client, bluetooth.svg
ZHLT01 IR Climate, components/climate/climate_ir, air-conditioner-ir.svg
This month we have been busy upgrading the Bluetooth Proxy support for Home Assistant.
This meant there are many PRs awaiting reviews for new components that were unable to be
reviewed and merged in time. We will be trying to pack the next release.
Python Version 3.9
------------------
ESPHome now requires Python 3.9 or newer. This is taken care of if you use the Home Assistant addon
or docker image. If using pip, you will need to upgrade your Python version manually before ESPHome will
upgrade.
BLE Client Sensors
------------------
Due to adding a new RSSI sensor to the ``ble_client`` sensor platform, a new ``type`` configuration variable.
You will get a validation error when you try to install and you have not added a ``type`` to your
existing configurations.
XPT2046 Touchscreen
-------------------
The ``xpt2046`` touchscreen component has been updated to be a platform of ``touchscreen`` instead of a
top level component. This requires a small change to your configuration, see :doc:`/components/touchscreen/xpt2046`
for the new way to configure.
Release 2022.10.1 - October 26
------------------------------
- Update bluetooth proxy limit as soon as connection requested :esphomepr:`3935` by :ghuser:`jesserockz`
- Add water & precipitation_intensity sensor device classes :esphomepr:`3940` by :ghuser:`frenck`
- Fixed touch release issue using the interrupt pin :esphomepr:`3925` by :ghuser:`nielsnl68`
- Add wind_speed sensor device class :esphomepr:`3941` by :ghuser:`frenck`
Release 2022.10.2 - November 1
------------------------------
- Fix bluetooth_proxy not connecting :esphomepr:`3967` by :ghuser:`jesserockz`
Full list of changes
--------------------
Breaking Changes
^^^^^^^^^^^^^^^^
- Thermostat remove deprecated config :esphomepr:`3643` by :ghuser:`MrMDavidson` (breaking-change)
- Bump python min to 3.9 :esphomepr:`3871` by :ghuser:`jesserockz` (breaking-change)
- Refactor xpt2046 to be a touchscreen platform :esphomepr:`3793` by :ghuser:`nielsnl68` (breaking-change)
- Add ble RSSI sensor for connected devices :esphomepr:`3860` by :ghuser:`RoboMagus` (breaking-change)
Beta Changes
^^^^^^^^^^^^
- fix never calling preset change trigger :esphomepr:`3864` by :ghuser:`glmnet`
- Modbus QWORD fix :esphomepr:`3856` by :ghuser:`dudanov`
- Send true and not RSSI in ble_presence :esphomepr:`3904` by :ghuser:`fjouault`
- Remove address type map from bluetooth proxy :esphomepr:`3905` by :ghuser:`jesserockz`
All changes
^^^^^^^^^^^
- Update mcp23s17.cpp :esphomepr:`3797` by :ghuser:`pawel3410`
- Allow CORS for web_server :esphomepr:`3819` by :ghuser:`zhzhzhy`
- Dont fail fast on CI for docker :esphomepr:`3832` by :ghuser:`jesserockz`
- Thermostat remove deprecated config :esphomepr:`3643` by :ghuser:`MrMDavidson` (breaking-change)
- Add support for parsing the short local name in the tracker :esphomepr:`3854` by :ghuser:`bdraco`
- Add display GPIO setup instruction for Aliexpress display :esphomepr:`3851` by :ghuser:`kbx81`
- fix dump preset string type :esphomepr:`3863` by :ghuser:`glmnet`
- Bump CI to python 3.9 :esphomepr:`3869` by :ghuser:`jesserockz`
- Add cg.with_local_variable :esphomepr:`3577` by :ghuser:`jpeletier`
- Fix time/automation (cron) wdt crash when time jumps ahead too much :esphomepr:`3844` by :ghuser:`jpeletier`
- Bump pyupgrade from 2.37.3 to 3.0.0 :esphomepr:`3867` by :ghuser:`dependabot[bot]`
- Add min_version to esphome config :esphomepr:`3866` by :ghuser:`jesserockz`
- Bump python min to 3.9 :esphomepr:`3871` by :ghuser:`jesserockz` (breaking-change)
- Bump pylint from 2.15.2 to 2.15.3 :esphomepr:`3870` by :ghuser:`dependabot[bot]`
- Add new sensor device classes :esphomepr:`3895` by :ghuser:`jesserockz`
- Refactor xpt2046 to be a touchscreen platform :esphomepr:`3793` by :ghuser:`nielsnl68` (breaking-change)
- Proxy friendly host url resolution for `use_address` with path. :esphomepr:`3653` by :ghuser:`RoboMagus`
- Update webserver index file :esphomepr:`3896` by :ghuser:`jesserockz`
- Correctly set ble_write UUIDs based on their lengths. :esphomepr:`3885` by :ghuser:`RoboMagus`
- Fix default unit for ble_rssi sensor :esphomepr:`3874` by :ghuser:`RoboMagus`
- Exposing coordinates from touchscreen binary sensor :esphomepr:`3891` by :ghuser:`gpambrozio`
- Fix type annotation on `extract_registry_entry_config` :esphomepr:`3623` by :ghuser:`quentinmit`
- Add ble RSSI sensor for connected devices :esphomepr:`3860` by :ghuser:`RoboMagus` (breaking-change)
- Fix pulse_meter filter logic :esphomepr:`3321` by :ghuser:`cstaahl`
- Add support for ZHLT01 heatpump IR protocol :esphomepr:`3655` by :ghuser:`cfeenstra1024`
- Send GATT error events to HA :esphomepr:`3884` by :ghuser:`jesserockz`
- Do not require CS pin for ST7789V :esphomepr:`3888` by :ghuser:`definitio`
- fix never calling preset change trigger :esphomepr:`3864` by :ghuser:`glmnet`
- Modbus QWORD fix :esphomepr:`3856` by :ghuser:`dudanov`
- Send true and not RSSI in ble_presence :esphomepr:`3904` by :ghuser:`fjouault`
- Remove address type map from bluetooth proxy :esphomepr:`3905` by :ghuser:`jesserockz`
Past Changelogs
---------------
- :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`

261
changelog/2022.11.0.rst Normal file
View File

@ -0,0 +1,261 @@
ESPHome 2022.11.0 - 16th November 2022
======================================
.. seo::
:description: Changelog for ESPHome 2022.11.0.
:image: /_static/changelog-2022.11.0.png
:author: Jesse Hills
:author_twitter: @jesserockz
.. imgtable::
:columns: 4
RP2040, components/rp2040, rp2040.svg
WL-134 Pet Tag Sensor , components/text_sensor/wl_134, fingerprint.svg
Ethernet Info, components/text_sensor/ethernet_info, ethernet.svg
Atlas Scientific Peristaltic Pump, components/ezo_pmp, ezo-pmp.jpg
ADC128S102, components/sensor/adc128s102, adc128s102.png
Daikin BRC, components/climate/climate_ir, air-conditioner-ir.svg
Display Menu Core, components/display_menu/index, folder-open.svg
LCD Menu, components/display_menu/lcd_menu, lcd_menu.png
Raspberry Pi Pico-W
-------------------
What can I say... I (Jesse) started working on making ESPHome run on the original Raspberry Pi
Pico one random weekend just for fun with no real intention of taking it further myself.
Little did I know there would be a Raspberry Pi Pico-W released earlier this year which sparked
up interest in continuing that PR and almost fully implementing RP2040 and the Pico-W as
a supported platform in ESPHome.
There are things that have not been tested, and most likely things that will not work, so
please `create or search for an issue <https://github.com/esphome/issues/issues>`__ if this is the case.
Looking forward to seeing peoples projects built on these boards running ESPHome.
Script Parameters
-----------------
Thanks :ghuser:`jimtng` for taking the time to implement a feature requested by many people over time.
Parameters on scripts are now a thing.
.. code-block:: yaml
script:
- id: push_button
parameters:
button: int
then:
- logger.log:
format: "Button %d pressed"
args: [ button ]
on_...:
- script.execute:
id: push_button
button: 1
on_...:
- script.execute:
id: push_button
button: 2
LCD Menu
--------
Another great feature added this release is the LCD Menu. This allows a user to build a simple (or complex)
menu system on an lcd display within ESPHome YAML, with support for switches, numbers, selects etc.
Thanks :ghuser:`numo68`.
Preserving User WiFi Credentials
--------------------------------
If you purchase a device, or install ESPHome on a device that does not have Wi-Fi credentials pre-configured from YAML,
ESPHome will now preserve any credentials entered via the :doc:`/components/captive_portal`, :doc:`/components/improv_serial`
or :doc:`/components/esp32_improv` components after an OTA update of the firmeware is done. It is possible they can survive
flashing via serial, but only if the flash was not erased first, which it is in the case of using ESPHome to flash.
Products that use `ESP Web Tools <https://esphome.github.io/esp-web-tools>`__ are able to specify in the manifest that the flash
should not be erased when installing the firmware and this is a way to provide updates for a device that was sold.
Running ESPHome on lower powered machines
-----------------------------------------
People have noticed that trying to compile their projects on machine such as the Raspberry Pi 3 would crash either the whole machine
or the ESPHome add-on, or Home Assistant. This is due to having less RAM and CPU power available to run all of the things at the same time.
A new config option has been added as per the example below that should help to allow compiling on machines such as Raspberry Pi 3.
By default ESPHome tries to compile using all of the processor cores, and this allows you to limit it to a lower amount.
.. code-block:: yaml
esphome:
...
compile_process_limit: 1
Release 2022.11.1 - November 17
-------------------------------
- Support ADC on RP2040 :esphomepr:`4040` by :ghuser:`jesserockz`
Release 2022.11.2 - November 23
-------------------------------
- Fix rp2040 pwm to use pico-sdk, not mbed :esphomepr:`4059` by :ghuser:`jesserockz`
- Update web_server index :esphomepr:`4060` by :ghuser:`jesserockz`
- rp2040_pwm frequency is per pair of pins :esphomepr:`4061` by :ghuser:`jesserockz`
- Avoid 128bit uuid loop for 16/32 bit uuids :esphomepr:`4068` by :ghuser:`bdraco`
- Avoid creating a new espbt::ESPBTUUID each loop when registering for notify :esphomepr:`4069` by :ghuser:`bdraco`
Release 2022.11.3 - November 24
-------------------------------
- fix missing library :esphomepr:`4051` by :ghuser:`ssieb`
- Fix units for refresh: never :esphomepr:`4048` by :ghuser:`bkaufx`
- Don't convert climate temperature step :esphomepr:`4082` by :ghuser:`jesserockz`
Full list of changes
--------------------
New Features
^^^^^^^^^^^^
- Allow preserving WiFi credentials entered with captive_portal :esphomepr:`3813` by :ghuser:`kuba2k2` (new-feature)
New Components
^^^^^^^^^^^^^^
- Add support for wl-134 :esphomepr:`3569` by :ghuser:`hobbypunk90` (new-integration)
- New platform ethernet_info from component text_sensor :esphomepr:`3811` by :ghuser:`gtjadsonsantos` (new-integration)
- Implementation for Atlas Scientific Peristaltic Pump :esphomepr:`3528` by :ghuser:`carlos-sarmiento` (new-integration)
- Add adc128s102 sensor :esphomepr:`3822` by :ghuser:`DeerMaximum` (new-integration)
- Added component Daikin BRC to support ceiling cassette heatpumps :esphomepr:`3743` by :ghuser:`hagak` (new-integration)
- Initial Support for RP2040 platform :esphomepr:`3284` by :ghuser:`jesserockz` (new-integration)
- Implement a simple LCD menu :esphomepr:`3406` by :ghuser:`numo68` (new-integration)
Breaking Changes
^^^^^^^^^^^^^^^^
- Don't Use Base Network Manual IP for WiFi AP :esphomepr:`3902` by :ghuser:`bkaufx` (breaking-change)
Beta Changes
^^^^^^^^^^^^
- Update set-output to use new GITHUB_OUTPUT :esphomepr:`4008` by :ghuser:`jesserockz`
- Add cover toggle support to current based cover :esphomepr:`3950` by :ghuser:`maringeph`
- Add option for dashboard command to only generate the project and supporting files :esphomepr:`3981` by :ghuser:`jesserockz`
- Fix local webserver based on esphome/esphome-webserver#17 :esphomepr:`3958` by :ghuser:`RoboMagus`
- fix to_lower filter :esphomepr:`4015` by :ghuser:`ssieb`
- Mark webserver and captive portal as not available on rp2040 :esphomepr:`4023` by :ghuser:`jesserockz`
- Fix time components on rp2040 :esphomepr:`4024` by :ghuser:`jesserockz`
- Mark mqtt as unavailable on rp2040 :esphomepr:`4025` by :ghuser:`jesserockz`
- Update_interval less that 1 second in QMC5883L integration :esphomepr:`4031` by :ghuser:`2mikrobi`
- Always save user wifi credentials if non in config :esphomepr:`4036` by :ghuser:`jesserockz`
- bump nginx-light 1.18.0-6.1+deb11u2 to 1.18.0-6.1+deb11u3 :esphomepr:`4034` by :ghuser:`johnmoxley`
All changes
^^^^^^^^^^^
- Update the ibeacon code :esphomepr:`3859` by :ghuser:`fhriley`
- Don't Use Base Network Manual IP for WiFi AP :esphomepr:`3902` by :ghuser:`bkaufx` (breaking-change)
- Allow preserving WiFi credentials entered with captive_portal :esphomepr:`3813` by :ghuser:`kuba2k2` (new-feature)
- Add support for wl-134 :esphomepr:`3569` by :ghuser:`hobbypunk90` (new-integration)
- New platform ethernet_info from component text_sensor :esphomepr:`3811` by :ghuser:`gtjadsonsantos` (new-integration)
- Implementation for Atlas Scientific Peristaltic Pump :esphomepr:`3528` by :ghuser:`carlos-sarmiento` (new-integration)
- Add adc128s102 sensor :esphomepr:`3822` by :ghuser:`DeerMaximum` (new-integration)
- Added component Daikin BRC to support ceiling cassette heatpumps :esphomepr:`3743` by :ghuser:`hagak` (new-integration)
- Bump platformio from 6.0.2 to 6.1.4 :esphomepr:`3711` by :ghuser:`dependabot[bot]`
- Add API interface to request a complete device config as JSON. :esphomepr:`3911` by :ghuser:`RoboMagus`
- Initial Support for RP2040 platform :esphomepr:`3284` by :ghuser:`jesserockz` (new-integration)
- Bump esphome-dashboard to 20221020.0 :esphomepr:`3920` by :ghuser:`jesserockz`
- Fix missing dependencies for heatpumpir :esphomepr:`3933` by :ghuser:`jesserockz`
- Update the PR template :esphomepr:`3934` by :ghuser:`jesserockz`
- Fix error with require_framework_version and rp2040 :esphomepr:`3923` by :ghuser:`jesserockz`
- Make mDNS on rp2040 work :esphomepr:`3936` by :ghuser:`jesserockz`
- Send manufacturer name via API :esphomepr:`3938` by :ghuser:`jesserockz`
- Update base platformio board for rp2040 :esphomepr:`3937` by :ghuser:`jesserockz`
- Implement different random for rp2040 :esphomepr:`3939` by :ghuser:`jesserockz`
- add proper device class to uptime :esphomepr:`3928` by :ghuser:`nagyrobi`
- Show local mac when scanning wifi :esphomepr:`3635` by :ghuser:`cvwillegen`
- Prefix devcontainer image with ghcr.io :esphomepr:`3942` by :ghuser:`jesserockz`
- Implement InterruptLock for RP2040 :esphomepr:`3945` by :ghuser:`jesserockz`
- Implement RP2040 preferences :esphomepr:`3946` by :ghuser:`jesserockz`
- Fix filesystem size for RP2040 OTA :esphomepr:`3947` by :ghuser:`jesserockz`
- Bump esphome/Improv to 1.2.3 :esphomepr:`3948` by :ghuser:`jesserockz`
- Add core config option to limit compile process count :esphomepr:`3952` by :ghuser:`jesserockz`
- Some RP2040 wifi changes for AP mode :esphomepr:`3953` by :ghuser:`jesserockz`
- Update rp2040 to latest framework release from GitHub :esphomepr:`3954` by :ghuser:`jesserockz`
- [SM300D2] Reduce log severity for successful reads :esphomepr:`3955` by :ghuser:`pauln`
- Fix imports for rp2040 with no wifi :esphomepr:`3956` by :ghuser:`jesserockz`
- Allow using LED pin on rpi pico-w :esphomepr:`3957` by :ghuser:`jesserockz`
- Fix RP2040 SPISettings :esphomepr:`3960` by :ghuser:`jesserockz`
- Make some minor changes to I²C so rp2040 works :esphomepr:`3959` by :ghuser:`jesserockz`
- Bump tornado from 6.1 to 6.2 :esphomepr:`3620` by :ghuser:`dependabot[bot]`
- Bump pytest-cov from 3.0.0 to 4.0.0 :esphomepr:`3922` by :ghuser:`dependabot[bot]`
- Remove gitpod :esphomepr:`3964` by :ghuser:`balloob`
- Bump pyupgrade from 3.0.0 to 3.2.0 :esphomepr:`3973` by :ghuser:`dependabot[bot]`
- Bump pytest from 7.1.3 to 7.2.0 :esphomepr:`3966` by :ghuser:`dependabot[bot]`
- Bump actions/stale from 5 to 6 :esphomepr:`3841` by :ghuser:`dependabot[bot]`
- Bump pylint from 2.15.3 to 2.15.5 :esphomepr:`3978` by :ghuser:`dependabot[bot]`
- Bump pytest-mock from 3.8.2 to 3.10.0 :esphomepr:`3877` by :ghuser:`dependabot[bot]`
- Allow multiple bluetooth proxy connections :esphomepr:`3971` by :ghuser:`jesserockz`
- Always use gh releases in base platformio file for rp2040 :esphomepr:`3988` by :ghuser:`jesserockz`
- Allow the use of multiple RDM6300 devices :esphomepr:`3989` by :ghuser:`mbardeen`
- Bump aioesphomeapi from 10.13.0 to 11.4.2 :esphomepr:`3987` by :ghuser:`dependabot[bot]`
- rp2040: Set watchdog to reboot properly :esphomepr:`3991` by :ghuser:`jesserockz`
- RP2040 uart support :esphomepr:`3990` by :ghuser:`jesserockz`
- add uart number to LOGCONFIG :esphomepr:`3996` by :ghuser:`tomaszduda23`
- Implement a simple LCD menu :esphomepr:`3406` by :ghuser:`numo68` (new-integration)
- Lint updates :esphomepr:`3992` by :ghuser:`jesserockz`
- Bump zeroconf from 0.39.1 to 0.39.4 :esphomepr:`3979` by :ghuser:`dependabot[bot]`
- Bump black from 22.8.0 to 22.10.0 :esphomepr:`3986` by :ghuser:`dependabot[bot]`
- Skip validation of defined pins :esphomepr:`3999` by :ghuser:`jenscski`
- Bump pytest-asyncio from 0.19.0 to 0.20.1 :esphomepr:`4003` by :ghuser:`dependabot[bot]`
- Bump aioesphomeapi from 11.4.2 to 11.4.3 :esphomepr:`4002` by :ghuser:`dependabot[bot]`
- Bump platformio from 6.1.4 to 6.1.5 :esphomepr:`4004` by :ghuser:`dependabot[bot]`
- Enable calibration, callbacks and custom commands for EZO sensors :esphomepr:`3910` by :ghuser:`gvdhoven`
- Bump esphome-dashboard to 20221109.0 :esphomepr:`4006` by :ghuser:`jesserockz`
- Add support for parameters in scripts :esphomepr:`3538` by :ghuser:`jimtng`
- Update set-output to use new GITHUB_OUTPUT :esphomepr:`4008` by :ghuser:`jesserockz`
- Add cover toggle support to current based cover :esphomepr:`3950` by :ghuser:`maringeph`
- Add option for dashboard command to only generate the project and supporting files :esphomepr:`3981` by :ghuser:`jesserockz`
- Fix local webserver based on esphome/esphome-webserver#17 :esphomepr:`3958` by :ghuser:`RoboMagus`
- fix to_lower filter :esphomepr:`4015` by :ghuser:`ssieb`
- Mark webserver and captive portal as not available on rp2040 :esphomepr:`4023` by :ghuser:`jesserockz`
- Fix time components on rp2040 :esphomepr:`4024` by :ghuser:`jesserockz`
- Mark mqtt as unavailable on rp2040 :esphomepr:`4025` by :ghuser:`jesserockz`
- Update_interval less that 1 second in QMC5883L integration :esphomepr:`4031` by :ghuser:`2mikrobi`
- Always save user wifi credentials if non in config :esphomepr:`4036` by :ghuser:`jesserockz`
- bump nginx-light 1.18.0-6.1+deb11u2 to 1.18.0-6.1+deb11u3 :esphomepr:`4034` by :ghuser:`johnmoxley`
Past Changelogs
---------------
- :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/2022.9.0.html
:url: /changelog/2022.11.0.html
.. toctree::
:glob:

2
components.py
View File

@ -26,7 +26,7 @@ def add_component_details(app, pagename, templatename, context, doctree):
page_data = {
"title": context["title"],
"url": context["pageurl"],
"path": context["pagename"],
"path": f"components/{component_name}",
}
if os.path.exists(os.path.join(app.builder.srcdir, "images", component_name + ".png")):
page_data["image"] = app.builder.config.html_baseurl + "/_images/" + component_name + ".png"

53
components/bluetooth_proxy.rst
View File

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

2
components/button/index.rst
View File

@ -7,7 +7,7 @@ Button Component
.. note::
To attach a physical buttons to ESPHome, see
To attach a physical button to ESPHome, see
:doc:`GPIO Binary Sensor </components/binary_sensor/gpio>`.
ESPHome has support for components to create button entities in Home Assistant. A button entity is

3
components/captive_portal.rst
View File

@ -16,7 +16,7 @@ After 1 minute of unsuccessful WiFi connection attempts, the ESP will start a Wi
:width: 70.0%
In this web interface, you can manually override the WiFi settings of the device (please note
this will be overwritten by any subsequent upload, so make sure to also update your YAML configuration).
this will be overwritten by any subsequent upload so make sure to also update your YAML configuration).
Additionally, you can upload a new firmware file.
@ -38,6 +38,7 @@ manually in your browser.
No configuration variables.
See Also
--------

28
components/climate/climate_ir.rst
View File

@ -27,6 +27,8 @@ submit a feature request (see FAQ).
+---------------------------------------+---------------------+----------------------+
| Daikin | ``daikin`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`Daikin BRC<daikin_brc>` | ``daikin_brc`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`Delonghi<delonghi_ir>` | ``delonghi`` | yes |
+---------------------------------------+---------------------+----------------------+
| Fujitsu General | ``fujitsu_general`` | yes |
@ -102,7 +104,7 @@ This platform utilises the library's generic one-size-fits-all API, which might
Additional configuration must be specified for this platform:
- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyac``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba``
- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyac``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba``, ``zhlt01``
- **horizontal_default** (**Required**, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Options are: ``left``, ``mleft``, ``middle``, ``mright``, ``right``, ``auto``
- **vertical_default** (**Required**, string): What to default to when the AC unit's vertical direction is *not* set to swing. Options are: ``down``, ``mdown``, ``middle``, ``mup``, ``up``, ``auto``
- **max_temperature** (**Required**, float): The maximum temperature that the AC unit supports being set to.
@ -120,6 +122,8 @@ Additional configuration must be specified for this platform:
internal temperature sensor; a value of 2 minutes seems to work well. See :doc:`/components/sensor/index`
for more information.
- The ``zhlt01`` protocol supports multiple AC brands: Eurom, Chigo, Tristar, Tecnomaster, Elgin, Geant, Tekno, Topair, Proma, Sumikura, JBS, Turbo Air, Nakatomy, Celestial Air, Ager, Blueway, Airlux, etc.
.. _ir-receiver_id:
Using a Receiver
@ -209,6 +213,28 @@ Configuration variables:
header_high: 3265us # AC Units from LG in Brazil, for example use these timings
header_low: 9856us
.. _daikin_brc:
``daikin_brc`` Climate
-------------------------
The Daikin BRC remotes are used by the ceiling cassette model of Daikin heatpumps.
Configuration variables:
- **use_fahrenheit** (*Optional*, boolean): U.S. models of the Daikin BRC remote send the temperature in Fahrenheit, if your remote shows Fahrenheit and can not be changed to Celsius then set this to true. Defaults to ``false``.
.. code-block:: yaml
# Example configuration entry
climate:
- platform: daikin_brc
name: "AC"
sensor: room_temperature
use_fahrenheit: true
.. _delonghi_ir:
``delonghi`` Climate

77
components/climate/index.rst
View File

@ -7,7 +7,7 @@ Climate Component
ESPHome has support for climate devices. Climate devices can represent different types of
hardware, but the defining factor is that climate devices have a settable target temperature
and can be put in different modes like HEAT, COOL, HEAT_COOL or OFF.
and can be put in different modes like ``HEAT``, ``COOL``, ``HEAT_COOL`` or ``OFF``.
.. figure:: images/climate-ui.png
:align: center
@ -58,42 +58,6 @@ Advanced options:
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
MQTT options:
- **action_state_topic** (*Optional*, string): The topic to publish
climate device action changes to.
- **away_state_topic** (*Optional*, string): The topic to publish
away mode changes on.
- **away_command_topic** (*Optional*, string): The topic to receive
away mode commands on.
- **current_temperature_state_topic** (*Optional*, string): The topic to publish
current temperature 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
fan mode commands on.
- **mode_state_topic** (*Optional*, string): The topic to publish
climate device mode changes to.
- **mode_command_topic** (*Optional*, string): The topic to receive
climate device mode commands on.
- **swing_mode_state_topic** (*Optional*, string): The topic to publish
swing mode changes to.
- **swing_mode_command_topic** (*Optional*, string): The topic to receive
swing mode commands on.
- **target_temperature_state_topic** (*Optional*, string): The topic to publish
target temperature changes to.
- **target_temperature_command_topic** (*Optional*, string): The topic to receive
target temperature commands on.
- **target_temperature_high_state_topic** (*Optional*, string): The topic to publish
higher target temperature changes to.
- **target_temperature_high_command_topic** (*Optional*, string): The topic to receive
higher target temperature commands on.
- **target_temperature_low_state_topic** (*Optional*, string): The topic to publish
lower target temperature changes to.
- **target_temperature_low_command_topic** (*Optional*, string): The topic to receive
lower target temperature commands on.
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
Climate Automation
------------------
@ -189,7 +153,7 @@ advanced stuff.
.. _climate-on_state_trigger:
``climate.on_state`` Trigger
******************************************************
****************************
This trigger is activated each time the state of the climate device is updated
(for example, if the current temperature measurement or the mode set by the users changes).
@ -202,6 +166,43 @@ This trigger is activated each time the state of the climate device is updated
on_state:
- logger.log: "State updated!"
MQTT options:
- **action_state_topic** (*Optional*, string): The topic to publish
climate device action changes to.
- **away_state_topic** (*Optional*, string): The topic to publish
away mode changes on.
- **away_command_topic** (*Optional*, string): The topic to receive
away mode commands on.
- **current_temperature_state_topic** (*Optional*, string): The topic to publish
current temperature 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
fan mode commands on.
- **mode_state_topic** (*Optional*, string): The topic to publish
climate device mode changes to.
- **mode_command_topic** (*Optional*, string): The topic to receive
climate device mode commands on.
- **swing_mode_state_topic** (*Optional*, string): The topic to publish
swing mode changes to.
- **swing_mode_command_topic** (*Optional*, string): The topic to receive
swing mode commands on.
- **target_temperature_state_topic** (*Optional*, string): The topic to publish
target temperature changes to.
- **target_temperature_command_topic** (*Optional*, string): The topic to receive
target temperature commands on.
- **target_temperature_high_state_topic** (*Optional*, string): The topic to publish
higher target temperature changes to.
- **target_temperature_high_command_topic** (*Optional*, string): The topic to receive
higher target temperature commands on.
- **target_temperature_low_state_topic** (*Optional*, string): The topic to publish
lower target temperature changes to.
- **target_temperature_low_command_topic** (*Optional*, string): The topic to receive
lower target temperature commands on.
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
See Also
--------

159
components/climate/thermostat.rst
View File

@ -6,10 +6,10 @@ Thermostat Climate Controller
:image: air-conditioner.svg
The ``thermostat`` climate platform allows you to control a climate control system in much the same manner as a
physical thermostat. Its operation is similar to the :doc:`bang-bang <bang_bang>` controller; a sensor measures a value
physical thermostat. Its operation is similar to the :doc:`Bang-Bang <bang_bang>` controller; a sensor measures a value
(the air temperature) and the controller will try to keep this value within a range defined by the set point(s). To do this,
the controller can activate devices like a heating unit and/or a cooling unit to change the value observed by the sensor.
When configured for both heating and cooling, it is essentially two :doc:`bang-bang <bang_bang>` controllers in one; it
When configured for both heating and cooling, it is essentially two :doc:`Bang-Bang <bang_bang>` controllers in one; it
differs, however, in that interaction with the thermostat component is nearly identical to that of a real thermostat.
This component can operate in one of two ways:
@ -52,8 +52,6 @@ modes that Home Assistant offers.
- platform: thermostat
name: "Thermostat Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
default_target_temperature_high: 22 °C
min_cooling_off_time: 300s
min_cooling_run_time: 300s
min_heating_off_time: 300s
@ -66,6 +64,11 @@ modes that Home Assistant offers.
idle_action:
- switch.turn_off: air_cond
- switch.turn_off: heater
default_preset: Home
preset:
- name: Home
default_target_temperature_low: 20 °C
default_target_temperature_high: 22 °C
.. code-block:: yaml
@ -74,7 +77,6 @@ modes that Home Assistant offers.
- platform: thermostat
name: "Thermostat Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
min_heating_off_time: 300s
min_heating_run_time: 300s
min_idle_time: 30s
@ -82,6 +84,11 @@ modes that Home Assistant offers.
- switch.turn_on: heater
idle_action:
- switch.turn_off: heater
default_preset: Home
preset:
- name: Home
default_target_temperature_low: 20 °C
.. code-block:: yaml
@ -90,7 +97,6 @@ modes that Home Assistant offers.
- platform: thermostat
name: "Thermostat Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_high: 22 °C
min_cooling_off_time: 300s
min_cooling_run_time: 300s
min_idle_time: 30s
@ -98,6 +104,11 @@ modes that Home Assistant offers.
- switch.turn_on: air_cond
idle_action:
- switch.turn_off: air_cond
default_preset: Home
preset:
- name: Home
default_target_temperature_high: 22 °C
Controller Behavior and Hysteresis
@ -158,45 +169,6 @@ The thermostat controller uses the sensor to determine whether it should heat or
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
Default Target Temperatures and Mode
************************************
These configuration items determine default values the thermostat controller should use when it starts.
- **default_mode** (*Optional*, *Deprecated*, climate mode): The default climate mode the controller should
use if it is unable to restore it from memory. One of:
- ``off`` (default)
- ``heat_cool``
- ``cool``
- ``heat``
- ``dry``
- ``fan_only``
- ``auto``
This value is used the first time your device starts after ESPHome is initially installed onto it. Add
this option into your configuration if you want your thermostat component to start in a climate mode other
than ``off``. If this option is not configured, you'll need to manually change the climate mode later via
the front end (Home Assistant), an ESPHome action, automation, or from within a lambda elsewhere in your
device's configuration.
- **default_target_temperature_low** (*Optional*, float): The default low target
temperature for the control algorithm. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (*Optional*, float): The default high target
temperature for the control algorithm. This can be dynamically set in the frontend later.
**At least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
**must be specified.**
.. note::
**default_mode**, **default_target_temperature_low**, and **default_target_temperature_high** are
being removed in a future release. In the future you will need to migrate your configuration to using
a :ref:`preset <thermostat-preset>` which will allow for more flexibility and customisation
Note that ``min_temperature`` and ``max_temperature`` from the base climate component are used to define
the range of allowed temperature values in the thermostat component. See :doc:`/components/climate/index`.
Heating and Cooling Actions
***************************
@ -315,22 +287,6 @@ Set Point Options/Behavior
- **supplemental_heating_delta** (*Required with* ``supplemental_heating_action``, float): When the temperature
difference between the lower set point and the current temperature exceeds this value,
``supplemental_heating_action`` will be called immediately.
- **away_config** (*Optional*, *Deprecated*): Additionally specify target temperature range settings for away mode.
Away mode can be used to have a second set of target temperatures (for example, while the user is
away or sleeping/at night).
- **default_target_temperature_low** (*Optional*, float): The default low target temperature for the control
algorithm when Away mode is selected. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (*Optional*, float): The default high target temperature for the control
algorithm when Away mode is selected. This can be dynamically set in the frontend later.
**If configured, at least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
**must be specified in the away mode configuration.**
.. note::
**away_config** is deprecated and will be removed in a future release. You should migrate your configuration
to using a :ref:`preset <thermostat-preset>` which allows for more flexibility and customisation
.. _thermostat-preset:
@ -343,19 +299,19 @@ experience and automation.
- **preset**: (*Optional*, list)
- **name** (*Required*, string): Name of the preset. If this is one of the *standard* presets (``eco``, ``away``,
- **name** (*Required*, string): Name of the preset. If this is one of the *standard* presets (``eco``, ``away``,
``boost``, ``comfort``, ``home``, ``sleep``, or ``activity``) it is considered a *standard* preset. Any other
string will make the preset a *custom* preset. *Standard* and *custom* presets are functionally equivalent,
the only difference is that when switching the mode via :ref:`climate.control Action <climate-control_action>`
you will need to use the `preset` or `custom_preset` property as appropriate. The Home Assistant
you will need to use the `preset` or `custom_preset` property as appropriate. The Home Assistant
`climate.set_preset_mode` service treats them identically
- **default_target_temperature_low** (*Optional*, float): The default low target temperature when switching to
- **default_target_temperature_low** (*Optional*, float): The default low target temperature when switching to
this preset
- **default_target_temperature_high** (*Optional*, float): The default high target temperature when switching
to this preset.
- **mode** (*Optional*, climate mode): The mode the thermostat should switch to when this preset is activated.
If not specified, the thermostat's mode will remain unchanged when the preset is activated. One of:
- ``heat_cool``
- ``cool``
- ``heat``
@ -378,7 +334,7 @@ experience and automation.
- **swing_mode** (*Optional*, climate swing mode): The fan swing mode the thermostat should switch to when this
preset is activated. If not specified, the thermostat's fan swing mode will remain unchanged when the preset
is activated. One of:
- ``off``
- ``both``
- ``horizontal``
@ -422,6 +378,67 @@ experience and automation.
preset_change:
- logger.log: Preset has been changed!
Default Preset
**************
These configuration items determine default values the thermostat controller should use when it starts.
- **default_preset** (*Optional*, string): The name of the preset to use by default. Must match a preset
as per :ref:`preset <thermostat-preset>`.
- **on_boot_restore_from**: (*Optional*, on_boot_restore_from): Controls what the thermostat will do when
it first boots. One of:
- ``memory`` (default): The thermostat will restore any settings from last time it was running.
- ``default_preset``: The thermostat will always switch to the preset specified by **default_preset**
.. note::
You can specify a ``default_preset`` and set ``on_boot_restore_from`` to ``memory``. In this mode when
the settings from last boot cannot be retrieved, for any reason, then the specified ``default_preset``
will be applied.
.. code-block:: yaml
# This climate controller, on first boot, will switch to "My Startup Preset". Subsequent boots would
# restore to whatever mode it was in prior to the reboot
climate:
- platform: thermostat
name: "From Memory Thermostat"
default_preset: My Startup Preset
on_boot_restore_from: memory
preset:
- name: My Startup Preset
default_target_temperature_low: 17
default_target_temperature_high: 26
fan_mode: OFF
swing_mode: OFF
mode: OFF
# Custom preset
- name: A custom preset
default_target_temperature_low: 21
default_target_temperature_high: 23
fan_mode: HIGH
mode: HEAT_COOL
# This climate controller will always switch to "Every Start Preset"
climate:
- platform: thermostat
name: "Default Preset Thermostat"
default_preset: Every Start Preset
on_boot_restore_from: default_preset
preset:
- name: Every Start Preset
default_target_temperature_low: 17
default_target_temperature_high: 26
fan_mode: OFF
swing_mode: OFF
mode: OFF
# Custom preset
- name: A custom preset
default_target_temperature_low: 21
default_target_temperature_high: 23
fan_mode: HIGH
mode: HEAT_COOL
Additional Actions/Behavior
***************************
@ -471,6 +488,9 @@ Additional Actions/Behavior
- **min_fan_mode_switching_time** (*Required with any* ``fan_mode`` *action*, :ref:`config-time`): Minimum duration
any given fan mode must be active before it may be changed.
Note that ``min_temperature`` and ``max_temperature`` from the base climate component are used to define
the range of allowed temperature values in the thermostat component. See :doc:`/components/climate/index`.
Hysteresis Values
*****************
@ -487,19 +507,20 @@ Hysteresis Values
- While this platform uses the term temperature everywhere, it can also be used to regulate other values.
For example, controlling humidity is also possible with this platform.
- ``min_temperature`` and ``max_temperature`` from the base climate component are used the define the range of
- ``min_temperature`` and ``max_temperature`` from the base climate component are used the define the range of
adjustability and the defaults will probably not make sense for control of things like humidity. See
:doc:`/components/climate/index`.
Bang-bang vs. Thermostat
Bang-Bang vs. Thermostat
------------------------
Please see the :doc:`Bang-bang <bang_bang>` component's documentation for a detailed comparison of these two components.
Please see the :doc:`Bang-Bang <bang_bang>` component's documentation for a detailed comparison of these two components.
See Also
--------
- :doc:`/components/climate/index`
- :doc:`/components/sensor/index`
- :doc:`Bang-Bang <bang_bang>`
- :ref:`config-action`
- :ghedit:`Edit`

2
components/debug.rst
View File

@ -7,7 +7,7 @@ Debug Component
The ``debug`` component can be used to debug problems with ESPHome. At startup, it prints
a bunch of useful information like reset reason, free heap size, ESPHome version and so on.
It also allows you get the same information as a text sensor, and to monitor the state of the
It also allows you to get the same information as a text sensor, and to monitor the state of the
ESP heap memory (free space, maximum free block size and fragmentation level) and the main-loop timing.
.. figure:: images/debug.png

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

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

After

Width:  |  Height:  |  Size: 334 KiB

189
components/display/lcd_display.rst
View File

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

2
components/display/st7789v.rst
View File

@ -63,7 +63,7 @@ Configuration variables:
- ``Adafruit RR 280x240`` (round-rectangular display -- some pixels are "deleted" from corners to form rounded shape)
- ``Custom`` (see details below)
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **reset_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **height** (*Optional*, int): When ``model`` is set to "Custom", use this to specify the ``height`` of the display

BIN
components/display_menu/images/lcd_menu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.0 KiB

761
components/display_menu/index.rst Normal file
View File

@ -0,0 +1,761 @@
Display Menu
============
.. seo::
:description: Instructions for setting up a simple hierarchical menu on displays.
:image: lcd_menu.png
.. _display_menu:
The integration provides a menu primarily intended to be controlled either by a rotary encoder
with a button or a five-button joystick controller. It allows to navigate a hierarchy of items
and submenus with the ability to change the values and execute commands. The menu can
be activated and deactivated on demand, allowing alternating between using the screen for
the menu and other information.
Overview
--------
This document describes the configuration and automations common for the components implementing
this integration. At the moment the character based LCD displays are supported using
the :ref:`lcd_menu <lcd_menu>` integration and an instance of this is used in the configuration
examples.
.. code-block:: yaml
# Example configuration entry
display:
- platform: lcd_pcf8574
id: my_lcd
...
lambda: |-
id(my_lcd_menu).draw();
if (!id(my_lcd_menu).is_active())
it.print("Menu is not active");
# Declare a LCD menu
lcd_menu:
id: my_lcd_menu
display_id: my_lcd
active: true
mode: rotary
on_enter:
then:
lambda: 'ESP_LOGI("display_menu", "root enter");'
on_leave:
then:
lambda: 'ESP_LOGI("display_menu", "root leave");'
items:
- type: back
text: 'Back'
- type: label
text: 'Label 1'
- type: label
text: !lambda |-
return "Templated label";
# Encoder to provide navigation
sensor:
- platform: rotary_encoder
...
on_anticlockwise:
- display_menu.up:
on_clockwise:
- display_menu.down:
# A de-bounced GPIO is used to 'click'
binary_sensor:
- platform: gpio
...
filters:
- delayed_on: 10ms
- delayed_off: 10ms
on_press:
- display_menu.enter:
Configuration variables:
- **root_item_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the root menu item.
- **active** (*Optional*, boolean): Whether the menu should start as active, meaning accepting
user interactions and displaying output. Defaults to ``true``.
- **mode** (*Optional*, string): Defines the navigation logic. The ``rotary`` mode expects
the clockwise movement wired to :ref:`display_menu.down <display_menu-down_action>`,
the anticlockwise one to :ref:`display_menu.up <display_menu-up_action>` and the switch
to :ref:`display_menu.enter <display_menu-enter_action>` action. The ``joystick`` mode
expects the up, down, left and right buttons wired to the :ref:`display_menu.up <display_menu-up_action>`,
:ref:`display_menu.down <display_menu-down_action>`, :ref:`display_menu.left <display_menu-left_action>`
and :ref:`display_menu.right <display_menu-right_action>` actions and the middle button
to the :ref:`display_menu.enter <display_menu-enter_action>` action. Defaults to ``rotary``.
- **menu** (**Required**): The first level of the menu.
Automations:
- **on_enter** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the menu level (here the root one) is entered. See :ref:`display_menu-on_enter`.
- **on_leave** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the menu level is not displayed anymore.
See :ref:`display_menu-on_leave`.
Menu Items
----------
The component manages a hierarchy of menu items. The common configuration variables are:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **type** (**Required**, string): The type of the menu item (see below).
- **text** (*Optional*, string, :ref:`templatable <config-templatable>`): The text displayed
for the menu item. If a lambda is specified it gets an ``it`` argument pointing to
the ``MenuItem`` that is being drawn.
.. _display_menu-edit_mode:
Editing values
**************
Some of the menu items provide a way to edit values either by selecting from a list of options
or changing a numeric one. Such items can be configured in two ways.
If the ``immediate_edit`` configuration is ``false``, the editing mode has to be activated
first by activating the rotary encoder's switch or the joystick's center button.
On the activation the ``on_enter`` automation is called and the item is marked as editable
(the ``>`` selection marker changes to ``*`` as default). The value can be then
iterated through the rotary wheel (in the ``rotary`` mode) or the joystick left
and right buttons (in the ``joystick`` one). The editing mode is deactivated
by another clicking of the switch, the ``on_leave`` automation is called and the selection
marker changes back.
If the ``immediate_edit`` configuration is ``true`` the menu item is editable immediately
when it is selected. The ``on_enter`` and ``on_leave`` are not called. In the ``joystick`` mode
the left and right buttons iterate through the values; the items that are editable
show the editable marker to signal that the buttons can be used. In the ``rotary`` mode
activating the switch iterates to the next value. The selection marker does not change
(here it is used to signal whether rotating the knob navigates the menu or changes the value).
The menu item of the ``number`` type can be only immediately editable in the ``joystick`` mode.
Label
*****
.. code-block:: yaml
items:
- id: my_label
type: label
text: 'My Label'
The menu item of the type ``label`` just displays a text. There is no configuration and
no interaction is possible.
Menu
****
.. code-block:: yaml
items:
- type: menu
text: 'My Submenu'
on_enter:
then:
lambda: 'ESP_LOGI("display_menu", "enter: %s", it->get_text().c_str());'
on_leave:
then:
lambda: 'ESP_LOGI("display_menu", "leave: %s", it->get_text().c_str());'
items:
- type: label
text: 'Label'
- type: back
text: 'Back'
The menu item of the type ``menu`` defines a list of child menu items. When the item
is clicked the display shows the new menu level.
Configuration variables:
- **menu** (**Required**): Defines the child menu items.
Automations:
- **on_enter** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the menu level is entered. See :ref:`display_menu-on_enter`.
- **on_leave** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the menu level is not displayed anymore.
See :ref:`display_menu-on_leave`.
Back
****
.. code-block:: yaml
items:
- type: back
text: 'Back'
The menu item of the type ``back`` closes the current menu level and goes up in
the menu level hierarchy. The ``on_leave`` automation of the current level and
``on_enter`` one of the higher one are invoked. There is no configuration.
Select
******
.. code-block:: yaml
lcd_menu:
items:
- type: select
immediate_edit: false
text: 'My Color'
select: my_color
on_enter:
then:
lambda: 'ESP_LOGI("display_menu", "select enter: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
on_leave:
then:
lambda: 'ESP_LOGI("display_menu", "select leave: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
on_value:
then:
lambda: 'ESP_LOGI("display_menu", "select value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
select:
- platform: template
id: my_color
optimistic: true
options:
- 'Red'
- 'Green'
- 'Blue'
The menu item of the type ``select`` allows cycling through a set of values defined by the
associated ``select`` component.
Configuration variables:
- **immediate_edit** (*Optional*, boolean): Whether the item can be immediately edited when
selected. See :ref:`Editing Values <display_menu-edit_mode>`. Defaults to ``false``.
- **select** (**Required**, :ref:`config-id`): A ``select`` component managing
the edited value.
- **value_lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda returning a string to be displayed as value. The lambda gets an ``it`` argument
pointing to the ``MenuItem``. If not specified the selected option name of the ``select``
component is used as the value.
Automations:
- **on_enter** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is activated. See :ref:`display_menu-on_enter`.
- **on_leave** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is exited.
See :ref:`display_menu-on_leave`.
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the value is changed.
See :ref:`display_menu-on_value`.
Number
******
.. code-block:: yaml
lcd_menu:
items:
- type: number
text: 'My Number'
format: '%.2f'
number: my_number
on_enter:
then:
lambda: 'ESP_LOGI("display_menu", "number enter: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
on_leave:
then:
lambda: 'ESP_LOGI("display_menu", "number leave: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
on_value:
then:
lambda: 'ESP_LOGI("display_menu", "number value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
number:
- platform: template
id: my_number
optimistic: true
min_value: 10.0
max_value: 20.0
step: 0.5
on_value:
then:
lambda: 'ESP_LOGI("number", "value: %f", x);'
The menu item of the type ``number`` allows editing a floating point number.
On click the ``on_enter`` automation is called and the item is marked as editable
(the ``>`` selection marker changes to ``*`` as default). Up and down events
then increase and decrease the value by steps defined in the ``number``,
respecting the ``min_value`` and ``max_value``. The editing mode is exited
by another click.
Note that the fractional floating point values do not necessarily add nicely and
ten times ``0.100000`` is not necessarily ``1.000000``. Use steps that are
powers of two (such as ``0.125``) or take care of the rounding explicitly.
Configuration variables:
- **immediate_edit** (*Optional*, boolean): Whether the item can be immediately edited when
selected. See :ref:`Editing Values <display_menu-edit_mode>`. Ignored in the ``rotary`` mode.
Defaults to ``false``.
- **number** (**Required**, :ref:`config-id`): A ``number`` component managing
the edited value. If on entering the value is less than ``min_value`` or more than
``max_value``, the value is capped to fall into the range.
- **format** (*Optional*, string): A ``printf``-like format string specifying
exactly one ``f`` or ``g``-type conversion used to display the current value.
Defaults to ``%.1f``.
- **value_lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda returning a string to be displayed as value. The lambda gets an ``it`` argument
pointing to the ``MenuItem``. If not specified the value of the ``number`` component
formatted according to the ``format`` is used as the value.
Automations:
- **on_enter** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is activated. See :ref:`display_menu-on_enter`.
- **on_leave** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is exited.
See :ref:`display_menu-on_leave`.
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the value is changed.
See :ref:`display_menu-on_value`.
Switch
******
.. code-block:: yaml
lcd_menu:
items:
- type: switch
immediate_edit: false
text: 'My Switch'
on_text: 'Bright'
off_text: 'Dark'
switch: my_switch
on_enter:
then:
lambda: 'ESP_LOGI("display_menu", "switch enter: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
on_leave:
then:
lambda: 'ESP_LOGI("display_menu", "switch leave: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
on_value:
then:
lambda: 'ESP_LOGI("display_menu", "switch value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
switch:
- platform: template
id: my_switch
optimistic: true
The menu item of the type ``switch`` allows toggling the associated ``switch`` component.
Configuration variables:
- **immediate_edit** (*Optional*, boolean): Whether the item can be immediately edited when
selected. See :ref:`Editing Values <display_menu-edit_mode>`. Defaults to ``false``.
- **on_text** (*Optional*, string): The text for the ``ON`` state. Defaults to ``On``.
- **off_text** (*Optional*, string): The text for the ``OFF`` state. Defaults to ``Off``.
- **switch** (**Required**, :ref:`config-id`): A ``switch`` component managing
the edited value.
- **value_lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda returning a string to be displayed as value. The lambda gets an ``it`` argument
pointing to the ``MenuItem``. If not specified the ``on_text`` / ``off_text`` is used.
Automations:
- **on_enter** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is activated. See :ref:`display_menu-on_enter`.
- **on_leave** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is exited.
See :ref:`display_menu-on_leave`.
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the value is changed.
See :ref:`display_menu-on_value`.
Command
*******
.. code-block:: yaml
items:
- type: command
text: 'Hide'
on_value:
then:
- display_menu.hide:
The menu item of the type ``command`` allows triggering commands. There is no
additional configuration.
Automations:
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the menu item is clicked.
See :ref:`display_menu-on_value`.
Custom
******
.. code-block:: yaml
lcd_menu:
items:
- type: custom
immediate_edit: false
text: 'My Custom'
value_lambda: 'return to_string(some_state);'
on_next:
then:
lambda: 'some_state++;'
on_prev:
then:
lambda: 'some_state--;'
The menu item of the type ``custom`` delegates navigating the values to the automations
and displaying the value to the ``value_lambda``.
Configuration variables:
- **immediate_edit** (*Optional*, boolean): Whether the item can be immediately edited when
selected. See :ref:`Editing Values <display_menu-edit_mode>`. Defaults to ``false``.
- **value_lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda returning a string to be displayed as value. The lambda gets an ``it`` argument
pointing to the ``MenuItem``.
Automations:
- **on_enter** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is activated. See :ref:`display_menu-on_enter`.
- **on_leave** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the editing mode is exited.
See :ref:`display_menu-on_leave`.
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the value is changed.
See :ref:`display_menu-on_value`.
- **on_next** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the user navigates to the next value.
See :ref:`display_menu-on_next`.
- **on_prev** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the user navigates to the previous value.
See :ref:`display_menu-on_prev`.
Automations
-----------
.. _display_menu-on_enter:
``on_enter``
************
This automation will be triggered when the menu level is entered, i.e. the component
draws its items on the display. The ``it`` parameter points to a ``MenuItem`` class
with the information of the menu item describing the displayed child items.
If present at the top level it is an internally generated root menu item,
otherwise an user defined one.
.. code-block:: yaml
lcd_menu:
...
items:
- type: menu
text: 'Submenu 1'
on_enter:
then:
lambda: 'ESP_LOGI("display_menu", "enter: %s", it->get_text().c_str());'
.. _display_menu-on_leave:
``on_leave``
************
This automation will be triggered when the menu level is exited, i.e. the component
does not draw its items on the display anymore. The ``it`` parameter points to
a ``MenuItem`` class with the information of the menu item. If present at the
top level it is an internally generated root menu item, otherwise
an user defined one. It does not matter whether the level was left due to entering
the submenu or going back to the parent menu.
.. code-block:: yaml
lcd_menu:
...
items:
- type: menu
text: 'Submenu 1'
on_leave:
then:
lambda: 'ESP_LOGI("display_menu", "leave: %s", it->get_text().c_str());'
.. _display_menu-on_value:
``on_value``
************
This automation will be triggered when the value edited through the menu changed
or a command was triggered.
.. code-block:: yaml
lcd_menu:
...
items:
- type: select
text: 'Select Item'
select: my_select_1
on_value:
then:
lambda: 'ESP_LOGI("display_menu", "select value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
.. _display_menu-on_next:
``on_next``
***********
This automation will be triggered when the user requested to set the value to the next one.
.. code-block:: yaml
lcd_menu:
...
items:
- type: custom
text: 'Custom Item'
value_lambda: 'return to_string(some_state);'
on_next:
then:
lambda: 'some_state++;'
.. _display_menu-on_prev:
``on_prev``
***********
This automation will be triggered when the user requested to set the value to the previous one.
.. code-block:: yaml
lcd_menu:
...
items:
- type: custom
text: 'Custom Item'
value_lambda: 'return to_string(some_state);'
on_prev:
then:
lambda: 'some_state--;'
.. _display_menu-up_action:
``display_menu.up`` Action
**************************
This is an :ref:`Action <config-action>` for navigating up in a menu. The action
is usually wired to an anticlockwise turn of a rotary encoder or to the upper
button of the joystick.
.. code-block:: yaml
sensor:
- platform: rotary_encoder
...
on_anticlockwise:
- display_menu.up:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to navigate.
.. _display_menu-down_action:
``display_menu.down`` Action
****************************
This is an :ref:`Action <config-action>` for navigating down in a menu. The action
is usually wired to a clockwise turn of a rotary encoder or to the lower
button of the joystick.
.. code-block:: yaml
sensor:
- platform: rotary_encoder
...
on_clockwise:
- display_menu.down:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to navigate.
.. _display_menu-left_action:
``display_menu.left`` Action
****************************
This is an :ref:`Action <config-action>` usually wired to the left button
of the joystick. In the ``joystick`` mode it is used to set the previous
value or to decrement the numeric one; depending on the ``immediate_edit``
flag entering the edit mode is required or not. If used in the ``rotary``
mode it exits the editing. In both modes it can be also used to navigate
back one level when used with the ``back`` menu item.
.. code-block:: yaml
binary_sensor:
- platform: gpio
...
on_press:
- display_menu.left:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to navigate.
.. _display_menu-right_action:
``display_menu.right`` Action
*****************************
This is an :ref:`Action <config-action>` usually wired to the right button
of the joystick. In the ``joystick`` mode it is used to set the next
value or to increment the numeric one; depending on the ``immediate_edit``
flag entering the edit mode is required or not. In both modes it can
be also used to enter the submenu when used with the ``menu`` menu item.
.. code-block:: yaml
binary_sensor:
- platform: gpio
...
on_press:
- display_menu.right:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to navigate.
.. _display_menu-enter_action:
``display_menu.enter`` Action
*****************************
This is an :ref:`Action <config-action>` for triggering a selected menu item, resulting
in an action depending on the type of the item - entering a submenu, starting/stopping
editing or triggering a command. The action is usually wired to a press button
of a rotary encoder or to the center button of the joystick.
.. code-block:: yaml
binary_sensor:
- platform: gpio
...
filters:
- delayed_on: 10ms
- delayed_off: 10ms
on_press:
- display_menu.enter:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to navigate.
.. display_menu-show_action:
``display_menu.show`` Action
****************************
This is an :ref:`Action <config-action>` for showing an inactive menu. The state
of the menu remains unchanged, i.e. the menu level shown at the moment it was hidden
is restored, as is the selected item. The following snippet shows the menu if it is
inactive, otherwise triggers the selected item.
.. code-block:: yaml
on_press:
- if:
condition:
display_menu.is_active:
then:
- display_menu.enter:
else:
- display_menu.show:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to show.
.. display_menu-hide_action:
``display_menu.hide`` Action
****************************
This is an :ref:`Action <config-action>` for hiding the menu. A hidden menu
does not react to ``draw()`` and does not process navigation actions.
.. code-block:: yaml
lcd_menu:
...
items:
- type: command
text: 'Hide'
on_value:
then:
- display_menu.hide:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to hide.
.. display_menu-show_main_action:
``display_menu.show_main`` Action
*********************************
This is an :ref:`Action <config-action>` for showing the root level of the menu.
.. code-block:: yaml
lcd_menu:
...
items:
- type: command
text: 'Show Main'
on_value:
then:
- display_menu.show_main:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The ID of the menu to hide.
.. _display_menu-is_active:
``display_menu.is_active`` Condition
************************************
This :ref:`Condition <config-condition>` checks if the given menu is active, i.e.
shown on the display and processing navigation events.
.. code-block:: yaml
on_press:
- if:
condition:
display_menu.is_active:
...
See Also
--------
- :apiref:`display_menu_base/display_menu_base.h`
.. toctree::
:maxdepth: 1
:glob:
*
- :ghedit:`Edit`

117
components/display_menu/lcd_menu.rst Normal file
View File

@ -0,0 +1,117 @@
.. _lcd_menu:
LCD 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 character based LCD displays. This offers the user an interactive method to display
labels, control entities like ``switch``, ``select``, ``number`` available locally on the
ESPHome node, without the requirement of a network connection.
.. figure:: images/lcd_menu.png
:align: center
:width: 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 character based LCD display, which
like :ref:`lcd-pcf8574` or :ref:`lcd-gpio`. For the best results the GPIO connection is
recommended; the I²C one running at the speed according to the datasheet (usually ``100``
kHz) or even ESPHome default (``50`` kHz) will create perceptible delays especially when
changing a numeric value using the rotary encoder. Most ``PCF8574`` adapters used with
these displays will happily run at ``200`` or even ``400`` kHz though so if you are comfortable
accepting risks from running your hardware out of spec, you might want to try that
in your :ref:`i2c` configuration.
.. code-block:: yaml
# Example configuration entry
display:
- platform: lcd_pcf8574
id: my_lcd
dimensions: 20x4
...
user_characters:
- position: 0
data: # mark_back symbol
- 0b00100
- 0b01000
- 0b11110
- 0b01001
- 0b00101
- 0b00001
- 0b11110
- 0b00000
lambda: |-
id(my_lcd_menu).draw();
if (!id(my_lcd_menu).is_active())
it.print("Menu is not active");
# Declare a LCD menu
lcd_menu:
id: my_lcd_menu
display_id: my_lcd
active: true
mode: rotary
mark_back: 0x08
mark_selected: 0x3e
mark_editing: 0x2a
mark_submenu: 0x7e
items:
...
# Rotary encoder to provide navigation
sensor:
- platform: rotary_encoder
...
filters:
debounce: 30ms
on_anticlockwise:
- display_menu.up:
on_clockwise:
- display_menu.down:
# A debounced GPIO push button is used to 'click'
binary_sensor:
- platform: gpio
...
filters:
- delayed_on: 30ms
- delayed_off: 30ms
on_press:
- display_menu.enter:
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **display_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the LCD display.
- **mark_back**, **mark_selected**, **mark_editing**, **mark_submenu** (*Optional*, 0-255):
Code of the character used to mark menu items going back one level, a selected one,
the editing mode and item leading to a submenu. Defaults to ``0x5e`` (``^``), ``0x3e`` (``>``),
``0x2a`` (``*``) and ``0x7e`` (a right arrow). As the character set lacks a good looking
back arrow, using a user defined character is advisable for ``mark_back`` (use ``8`` to
reference one at position ``0`` to avoid problems with zeros in a string).
The rest of the configuration is described in the :ref:`Display Menu <display_menu>` component.
The menu inherits the dimensions of the connected LCD display and uses the entire area.
See Also
--------
- :ref:`i2c`
- :ref:`lcd-pcf8574`
- :ref:`lcd-gpio`
- :ref:`Display Menu <display_menu>`
- :doc:`/components/sensor/rotary_encoder`
- :doc:`/components/binary_sensor/index`
- :apiref:`lcd_menu/lcd_menu.h`
- :ghedit:`Edit`

30
components/esp32.rst
View File

@ -27,8 +27,38 @@ Configuration variables:
``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.
.. _esp32-arduino_framework:
GPIO Pin Numbering
------------------
The ESP32 boards often use the internal GPIO pin numbering on the board, this means that
you don't have to worry about other kinds of pin numberings, yay!
Some notes about the pins on the ESP32:
- ``GPIO0`` is used to determine the boot mode on startup. It should therefore not be pulled LOW
on startup to avoid booting into flash mode. You can, however, still use this as an output pin.
- ``GPIO34``-``GPIO39`` can not be used as outputs (even though GPIO stands for "general purpose input
**output**"...).
- ``GPIO32``-``GPIO39``: These pins can be used with the :doc:`/components/sensor/adc` to measure
voltages.
- ``GPIO2``: This pin is connected to the blue LED on the board. It also supports
the :doc:`touch pad binary sensor </components/binary_sensor/esp32_touch>` like some other
pins.
.. code-block:: yaml
# Example configuration entry
binary_sensor:
- platform: gpio
name: "Pin GPIO23"
pin: GPIO23
Arduino framework
-----------------

12
components/esp32_ble_beacon.rst
View File

@ -32,6 +32,18 @@ Advanced options:
the BLE receiver doesn't use it. Defaults to ``10167``.
- **minor** (*Optional*, int): The iBeacon minor identifier of this beacon. Usually used to
identify beacons within an iBeacon group. Defaults to ``61958``.
- **min_interval** (*Optional*, :ref:`config-time`): The iBeacon minimum transmit interval in milliseconds from 20 to 10240.
Setting this less than ``max_interval`` gives the BLE hardware a better chance to avoid
collisions with other BLE transmissions. Defaults to the iBeacon specification's defined interval: ``100ms``.
- **max_interval** (*Optional*, :ref:`config-time`): The iBeacon maximum transmit interval in milliseconds from 20 to 10240.
Setting this greater than ``min_interval`` gives the BLE hardware a better chance to avoid
collisions with other BLE transmissions. Defaults to the iBeacon specification's defined interval: ``100ms``.
- **measured_power** (*Optional*, int): The RSSI of the iBeacon as measured 1 meter from the device.
This is used to calibrate the ranging calculations in iOS. The procedure for setting this value can
be found in Apple's `Getting Started with iBeacon PDF <https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf>`__
under the heading *Calibrating iBeacon*. Between -128 to 0. Defaults to ``-59``.
- **tx_power** (*Optional*, int): The transmit power of the iBeacon in dBm.
One of -12, -9, -6, -3, 0, 3, 6, 9. Defaults to ``3dBm``.
Setting Up
----------

177
components/esp8266.rst
View File

@ -20,7 +20,7 @@ Configuration variables:
- **board** (**Required**, string): The PlatformIO board ID that should
be used. Choose the appropriate board from
`this list <https://registry.platformio.org/platforms/platformio/espressif8266/boards>`__ (the icon next to the
`this list <https://registry.platformio.org/platforms/platformio/espressif8266/boards>`__ (the icon next to the
name can be used to copy the board ID). *This only affects pin aliases, flash size and some internal settings*, if unsure
choose a generic board from Espressif such as ``esp01_1m``.
- **framework** (*Optional*): Options for the underlying framework used by ESPHome.
@ -39,6 +39,181 @@ Configuration variables:
- **board_flash_mode** (*Optional*, string): The SPI mode of the flash chip. One of ``qio``, ``qout``, ``dio`` and ``dout``. Defaults to ``dout`` for compatibility with all chips. Note: on the next OTA update the actual flash mode is automatically detected and changed to the appropriate one.
- **early_pin_init** (*Optional*, boolean): Specifies whether pins should be initialised as early as possible to known values. Recommended value is ``false`` where switches are involved, as these will toggle when updating the firmware or when restarting the device. Defaults to ``true``.
GPIO Pin Numbering
------------------
Many boards have a pin numbering for the exposed pins that is different from the internally used
ones. ESPHome tries to map the silk-screen pin numbers into the internal pin numbers with a few
boards, but for generic ESP8266 boards it is often required to just use the internal pin numbers.
To do this, just prefix all pins with ``GPIO``, for example ``GPIO0`` for the pin with the internal pin
number 0.
Some notes on the pins:
- ``GPIO6`` - ``GPIO11``, ``GPIO0``, ``GPIO2`` and ``GPIO15`` are often already used by the internal
flash interface and boot mode detection. So it's best to avoid using these pins.
- ``GPIO17`` additionally has an ADC connected to it. See the :doc:`/components/sensor/adc`
to read voltages (in the range from 0 to 1.0V) on this pin.
.. code-block:: yaml
# Example configuration entry
esphome:
name: livingroom
esp8266:
board: nodemcuv2
binary_sensor:
- platform: gpio
name: "Pin GPIO17"
pin: GPIO17
Special Pins
^^^^^^^^^^^^
=================== =============================================
``GPIO0`` Controls Boot Mode
------------------- ---------------------------------------------
``GPIO1`` UART TX pin
------------------- ---------------------------------------------
``GPIO2`` Controls Boot Mode
------------------- ---------------------------------------------
``GPIO3`` UART RX pin
------------------- ---------------------------------------------
``GPIO6`` SDIO/Flash CLK pin
------------------- ---------------------------------------------
``GPIO7`` SDIO/Flash Data 0 pin
------------------- ---------------------------------------------
``GPIO8`` SDIO/Flash Data 1 pin
------------------- ---------------------------------------------
``GPIO9`` SDIO/Flash Data 2 pin (qio/qout only)
------------------- ---------------------------------------------
``GPIO10`` SDIO/Flash Data 3 pin (qio/qout only)
------------------- ---------------------------------------------
``GPIO11`` SDIO/Flash CMD pin
------------------- ---------------------------------------------
``GPIO12`` Attached to Hardware SPI controller MISO
------------------- ---------------------------------------------
``GPIO13`` Attached to Hardware SPI controller MOSI
------------------- ---------------------------------------------
``GPIO14`` Attached to Hardware SPI controller CLK
------------------- ---------------------------------------------
``GPIO15`` Controls Boot Mode; Attached to Hardware SPI
controller CS
------------------- ---------------------------------------------
``GPIO16`` Special pin that can be accessed from RTC,
and is Deep-Sleep wakeup pin
------------------- ---------------------------------------------
TOUT aka ``GPIO17`` ADC pin for measuring voltages, can only be
used as analog input pin
=================== =============================================
This means effectively only the following pins can be used as general purpose GPIO:
========== ============================== ==============================
**Pin** **Restrictions** **State after Reset**
---------- ------------------------------ ------------------------------
``GPIO0`` If HIGH on boot Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO2`` If HIGH on boot Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO4`` High Impedance
---------- ------------------------------ ------------------------------
``GPIO5`` High Impedance
---------- ------------------------------ ------------------------------
``GPIO6`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO12`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO13`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO14`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO15`` If LOW on boot Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO16`` Has pull-down (but no pull-up) Weak Pull Down
resistor
========== ============================== ==============================
Boot Modes
----------
On each boot, the ESP8266 will check three pins to determine in which boot mode to enter.
There are three boot modes:
========================= ========= ========= ========== ==============
**Mode** ``GPIO0`` ``GPIO2`` ``GPIO15`` ``boot mode:``
------------------------- --------- --------- ---------- --------------
Boot from Flash (normal) HIGH HIGH LOW 3
------------------------- --------- --------- ---------- --------------
Download Code from UART LOW HIGH LOW 1
------------------------- --------- --------- ---------- --------------
Boot from SD-Card ANY ANY HIGH 4-7
========================= ========= ========= ========== ==============
You can identify these on boot-up by looking at the UART output, the first number
in the ``boot mode:`` line tells you what mode was selected
.. code-block:: text
ets Jan 8 2013,rst cause:4, boot mode:(3,6)
The first lines when viewing the UART logs might have unrecognized characters. This is
because the effective baudrate of the ESP8266 bootloader is 74800, whereas the program uses 115200.
Reset Causes
------------
Additionally, the first line also contains the **reset cause**.
These reset causes `are documented
<https://www.espressif.com/sites/default/files/documentation/esp8266_reset_causes_and_common_fatal_exception_causes_en.pdf>`__:
== ===================================
0 Undefined
-- -----------------------------------
1 Power On Reboot
-- -----------------------------------
2 External reset or deep-sleep wakeup
-- -----------------------------------
4 Hardware WDT reset
== ===================================
After a software reset, the reset cause will not change.
Electrical Characteristics
--------------------------
=========================================================== =========== =========== =========== ===========
**Parameter** **Min.** **Typical** **Max.** **Unit**
----------------------------------------------------------- ----------- ----------- ----------- -----------
Operating Temperature -40 125 °C
----------------------------------------------------------- ----------- ----------- ----------- -----------
Working Voltage ``V_IO`` 2.5 3.3 3.6 V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_IL`` - INPUT voltage level to be considered LOW -0.3 0.25*V_IO V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_IH`` - INPUT voltage level to be considered HIGH 0.75*V_IO 3.6 V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_OL`` - OUTPUT voltage level for LOW 0.1*V_IO V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_OH`` - OUTPUT voltage level for HIGH 0.8*V_IO V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``I_MAX`` - Maximum current for GPIO 12 mA
----------------------------------------------------------- ----------- ----------- ----------- -----------
Power Consumption in Deep Sleep 20 µA
----------------------------------------------------------- ----------- ----------- ----------- -----------
Power Consumption in Active Mode 120 mA
=========================================================== =========== =========== =========== ===========
Source: `ESP8266EX datasheet <https://www.espressif.com/sites/default/files/documentation/0a-esp8266ex_datasheet_en.pdf>`__
The internal pull up/down resistors have values of 30kΩ to 100kΩ
(`source <https://bbs.espressif.com/viewtopic.php?t=1079>`__).
See Also
--------

21
components/esphome.rst
View File

@ -26,7 +26,8 @@ Configuration variables:
- **name** (**Required**, string): This is the name of the node. It
should always be unique in your ESPHome network. May only contain lowercase
characters, digits and hyphens, and can be at most 31 characters long.
characters, digits and hyphens, and can be at most 24 characters long by default, or 31
characters long if ``name_add_mac_suffix`` is ``false``.
See :ref:`esphome-changing_node_name`.
Advanced options:
@ -50,6 +51,10 @@ Advanced options:
- **name** (**Required**, string): Name of the project
- **version** (**Required**, string): Version of the project
- **min_version** (*Optional*, string): The minimum ESPHome version required to compile this configuration.
See :ref:`esphome-min_version`.
- **compile_process_limit** (*Optional*, int): The maximum number of simultaneous compile processes to run.
Defaults to the number of cores of the CPU which is also the maximum you can set.
Old-style platform options, which have been moved to the platform-specific :doc:`esp32 </components/esp32>` and
:doc:`esp8266 </components/esp8266>` sections but are still accepted here for compatibility reasons (usage not
@ -129,11 +134,11 @@ too many WiFi/MQTT connection attempts, Over-The-Air updates being applied or th
Configuration variables:
- **priority** (*Optional*, float): The priority to execute your custom shutdown code. A higher value
means a high priority and in case of shutdown triggers that the code is executed **later**.
means a high priority and in case of shutdown triggers that the code is executed **later**.
Priority is used primarily for the initialization order of components. Shutdowns for these components are handled in *reverse* order, such that e.g. sensors (600) are shutdown before the hardware components (800) they depend on.
Please note this is an ESPHome-internal value and any change will not be marked as a breaking change.
Please note this is an ESPHome-internal value and any change will not be marked as a breaking change.
Defaults to ``600``. For priority values refer to the list in the :ref:`esphome-on_boot` section.
- See :ref:`Automation <automation>`.
.. _esphome-on_loop:
@ -337,6 +342,14 @@ should be ``author_name.project_name``.
name: "jesse.leds_party"
version: "1.0.0"
.. _esphome-min_version:
Minimum ESPHome version
-----------------------
This allows YAML files to specify the minimum version of ESPHome required to compile.
This is useful in the case of packages where a published package might use features only
available in a newer version of ESPHome. This allows for a more friendly error message.
See Also
--------

15
components/ethernet.rst
View File

@ -181,6 +181,21 @@ Configuration for ESP32-Ethernet-Kit board
clk_mode: GPIO0_IN
phy_addr: 1
power_pin: GPIO5
Configuration for M5Stack PoESP32 Unit
--------------------------------------
.. code-block:: yaml
ethernet:
type: IP101
mdc_pin: GPIO23
mdio_pin: GPIO18
clk_mode: GPIO0_IN
phy_addr: 1
power_pin: GPIO5
See Also
--------

4
components/exposure_notifications.rst
View File

@ -19,7 +19,7 @@ nearby COVID-19 exposure notification bluetooth messages sent by phones running
then:
- lambda: |
ESP_LOGD("main", "Got notification:");
ESP_LOGD("main", " RPI: %s", hexencode(x.rolling_proximity_identifier).c_str());
ESP_LOGD("main", " RPI: %s", format_hex_pretty(x.rolling_proximity_identifier).c_str());
ESP_LOGD("main", " RSSI: %d", x.rssi);
Configuration variables:
@ -67,7 +67,7 @@ minute, the indicator will be on.
then:
- lambda: |
ESP_LOGD("main", "Got notification:");
ESP_LOGD("main", " RPI: %s", hexencode(x.rolling_proximity_identifier).c_str());
ESP_LOGD("main", " RPI: %s", format_hex_pretty(x.rolling_proximity_identifier).c_str());
ESP_LOGD("main", " RSSI: %d", x.rssi);
# Stop existing timer so that turn_off doesn't get called

571
components/ezo_pmp.rst Normal file
View File

@ -0,0 +1,571 @@
Atlas Scientific Peristaltic Pump
=================================
.. seo::
:description: Instructions for setting up an Atlas Scientific Peristaltic Pump in ESPHome
:image: ezo-pmp.jpg
:keywords: pump, peristaltic, atlas, ezo
The ``ezo_pmp`` component allows you to use an Atlas Scientific Peristaltic Pump with ESPHome.
Both the EZO-PMP (`datasheet <https://files.atlas-scientific.com/EZO_PMP_Datasheet.pdf>`__)
and EZO-PMP-L (`datasheet <https://files.atlas-scientific.com/EZO_PMP_L_Datasheet.pdf>`__) are supported.
The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
.. note::
This component will not be directly controllable in the Home Assistant front-end automatically because
Home Assistant doesn't have support for pumps. In order to control the pump from the frontend you will need to use
templates to offer access to the actions you need. Please see :ref:`ezo-pmp-ha-config`.
.. figure:: images/ezo-pmp.jpg
:align: center
:width: 80.0%
.. code-block:: yaml
ezo_pmp:
id: ezo_pmp
address: 103 # Default Address for the EZO-PMP.
update_interval: 60s
Configuration variables:
- **id** (**Required**, :ref:`config-id`): Specify the ID of the pump so that you can control it.
- **address** (*Optional*, int): Specify the I²C address of the sensor. Defaults to 103.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
Sensors
-----------------------------
Since the EZO-PMP offers a large number of sensors and each sensor needs to be polled individually, the code has been
optimized not to update a sensor that is not defined in the config. If you need very quick updates from the pump (under 3 seconds)
only enable the sensors that you actually need.
.. _ezo_pmp-current_volume_dosed_sensor:
``current_volume_dosed``
-----------------------------
This sensor indicates the volume (in milliliters) that has been dosed in the currently running or last ran dosing command.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
current_volume_dosed:
id: current_volume_dosed
name: Current Volume Dosed
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-total_volume_dosed_sensor:
``total_volume_dosed``
-----------------------------
This sensor indicates total volume (in milliliters) that has been dosed since the last time the pump was turned on. Could be a
negative number if the pump has been run in reverse.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
total_volume_dosed:
id: total_volume_dosed
name: Total Volume Dosed
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-absolute_total_volume_dosed_sensor:
``absolute_total_volume_dosed``
-------------------------------
This sensor indicates the absolute total volume (in milliliters) that has been dosed since the last time the pump was turned on.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
absolute_total_volume_dosed:
id: absolute_total_volume_dosed
name: Absolute Total Volume Dosed
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-last_volume_requested_sensor:
``last_volume_requested``
-----------------------------
Indicates the total volume (in milliliters) that is being dosed (or was if the pump has already finished) by a dose Action. When
using dosing actions that have a duration, the sensor will have the right calculation for total volume.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
last_volume_requested:
id: last_volume_requested
name: Last Volume Requested
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-max_flow_rate_sensor:
``max_flow_rate``
-----------------------------
The pump provides its own calculation of the maximum flow rate it can provide (in ml/minute). Dosing requests that exceed this rate
will fail. When using the :ref:`Dose Continuously <ezo_pmp-dose_continuously_action>` Action, this is the volume the pump will
dose every minute. This value will get updated after the pump is calibrated (see :ref:`ezo_pmp-set_calibration_volume_action`).
.. code-block:: yaml
sensor:
- platform: ezo_pmp
max_flow_rate:
id: max_flow_rate
name: Max Flow Rate
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _ezo_pmp-pump_voltage_sensor:
``pump_voltage``
-----------------------------
The current voltage of the power supply that powers the pump. Not to be confused with the voltage that powers the electronics on the pump.
.. code-block:: yaml
sensor:
- platform: ezo_pmp
pump_voltage:
id: pump_voltage
name: Pump Voltage
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
Binary Sensors
-----------------------------
.. _ezo_pmp-pump_state_binary_sensor:
``pump_state``
-----------------------------
Indicates if the pump is currently running or not.
.. code-block:: yaml
binary_sensor:
- platform: ezo_pmp
pump_state:
id: pump_state
name: Pump State
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. _ezo_pmp-is_paused_binary_sensor:
``is_paused``
-----------------------------
Indicates if a dosing action is currently paused.
.. code-block:: yaml
binary_sensor:
- platform: ezo_pmp
is_paused:
id: is_paused
name: Is Paused
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
Text Sensors
-----------------------------
.. _ezo_pmp-dosing_mode_text_sensor:
``dosing_mode``
-----------------------------
Indicates the dosing mode the pump is currently running as. Can be any of `Volume`, `Volume/Time`, `Constant Flow Rate`, `Continuous`, `None`.
.. code-block:: yaml
text_sensor:
- platform: ezo_pmp
dosing_mode:
id: dosing_mode
name: Dosing Mode
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Text Sensor <config-text_sensor>`.
.. _ezo_pmp-calibration_status_text_sensor:
``calibration_status``
-----------------------------
Indicates calibration status of the pump. Can be any of `Fixed Volume`, `Volume/Time`, `Fixed Volume & Volume/Time` or `Uncalibrated`.
.. code-block:: yaml
text_sensor:
- platform: ezo_pmp
calibration_status:
id: calibration_status
name: Calibration Status
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Text Sensor <config-text_sensor>`.
Actions
-----------------------------
.. _ezo_pmp-dose_continuously_action:
``ezo_pmp.dose_continuously`` Action
------------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose continuously
at the :ref:`Maximum Flow Rate <ezo_pmp-max_flow_rate_sensor>`. The pump will automatically stop after 20 days
of running in continuous mode.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.find:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-dose_volume_action:
``ezo_pmp.dose_volume`` Action
------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose an specific volume (in milliliters)
at the :ref:`Maximum Flow Rate <ezo_pmp-max_flow_rate_sensor>`. If the volume is negative the pump will run backwards.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.dose_volume:
id: ezo_pmp
volume: 10
# Templated
- ezo_pmp.dose_volume:
id: ezo_pmp
volume: !lambda |-
return id(some_volume_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume** (**Required**, float, :ref:`templatable <config-templatable>`): The volume to dose in milliliters. If negative, pump will run in reverse.
.. _ezo_pmp-dose_volume_over_time_action:
``ezo_pmp.dose_volume_over_time`` Action
----------------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose an specific `volume` (in milliliters)
over the provided `duration` (in minutes). At the end of the time period the pump will have dosed the specified `volume`.
If the volume is negative the pump will run backwards.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.dose_volume_over_time:
id: ezo_pmp
volume: 23.4
duration: 2
# Templated
- ezo_pmp.dose_volume_over_time:
id: ezo_pmp
volume: !lambda |-
return id(some_volume_sensor).state;
duration: !lambda |-
return id(some_duration_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume** (**Required**, float, :ref:`templatable <config-templatable>`): The volume to dose in milliliters. If negative, pump will run in reverse.
- **duration** (**Required**, int, :ref:`templatable <config-templatable>`): The time (in minutes) the pump will take to dose the volume requested.
.. _ezo_pmp-dose_with_constant_flow_rate_action:
``ezo_pmp.dose_with_constant_flow_rate`` Action
-----------------------------------------------
Use this action in an :ref:`automations <automation>` to have the peristaltic pump dose an specific `volume` (in milliliters) every minute
for the provided `duration` (in minutes). At the end of the time period the pump will have dosed the specified `volume` times the `duration`.
If the volume is negative the pump will run backwards.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.dose_with_constant_flow_rate:
id: ezo_pmp
volume_per_minute: 10.2
duration: 2
# Templated
- ezo_pmp.dose_with_constant_flow_rate:
id: ezo_pmp
volume_per_minute: !lambda |-
return id(some_volume_sensor).state;
duration: !lambda |-
return id(some_duration_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume_per_minute** (**Required**, float, :ref:`templatable <config-templatable>`): The volume to dose in milliliters every minute. If negative, pump will run in reverse.
- **duration** (**Required**, int, :ref:`templatable <config-templatable>`): The time (in minutes) the pump will dose the volume requested every minute.
.. _ezo_pmp-pause_dosing_action:
``ezo_pmp.pause_dosing`` Action
-------------------------------
Use this action to pause a Dosing command that was previously issued. To determine if the dosing is paused or not, you can use the :ref:`Is Paused <ezo_pmp-is_paused_binary_sensor>` sensor.
If the pump is currently paused, issuing this action again will unpause it.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.pause_dosing:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-stop_dosing_action:
``ezo_pmp.stop_dosing`` Action
------------------------------
Use this action to stop the current Dosing command.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.stop_dosing:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-clear_total_volume_dosed_action:
``ezo_pmp.clear_total_volume_dosed`` Action
-------------------------------------------
Clear the values of the :ref:`Current Volume Dosed <ezo_pmp-current_volume_dosed_sensor>`, :ref:`Total Volume Dosed <ezo_pmp-total_volume_dosed_sensor>`
and :ref:`Absolute Total Volume Dosed <ezo_pmp-absolute_total_volume_dosed_sensor>` sensors.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.clear_total_volume_dosed:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-set_calibration_volume_action:
``ezo_pmp.set_calibration_volume`` Action
-----------------------------------------
Use this action to calibrate the peristaltic pump. The EZO-PMP needs two forms of calibration: absolute volume and volume over time. You can check
the calibration status by using the :ref:`Calibration Status<ezo_pmp-calibration_status_text_sensor>` sensor. For the procedure on calibrating the pump
check the datasheet.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.set_calibration_volume:
id: ezo_pmp
volume: 10.01
# Templated
- ezo_pmp.set_calibration_volume:
id: ezo_pmp
volume: !lambda |-
return id(some_volume_sensor).state;
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **volume** (**Required**, float, :ref:`templatable <config-templatable>`): The volume measured as part of the calibration process.
.. _ezo_pmp-clear_calibration_action:
``ezo_pmp.clear_calibration`` Action
------------------------------------
Clear the calibration values stored in the pump. You can check the calibration status by using the
:ref:`Calibration Status<ezo_pmp-calibration_status_text_sensor>` sensor.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.clear_calibration:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-find_action:
``ezo_pmp.find`` Action
-----------------------
Use this action to make the LED on the Pump control board to blink for a minute. The pump will not respond to any other action while the LED is blinking.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.find:
id: ezo_pmp
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
.. _ezo_pmp-change_i2c_address_action:
``ezo_pmp.change_i2c_address`` Action
-------------------------------------------
Changes the i2c address of the pump to the provided value. After the address is changed you must upload a new version of the ESPHome firmware with the updated I2C
address for the pump to work.
.. code-block:: yaml
on_...:
then:
- ezo_pmp.change_i2c_address:
id: ezo_pmp
address: 100
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the pump.
- **address** (**Required**, int, :ref:`templatable <config-templatable>`): The new I2C address for the pump.
.. _ezo-pmp-ha-config:
Home Assistant Configuration
----------------------------
In order to provide control of the pump from the home assistant frontend it is important to expose the actions
as components that have UI rendering. This could be done using templates in ESPHome. Here is an example using a
`Template Button` and `Template Number` to dose a certain volume over time.
.. code-block:: yaml
i2c:
ezo_pmp:
id: ezo_pmp
number:
- platform: template
id: volume
name: "Volume"
optimistic: true
min_value: 0
max_value: 100
step: 0.01
- platform: template
id: duration
name: "Duration"
optimistic: true
min_value: 0
max_value: 100
step: 1
button:
- platform: template
name: "Dose Over Time"
on_press:
- ezo_pmp.dose_volume_over_time:
id: ezo_pump
volume: !lambda |-
return id(volume).state;
duration: !lambda |-
return id(duration).state;
.. _ezo_pmp-lambda_calls:
lambda calls
------------
From :ref:`lambdas <config-lambda>`, you can also access the actions on the peristaltic pump to do some
advanced stuff (see the full API Reference for more info). The name of the functions is the same as the name
of the actions in YAML config.
See Also
--------
- :apiref:`ezo_pmp/ezo_pmp.h`
- :ghedit:`Edit`

BIN
components/images/ezo-pmp.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.2 KiB

1
components/index.rst
View File

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

7
components/light/shelly_dimmer.rst
View File

@ -5,7 +5,7 @@ Shelly Dimmer
:description: Instructions for setting up a Shelly Dimmer 2.
:image: shellydimmer2.jpg
The ``shelly_dimmer`` component adds support for the dimming and power-metering functionality that can be found the `Shelly Dimmer 2 <https://shelly.cloud/knowledge-base/devices/shelly-dimmer-2/>`_. The interaction with mains is done via an STM32 microcontroller that is flashed with an `open source firmware <https://github.com/jamesturton/shelly-dimmer-stm32>`_.
The ``shelly_dimmer`` component adds support for the dimming and power-metering functionality that can be found the `Shelly Dimmer 2 <https://shelly.cloud/knowledge-base/devices/shelly-dimmer-2/>`_. The interaction with mains is done via an STM32 microcontroller that is automatically (when configured) flashed with an `open source firmware <https://github.com/jamesturton/shelly-dimmer-stm32>`_.
A detailed analysis of the Shelly Dimmer 2 hardware is given `here <https://github.com/arendst/Tasmota/issues/6914>`_.
Warning!!! At the time of writing there seems to be no way to revert back to the "stock firmware", because there seems to be no way to revert to firmware of the STM32 co-processor.
@ -84,14 +84,15 @@ Configuration variables:
.. note::
When flashing Shelly Dimmer with esphome for the first time, flashing the STM firmware is necessary too for the dimmer to work:
When flashing Shelly Dimmer with esphome for the first time, automatic flashing the STM firmware is necessary too for the dimmer to work and enabled by the following configuration.:
.. code-block:: yaml
firmware:
version: "51.6" #<-- set version here
update: true
There is no action required by the user to flash the STM32. There is no way to revert to stock firmware on the STM32 at the time of writing.
- All other options from :ref:`Light <config-light>`.

3
components/modbus_controller.rst
View File

@ -56,6 +56,9 @@ Configuration variables:
- **command_throttle** (*Optional*, int): minimum time in milliseconds 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.
- **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked.
Defaults to 60 seconds.
Example
-------

4
components/number/index.rst
View File

@ -309,8 +309,8 @@ advanced stuff (see the full API Reference for more info).
call.perform();
Check the API reference for information on the methods that are available for
the ``NumberCall`` object. You can for example also use ``call.to_min()``
to set the number to its minimum value or ``call.increment(true)`` to increment
the ``NumberCall`` object. You can for example also use ``call.number_to_min()``
to set the number to its minimum value or ``call.number_increment(true)`` to increment
the number by its step size with the cycle feature enabled.
- ``.state``: Retrieve the current value of the number. Is ``NAN`` if no value has been read or set.

12
components/ota.rst
View File

@ -16,8 +16,8 @@ ESPHome also has an "OTA safe mode". If for some reason your
node gets into a boot loop, ESPHome will automatically try to detect
this and will go over into a safe mode after the configured unsuccessful boot
attempts (Defaults to ``10``). In that mode, all components are disabled and only Serial
Logging + Network(WiFi or Ethernet) + OTA are initialized, so that you can upload a new
binary. You can trigger entering safe mode by either configuring a dedicated button or
Logging + Network(WiFi or Ethernet) + OTA are initialized, so that you can upload a new
binary. You can trigger entering safe mode by either configuring a dedicated button or
switch to do that or by pressing the reset button on the board for ``num_attempts`` times.
@ -34,8 +34,12 @@ Configuration variables:
- **safe_mode** (*Optional*, boolean): Whether to enable safe mode.
Defaults to ``true``.
- **password** (*Optional*, string): The password to use for updates.
- **port** (*Optional*, int): The port to use for OTA updates. Defaults
to ``3232`` for the ESP32 and ``8266`` for the ESP8266.
- **port** (*Optional*, int): The port to use for OTA updates.
Defaults:
- ``3232`` for the ESP32
- ``8266`` for the ESP8266
- ``2040`` for the RP2040
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when in
safe mode. Defaults to ``5min``.

2
components/power_supply.rst
View File

@ -30,7 +30,7 @@ Configuration variables:
power supply so that it can be used by the outputs.
- **pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The
GPIO pin to control the power supply on.
- **enable_time** (*Optional*, :ref:`config-time`): The time to
- **enable_time** (*Optional*, :ref:`config-time`): The time
that the power supply needs for startup. The output component will
wait for this period of time after turning on the PSU and before
switching the output on. Defaults to ``20ms``.

30
components/rp2040.rst Normal file
View File

@ -0,0 +1,30 @@
RP2040 Platform
===============
.. seo::
:description: Configuration for the RP2040 platform for ESPHome.
:image: rp2040.svg
This component contains platform-specific options for the RP2040 platform.
.. note::
Support for all aspects of ESPHome on the RP2040 is still in development.
Please search for or create an `issue <https://github.com/esphome/issues/issues/new?assignees=&labels=&template=bug_report.yml>`__ if you encounter an unknown problem.
.. code-block:: yaml
# Example configuration entry
rp2040:
board: rpipicow
Configuration variables:
------------------------
- **board** (*Optional*, string): The board type. Valid options are ``rpipico`` and ``rpipicow``.
See Also
--------
- :doc:`esphome`
- :ghedit:`Edit`

27
components/sensor/adc.rst
View File

@ -6,9 +6,12 @@ Analog To Digital Sensor
:image: flash.svg
The Analog To Digital (``adc``) Sensor allows you to use the built-in
ADC in your device to measure a voltage on certain pins. On the ESP8266
only pin A0 (GPIO17) supports this. On the ESP32 pins GPIO32 through
GPIO39 can be used.
ADC in your device to measure a voltage on certain pins.
- ESP8266: Only pin A0 (GPIO17) can be used.
- ESP32: GPIO32 through GPIO39 can be used.
- RP2040: GPIO26 through GPIO29 can be used.
.. figure:: images/adc-ui.png
:align: center
@ -105,7 +108,7 @@ To measure the VCC voltage, set ``pin:`` to ``VCC`` and make sure nothing is con
.. note::
To avoid confusion: It measures the voltage at the chip, and not at the VCC pin of the board. It should usually be around 3.3V.
.. code-block:: yaml
sensor:
@ -113,6 +116,22 @@ To measure the VCC voltage, set ``pin:`` to ``VCC`` and make sure nothing is con
pin: VCC
name: "VCC Voltage"
RP2040 Internal Core Temperature
--------------------------------
The RP2040 has an internal temperature sensor that can be used to measure the core temperature. This sensor is not available on the GPIO pins, but is available on the internal ADC.
The below code is how you can access the temperature and expose as a sensor. The filter values are taken from the RP2040 datasheet to calculate Voltage to Celcius.
.. code-block:: yaml
sensor:
- platform: adc
pin: TEMPERATURE
name: "Core Temperature"
unit_of_measurement: "°C"
filters:
- lambda: return 27 - (x - 0.706f) / 0.001721f;
Multiple ADC Sensors
---------------------

66
components/sensor/adc128s102.rst Normal file
View File

@ -0,0 +1,66 @@
ADC128S102 8-Channel 12-Bit A/D Converter
==========================================
.. seo::
:description: Instructions for setting up ADC128S102 12 Bit Analog to Digital Converter in ESPHome.
:keywords: ADC128S102
:image: adc128s102.png
The ADC128S102 is a low-power, eight-channel CMOS 12-bit analog-to-digital converter specified for conversion
throughput rates of 500 ksps to 1 MSPS. The converter is based on a successive-approximation register architecture
with an internal track-and-hold circuit.
.. figure:: images/adc128s102.png
:align: center
:width: 50.0%
.. _adc128s102-component:
Component/Hub
-------------
The ADC128S102 component allows you to use ADC128S102 8-Channel 12-Bit A/D Converter
(`datasheet <https://www.ti.com/lit/ds/symlink/adc128s102.pdf>`__,
`Texas Instruments <https://www.ti.com/product/ADC128S102>`__) in ESPHome.
It uses the :ref:`SPI Bus <spi>` for communication.
Once configured, you can use any of the 8 pins as
sensors for your projects.
.. code-block:: yaml
# Example configuration entry
adc128s102:
cs_pin: GPIO15
id: my_adc
sensor:
- platform: adc128s102 # Attached to pin 0 of the ADC128S102.
update_interval: 1s
adc128s102_id: my_adc
id: freezer_temp_source
channel: 0 # ADC128S102 channel
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The id to use for this ADC128S102 component.
- **cs_pin** (**Required**, int): The SPI cable select pin to use
Sensor
------
The ``adc128s102`` sensor allows you to use your ADC128S102 12-Bit A/D Converter sensors with ESPHome.
First, setup a :ref:`ADC128S102 Hub <adc128s102-component>` for your ADC128S102 sensor and then use this
sensor platform to create individual sensors that will report the voltage to Home Assistant.
Configuration variables:
- **adc128s102_id** (**Required**, :ref:`config-id`): The id of the parent ADC128S102 component.
- **channel** (**Required**, int): The channel of the ADC128S102 to use.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
See Also
--------
- :ref:`spi`
- :apiref:`adc128s102/adc128s102.h`
- :ghedit:`Edit`

40
components/sensor/ble_client.rst
View File

@ -6,7 +6,7 @@ BLE Client Sensor
:image: bluetooth.svg
The ``ble_client`` component is a sensor platform that can
query BLE devices for specific values of service characteristics.
query BLE devices for RSSI or specific values of service characteristics.
For more information on BLE services and characteristics, see
:doc:`/components/ble_client`.
@ -21,6 +21,7 @@ For more information on BLE services and characteristics, see
sensor:
- platform: ble_client
type: characteristic
ble_client_id: itag_black
name: "iTag battery level"
service_uuid: '180f'
@ -28,20 +29,34 @@ For more information on BLE services and characteristics, see
icon: 'mdi:battery'
unit_of_measurement: '%'
- platform: ble_client
type: rssi
ble_client_id: itag_black
name: "iTag RSSI"
Configuration variables:
------------------------
- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
- **service_uuid** (**Required**, UUID): UUID of the service on the device.
- **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to query.
- **descriptor_uuid** (*Optional*, UUID): UUID of the characteristic's descriptor to query.
- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for converting a raw data
reading to a sensor value. See :ref:`ble-sensor-lambda` for more information.
- **notify** (*Optional*, boolean): Instruct the server to send notifications for this
characteristic.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
- All other options from :ref:`Sensor <config-sensor>`.
- **type** (**Required**): One of ``rssi``, ``characteristic``.
rssi options:
- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
- All other options from :ref:`Sensor <config-sensor>`.
characteristic options:
- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
- **service_uuid** (**Required**, UUID): UUID of the service on the device.
- **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to query.
- **descriptor_uuid** (*Optional*, UUID): UUID of the characteristic's descriptor to query.
- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for converting a raw data
reading to a sensor value. See :ref:`ble-sensor-lambda` for more information.
- **notify** (*Optional*, boolean): Instruct the server to send notifications for this
characteristic.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device.
- All other options from :ref:`Sensor <config-sensor>`.
Automations:
@ -64,6 +79,7 @@ variable ``x`` of type ``std::vector<uint8_t>``. The function must return a sing
sensor:
- platform: ble_client
type: characteristic
ble_client_id: t_sensor
name: "Temperature Sensor 32bit float"
...

13
components/sensor/daly_bms.rst
View File

@ -238,6 +238,19 @@ Connect RX from BMS to TX in ESP board and TX from BMS to RX in ESP board
:width: 100.0%
Uart Pinout.
**3.3v Warning:** some BMS 3.3v cant source large currents and may not work to properly power the ESP. If you are having WIFI connection issues or similar, try a different power source. There is 12-15v available on the Daly connector which via a proper step-down converter can properly power the ESP.
On the ESP32 (untested on ESP8266) if you are having missing data (such as Temperature 1/2), it may be due to UART buffer size.
Add the following to your configuration to increase the buffer from the default 256 to 512.
.. code-block::
uart:
...
rx_buffer_size: 512
See Also
--------

2
components/sensor/esp32_hall.rst
View File

@ -50,6 +50,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`adc`
- :doc:`/devices/esp32`
- :doc:`/components/esp32`
- :apiref:`esp32_hall/esp32_hall.h`
- :ghedit:`Edit`

135
components/sensor/ezo.rst
View File

@ -9,6 +9,8 @@ EZO sensor circuits
The ``ezo`` sensor platform allows you to use your EZO sensor circuits with
ESPHome. The :ref:`I²C Bus <i2c>` is
required to be set up in your configuration for this sensor to work.
All embedded solutions from EZO can be found `here <https://atlas-scientific.com/embedded-solutions/>`__.
If a certain command is not supported directly, it can be executed with the ``send_custom()`` method call.
.. figure:: images/ezo-ph-circuit.png
:align: center
@ -43,20 +45,145 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
.. _evo_callbacks:
Callbacks
---------
- **on_led:** : Triggered when the result of ``get_led_state()`` is ready. The LED state is provided as a boolean variable named ``x``.
- **on_device_information:** : Triggered when the result of ``get_device_information()`` is ready. The result is provided as a ``std::string`` variable named ``x``.
- **on_slope:** : Triggered when the result of ``get_slope()`` is ready. The result is provided as a ``std::string`` variable named ``x``.
- **on_calibration:** : Triggered when the result of ``get_calibration()`` is ready. The result is provided as a ``std::string`` variable named ``x``.
- **on_t:** : Triggered when the result of ``get_t()`` is ready. The result is provided as a ``std::string`` variable named ``x``.
- **on_custom:** : Triggered when the result of ``get_custom()`` is ready. The result is provided as a ``std::string`` variable named ``x``.
.. _evo_lambda_calls:
lambda calls
------------
From :ref:`lambdas <config-lambda>`, you can set the temperature compensation for the
sensors that support that option.
From :ref:`lambdas <config-lambda>`, you can interact with the sensor in various ways. For any ``get`` command a trigger will be called with the information retrieved from the sensor. See :ref:`evo_callbacks`. For more information on the command specifics, refer to the datasheet.
- ``set_tempcomp_value()``: Send the given temperature to the sensor.
- ``set_i2c(uint8_t address)``: Set I2C address of the device, must be an integer between 1 and 127
.. code-block:: cpp
id(ph_ezo).set_i2c(100);
- ``get_device_information()``: Sensor retrieves calibration and triggers ``on_device_information:`` once done
.. code-block:: cpp
id(ph_ezo).get_device_information();
- ``set_sleep()``: Put the device to sleep
.. code-block:: cpp
id(ph_ezo).set_sleep();
- ``get_state()``: Performs a read on the current sensor.
.. code-block:: cpp
id(ph_ezo).get_state();
- ``get_slope()``: Sensor retrieves slope and triggers ``on_slope:`` once done
.. code-block:: cpp
id(ph_ezo).get_slope();
- ``get_t()``: Sensor retrieves temperature compensation value (in Celcius) and triggers ``on_t:`` once done
.. code-block:: cpp
id(ph_ezo).get_t();
- ``set_t(float value)``: Send the given temperature (in Celcius) to the sensor.
.. code-block:: cpp
id(ph_ezo).set_t("27.00");
- ``set_tempcomp_value(float temp)``: Send the given temperature (in Celcius) to the sensor (this is an alias of `set_t()` for backwards compatibility)
.. code-block:: cpp
// Within a lambda, set the temperature compensation value from the temperature sensor
id(ph_ezo).set_tempcomp_value(id(rtd_ezo).state);
- ``get_calibration()``: Sensor retrieves calibration and triggers ``on_calibration:`` once done
.. code-block:: cpp
id(ph_ezo).get_calibration();
- ``set_calibration_generic(float value)``: Sets the calibration with no point.
.. code-block:: cpp
id(ph_ezo).set_calibration_generic(750.0);
- ``set_calibration_point_low(float value)``: Sets the low calibration point.
.. code-block:: cpp
id(ph_ezo).set_calibration_point_low(4.00);
- ``set_calibration_point_mid(float value)``: Sets the medium calibration point.
.. code-block:: cpp
id(ph_ezo).set_calibration_point_mid(7.00);
- ``set_calibration_point_high(float value)``: Sets the high calibration point.
.. code-block:: cpp
id(ph_ezo).set_calibration_point_high(10.00);
- ``clear_calibration()``: Clears all calibration points.
.. code-block:: cpp
id(ph_ezo).clear_calibration();
- ``get_led_state()``: Sensor LED state and triggers ``on_led:`` once done
.. code-block:: cpp
id(ph_ezo).get_led_state();
- ``set_led_state(bool on)``: Sensor LED on or off
.. code-block:: cpp
id(ph_ezo).set_led_state(true);
- ``send_custom(const std::string &payload, uint16_t delay_ms = 300, bool response_expected = false)``: Runs a custom command. This sends exactly what is in ``payload``. Optionally you can set a ``delay`` and if a response is expected that should be parsed. Defaults to ``false`` for custom commands. Triggers ``on_custom:`` if there's a response.
.. code-block:: cpp
// Run a custom command to turn on the LED
id(ph_ezo).send_custom("L,1");
See Also
--------

1
components/sensor/hmc5883l.rst
View File

@ -52,7 +52,6 @@ Configuration variables:
- **heading** (*Optional*): The heading of the sensor in degrees. All options from
:ref:`Sensor <config-sensor>`.
- **oversampling** (*Optional*): The oversampling parameter for the sensor.
- **range** (*Optional*): The range parameter for the sensor.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
- **oversampling** (*Optional*): Number of readings to average over for each sample. One of ``1x``, ``2x``,
``4x``, ``8x``. Defaults to ``1x``.

13
components/sensor/homeassistant.rst
View File

@ -16,7 +16,7 @@ states from your Home Assistant instance using the :doc:`native API </components
name: "Temperature Sensor From Home Assistant"
entity_id: sensor.temperature_sensor
With Home Assistant 2021.6 or newer, entity state attributes can also be imported.
Entity state attributes can also be imported:
.. code-block:: yaml
@ -32,7 +32,7 @@ With Home Assistant 2021.6 or newer, entity state attributes can also be importe
This component is only for numeral states. If you want to import arbitrary text states
from Home Assistant, use the :doc:`Home Assistant Text Sensor </components/text_sensor/homeassistant>`.
Albeit you might not plan to __export__ states from the node and you do not need an entity of the node
Albeit you might not plan to *export* states from the node and you do not need an entity of the node
in Home Assistant, this component still requires you to register the node under Home Assistant. See:
:doc:`Getting started with Home Assistant </guides/getting_started_hassio>`
@ -47,6 +47,15 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Sensor <config-sensor>`.
.. note::
The sensors implemented by this component are by default ``internal``, to avoid exporting back them to
Home Assistant. Should you still want to do that (eg. because you use ESPHome's very efficient filters
on them) you need to specifically configure ``internal: false``. Also, ``state_class``, ``unit_of_measurement``
are not inherited from the imported sensor so you need to set them manually.
See Also
--------

BIN
components/sensor/images/adc128s102.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 116 KiB

39
components/sensor/pulse_counter.rst
View File

@ -91,7 +91,7 @@ measure the total consumed energy in kWh.
# Example configuration entry
sensor:
- platform: pulse_counter
- platform: pulse_counter
pin: 12
unit_of_measurement: 'kW'
name: 'Power Meter House'
@ -129,6 +129,43 @@ trying to match.
This value is the raw count of pulses, and not the value you see after the filters
are applied.
Wiring
------
If you want to count pulses from a simple reed switch, the simplest way is to make
use of the internal pull-up/pull-down resistors.
You can wire the switch between a GPIO pin and GND; in this case set the pin to input, pullup and inverted:
.. code-block:: yaml
# Reed switch between GPIO and GND
sensor:
- platform: pulse_counter
pin:
number: 12
inverted: true
mode:
input: true
pullup: true
name: "Pulse Counter"
If you wire it between a GPIO pin and +3.3V, set the pin to input, pulldown:
.. code-block:: yaml
# Reed switch between GPIO and +3.3V
sensor:
- platform: pulse_counter
pin:
number: 12
mode:
input: true
pulldown: true
name: "Pulse Counter"
The safest way is to use GPIO + GND, as this avoids the possibility of short
circuiting the wire by mistake.
See Also
--------

6
components/sensor/pzemac.rst
View File

@ -143,8 +143,12 @@ You must set the ``address`` of the ``modbus_controller`` to the current address
modbus_controller:
- id: pzem
## the current device addr
# The current device address.
address: 0x1
# The special address 0xF8 is a broadcast address accepted by any pzem device,
# so if you use this address, make sure there is only one pzem device connected
# to the uart bus.
# address: 0xF8
modbus_id: mod_bus_pzem
command_throttle: 0ms
setup_priority: -10

2
components/sensor/scd4x.rst
View File

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

36
components/sensor/sdm_meter.rst
View File

@ -4,7 +4,7 @@ Eastron SDM Energy Monitor
.. seo::
:description: Instructions for setting up SDM power monitors.
:image: sdm220m.jpg
:keywords: SDM220M, SDM220, SDM630
:keywords: SDM230M, SDM220, SDM630, SDM120M, SDM72
The ``sdm_meter`` sensor platform allows you to use Eastron SDM modbus energy monitors
(`website <http://www.eastrongroup.com/product_detail.php?id=170&menu1=&menu2=>`__)
@ -14,12 +14,13 @@ with ESPHome.
:align: center
:width: 50.0%
SDM220M Energy Monitor.
SDM230M Energy Monitor.
The communication with this integration is done over a :ref:`UART bus <uart>` using the :ref:`Modbus protocol <modbus>`
over RS485 wiring. You will need an RS485 to UART converter for communication.
You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set
to some pins on your board and the baud rate set to 9600.
to some pins on your board and the baud rate set to 9600bps.
! For the SDM230M, SDM120M Energy Monitor the default factory baud rate is 2400bps. You either need to change the code to 2400bps for these models or change the settings on your Energy Meter For more information search for your model: (`eastron's website <https://www.eastroneurope.com/products/category/din-rail-mounted-metering>`__).
.. code-block:: yaml
@ -27,38 +28,38 @@ to some pins on your board and the baud rate set to 9600.
uart:
rx_pin: D1
tx_pin: D2
baud_rate: 9600
baud_rate: 9600 #if your energy meter is SDM230M or SDM120M than change the baud_rate: 2400
stop_bits: 1
sensor:
- platform: sdm_meter
phase_a:
current:
name: "SDM220M Current"
name: "SDM230M Current"
voltage:
name: "SDM220M Voltage"
name: "SDM230M Voltage"
active_power:
name: "SDM220M Power"
name: "SDM230M Power"
power_factor:
name: "SDM220M Power Factor"
name: "SDM230M Power Factor"
apparent_power:
name: "SDM220M Apparent Power"
name: "SDM230M Apparent Power"
reactive_power:
name: "SDM220M Reactive Power"
name: "SDM230M Reactive Power"
phase_angle:
name: "SDM220M Phase Angle"
name: "SDM230M Phase Angle"
frequency:
name: "SDM220M Frequency"
name: "SDM230M Frequency"
total_power:
name: "SDM220M Total Power"
name: "SDM230M Total Power"
import_active_energy:
name: "SDM220M Import Active Energy"
name: "SDM230M Import Active Energy"
export_active_energy:
name: "SDM220M Export Active Energy"
name: "SDM230M Export Active Energy"
import_reactive_energy:
name: "SDM220M Import Reactive Energy"
name: "SDM230M Import Reactive Energy"
export_reactive_energy:
name: "SDM220M Export Reactive Energy"
name: "SDM230M Export Reactive Energy"
update_interval: 60s
@ -113,3 +114,4 @@ See Also
- :ref:`sensor-filters`
- :apiref:`sdm220m/sdm220m.h`
- :ghedit:`Edit`

2
components/sensor/sgp4x.rst
View File

@ -27,7 +27,7 @@ The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for thi
# Example configuration entry
sensor:
- platform: sgp4x
- platform: sgp4x
voc:
name: "VOC Index"
nox:

40
components/sensor/sm300d2.rst
View File

@ -19,16 +19,24 @@ The ``sm300d2`` sensor platform allows you to use the SM300D2 7-in-1 Air Quality
:width: 50.0%
The SM300D2 sensor supports connections via UART or RS485. This platform only supports UART-connections.
Although the SM300D2 sensor supports connections via UART or RS485, this platform only supports UART
connections. The LCD module which is often sold with/for these sensor boards can work over either UART
or RS485, so you can use the LCD over RS485 and an ESP over UART at the same time (see
:ref:`note below <pins-note>` regarding powering everything).
Make sure you have a :ref:`UART bus <uart>` in your configuration with the ``rx_pin`` connected to the
TX pin of the sensor. The sensor does not support receiving data, so the ``tx_pin`` does not need to be
connected. The sensor expects the baud rate to be set at 9600.
sensor's TX pin. The sensor does not support receiving data, so the ``tx_pin`` does not need to be
connected. The UART bus should be set to a baud rate of 9600 to match the sensor's output. Setting the
``rx_pin``'s mode to ``INPUT_PULLDOWN`` may help improve reliability if you're regularly getting missed
or bad/incomplete readings.
.. code-block:: yaml
# Example configuration entry
uart:
rx_pin: D0
rx_pin:
number: D0
mode: INPUT_PULLDOWN
tx_pin: D1
baud_rate: 9600
@ -54,43 +62,43 @@ Configuration variables:
------------------------
- **co2** (**Required**): The CO₂ data from the sensor in parts per million (ppm).
- **co2** (**Required**): The information for the CO₂ sensor. Readings in parts per million (ppm).
- **name** (**Required**, string): The name of the CO₂ sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **formaldehyde** (**Required**): The formaldehyde data of the sensor in micrograms per cubic meter air (µg/m³).
- **formaldehyde** (**Required**): The information for the formaldehyde sensor. Readings in µg/m³.
- **name** (**Required**, string): The name of the formaldehyde 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**): The total volatile organic compounds (TVOC) data of the sensor in micrograms per cubic meter air (µg/m³).
- **tvoc** (**Required**): The information for the total volatile organic compounds (TVOC) sensor. Readings in µg/m³.
- **name** (**Required**, string): The name of 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>`.
- **pm_2_5** (**Required**): The PM2.5 data of the sensor in micrograms per cubic meter air (µg/m³).
- **pm_2_5** (**Required**): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm. Readings in µg/m³.
- **name** (**Required**, string): The name of the PM2.5 sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **pm_10_0** (**Required**): The PM10 data of the sensor in micrograms per cubic meter air (µg/m³).
- **pm_10_0** (**Required**): The information for the **Weight Concentration** sensor for coarse particles up to 10μm. Readings in µg/m³.
- **name** (**Required**, string): The name of the PM10 sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **temperature** (**Required**): The temperature data of the sensor in degrees celsius (°C).
- **temperature** (**Required**): The information for the temperature sensor. Readings in degrees celsius (°C).
- **name** (**Required**, string): The name of the temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **humidity** (**Required**): The humidity data of the sensor in percent relative humidity (%).
- **humidity** (**Required**): The information for the relative humidity sensor. Readings in %.
- **name** (**Required**, string): The name of the humidity sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
@ -110,10 +118,18 @@ Configuration variables:
Pins on the SM300D2. UART RX is not in use.
.. _pins-note:
.. note::
``5V`` should be connected to power supply (supported voltage is 4.8 V to 5.2 V), ``GD`` to ``GND`` pin
The board's ``GD`` pin must be connected to a ``GND`` pin on the ESP.
The sensor board requires between 4.8 and 5.2 volts via the ``5V`` pin in either the UART or RS485 socket, as they
are connected. If you're using a USB-powered ESP module with a 5V input pin (i.e. ``VIN``) exposed, you can choose
to connect the UART ``5V`` pin to the ESP's ``VIN`` and then power everything through either the LCD module or the
ESP module, with a single power cable. If you choose to power the ESP separately from the sensor board, leave the
UART ``5V`` pin unconnected.
See Also
--------

2
components/sensor/tcs34725.rst
View File

@ -46,8 +46,6 @@ as the color temperature in kelvin will show `0`.
name: "TCS34725 Illuminance"
color_temperature:
name: "TCS34725 Color Temperature"
gain: 1x
integration_time: 2.4ms
glass_attenuation_factor: 1.0
address: 0x29
update_interval: 60s

38
components/sensor/uptime.rst
View File

@ -23,44 +23,6 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
Human readable sensor
---------------------
The sensor reports uptime in seconds which is good for automations
but is hard to read for humans, this example creates a text sensor
with human readable output.
.. code-block:: yaml
# Example configuration entry
text_sensor:
- platform: template
name: Uptime Human Readable
id: uptime_human
icon: mdi:clock-start
sensor:
- platform: uptime
name: Uptime Sensor
id: uptime_sensor
update_interval: 60s
on_raw_value:
then:
- text_sensor.template.publish:
id: uptime_human
state: !lambda |-
int seconds = round(id(uptime_sensor).raw_state);
int days = seconds / (24 * 3600);
seconds = seconds % (24 * 3600);
int hours = seconds / 3600;
seconds = seconds % 3600;
int minutes = seconds / 60;
seconds = seconds % 60;
return (
(days ? to_string(days) + "d " : "") +
(hours ? to_string(hours) + "h " : "") +
(minutes ? to_string(minutes) + "m " : "") +
(to_string(seconds) + "s")
).c_str();
See Also
--------

2
components/sensor/xiaomi_ble.rst
View File

@ -6,7 +6,7 @@ Xiaomi Mijia BLE Sensors
:image: xiaomi_mijia_logo.jpg
:keywords: Xiaomi, Mi Home, Mijia, BLE, Bluetooth, HHCCJCY01, GCLS002, HHCCPOT002, LYWSDCGQ, LYWSD02, CGG1, LYWSD03MMC, CGD1, JQJCY01YM, MUE4094RT, WX08ZM, MHO, C401, MHOC401
The ``xiaomi_ble`` sensor platform lets you track the output of Xiaomi Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`. This component will track, for example, the temperature, humidity, moisture, conductivity, illuminance, formaldehyde, mosquito tablet and battery level of the device every time the sensor sends out a BLE broadcast. Contrary to other implementations, ``xiaomi_ble`` listens passively to advertisement packets and does not pair with the device. Hence ESPHome has no impact on battery life. Thus, if you only use such sensors, you can safely set ``active: false`` in ``esp32_ble_tracker`` configuration, to save from spamming your RF environment with useless scan requests.
The ``xiaomi_ble`` sensor platform lets you track the output of Xiaomi Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`. This component will track, for example, the temperature, humidity, moisture, conductivity, illuminance, formaldehyde, mosquito tablet and battery level of the device every time the sensor sends out a BLE broadcast. Contrary to other implementations, ``xiaomi_ble`` listens passively to advertisement packets and does not pair with the device. Hence ESPHome has no impact on battery life. Thus, if you only use such sensors, you can safely set ``scan_parameters.active: false`` in ``esp32_ble_tracker`` configuration, to save from spamming your RF environment with useless scan requests.
Supported Devices
-----------------

76
components/stepper/index.rst
View File

@ -273,82 +273,22 @@ Configuration variables:
Home Assistant Configuration
----------------------------
This component will not show up in the Home Assistant front-end (Overview) automatically because
Home Assistant does not support steppers natively.
You can add the stepper component code below to your Home Assistant configuration (``configuration.yaml``) to
be able to control the stepper from the front-end.
The easiest way to control your stepper from Home Assistant is to add a ``number`` to your ESPHome
configuration. See :ref:`Number <config-number>` for more information.
.. code-block:: yaml
# Add a slider control to Home Assistant to set an integer value
input_number:
stepper_control:
number:
- platform: template
name: Stepper Control
initial: 0
min: -1000
max: 1000
min_value: -100
max_value: 100
step: 1
mode: slider
# Do something when the slider changes
automation:
- alias: Write Stepper Value to ESP
trigger:
platform: state
entity_id: input_number.stepper_control
action:
# Replace livingroom with the name you gave the ESP
- service: esphome.livingroom_control_stepper
data_template:
target: '{{ trigger.to_state.state | int }}'
In the above code, "stepper_control" is the ID of a numeric input field. It must be unique and it is
used in the automation section as a reference name. The display name for this field is in
stepper_control's ``name`` key.
If you want your user interface to give you more control over your stepper controller, such as
setting the acceleration, deceleration, etc, then you can add more input fields after ``stepper_control``
but before ``automation``. They can be a simple number-entry field (mode: box) or a slider like this.
Each of these extra input fields needs an associated input parameter defined on the ESPHome device's
API service.
The automation section tells Home Assistant what to do when the slider changes. It needs a trigger
(state of the ``stepper_control`` slider) and an action. In the trigger section, ``entity_id`` must refer
back to the configuration ID that triggers the automation. For us, that is the ``stepper_control``
field in the ``input_number`` item. That's why the value is ``input_number.stepper_control``.
In the action section, the service name is vital to get right: it's the glue that connects Home Automation's
front-end to the ESPHome device configuration. While you might expect the syntax to be ``esphome.<your_device>.<api_service>``,
the correct syntax is to join the device ID to the API service ID with an underscore,
as in ``esphome.livingroom_control_stepper`` where "Livingroom" is a device in ESPHome and "control_stepper" is an
API service for that device.
The template string is used to get the "state" value from the ``target`` field (defined in the target section) on the
``input_number`` component of the Home Assistant front-end. This value is then passed to the API service as defined in
the ESPHome device's configuration. The ``data_template`` section lists one value for each of the input parameters on
the service being called by the automation. In our case, the ESPHome device has an API service with a single parameter,
"target". If you called this "my_target", then the last line above should be ``my_target: '{{ trigger.to_state.state | int }}'``.
Getting this linkage right is very important.
The following code needs to go in the ESPHome configuration file for this device. Above, we mention "API service"
a lot. This code is where that is defined. You may have already added it (or something similar). Note
that the input variable for the ``control_stepper`` service is called ``target``. That's what matches with the
automation configuration above. Also note that the variable ``target`` is defined as an integer. That means it
must be an integer number, not a string.
.. code-block:: yaml
# ESPHome configuration
api:
services:
- service: control_stepper
variables:
target: int
set_action:
then:
- stepper.set_target:
id: my_stepper
target: !lambda 'return target;'
target: !lambda 'return x;'
stepper:
- platform: ...

30
components/text_sensor/ethernet_info.rst Normal file
View File

@ -0,0 +1,30 @@
Ethernet Info Text Sensor
=========================
.. seo::
:description: Instructions for setting up Ethernet info text sensors.
:image: ethernet.svg
The ``ethernet_info`` text sensor platform exposes different Ethernet information
via text sensors.
.. code-block:: yaml
# Example configuration entry
text_sensor:
- platform: ethernet_info
ip_address:
name: ESP IP Address
Configuration variables:
------------------------
- **ip_address** (*Optional*): Expose the IP Address of the ESP as a text sensor. All options from
:ref:`Text Sensor <config-text_sensor>`.
See Also
--------
- :apiref:`ethernet_info/ethernet_info_text_sensor.h`
- :ghedit:`Edit`

5
components/text_sensor/homeassistant.rst
View File

@ -16,7 +16,7 @@ states from your Home Assistant instance using the :doc:`native API </components
name: "Weather Forecast From Home Assistant"
entity_id: sensor.weather_forecast
With Home Assistant 2021.6 or newer, entity state attributes can also be imported.
Entity state attributes can also be imported:
.. code-block:: yaml
@ -30,11 +30,10 @@ With Home Assistant 2021.6 or newer, entity state attributes can also be importe
Configuration variables:
------------------------
- **name** (**Required**, string): The name of the text sensor.
- **name** (*Optional*, string): The name of the text sensor.
- **entity_id** (**Required**, string): The entity ID to import from Home Assistant.
- **attribute** (*Optional*, string): The name of the state attribute to import from the
specified entity. The entity state is used when this option is omitted.
Requires Home Assistant 2021.6 or newer.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Text Sensor <config-text_sensor>`.

32
components/text_sensor/wl_134.rst Normal file
View File

@ -0,0 +1,32 @@
WL-134 Pet Tag Sensor
=====================
.. seo::
:description: Instructions for setting up WL-134 text sensors.
:image: fingerprint.svg
The ``wl_134`` text sensor platform exposes the last read pet tag as text sensor.
.. code-block:: yaml
# Example configuration entry
uart:
rx_pin: GPIO17
baud_rate: 9600
text_sensor:
- platform: wl_134
name: Transponder Code
reset: true
Configuration variables:
------------------------
- **reset** (*Optional*, boolean): Reset the text sensor state back to "" 1s after reading a tag. Defaults to ``false``.
- All options from :ref:`Text Sensor <config-text_sensor>`.
See Also
--------
- :apiref:`wl_134/wl_134.h`
- :ghedit:`Edit`

4
components/time.rst
View File

@ -57,7 +57,9 @@ This powerful automation can be used to run automations at specific intervals at
specific times of day. The syntax is a subset of the `crontab <https://crontab.guru/>`__ syntax.
There are two ways to specify time intervals: Either with using the ``seconds:``, ``minutes:``, ...
keys as seen below or using a cron expression like ``* /5 * * * *``.
keys as seen below or using a cron alike expression like ``* /5 * * * *``.
Be aware normal cron implementations does not know about seconds like this esphome implementation, therefore you got 6 fields (seconds,minutes,hours,dayofmonth,month,dayofweek).
Basically, the automation engine looks at your configured time schedule every second and
evaluates if the automation should run.

0
components/binary_sensor/images/xpt2046-full.jpg → components/touchscreen/images/xpt2046-full.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

2
components/touchscreen/index.rst
View File

@ -80,7 +80,7 @@ See Also
- :ref:`Binary Sensor Filters <binary_sensor-filters>`
- :doc:`Inkplate 6 Plus </components/display/inkplate6>`
- :doc:`EKTF2232 </components/touchscreen/ektf2232>`
- :doc:`XPT2046 </components/binary_sensor/xpt2046>`
- :doc:`XPT2046 </components/touchscreen/xpt2046>`
- :apiref:`touchscreen/touchscreen.h`
- :apiref:`touchscreen/binary_sensor/touchscreen_binary_sensor.h`
- :ghedit:`Edit`

132
components/binary_sensor/xpt2046.rst → components/touchscreen/xpt2046.rst
View File

@ -1,5 +1,5 @@
XPT2046 Touch Screen Controller
==================================
XPT2046 Touch Screen Controller (Updated version)
==================================================
.. seo::
:description: Instructions for setting up XPT2046 touch screen controller with ESPHome
@ -8,10 +8,7 @@ XPT2046 Touch Screen Controller
.. _xpt2046-component:
Component/Hub
-------------
The ``xpt2046`` component allows using the touch screen controllers
The ``xpt2046`` touchscreen platform allows using the touch screen controllers
based on the XPT2046 chip
(`datasheet <https://datasheetspdf.com/pdf-file/746665/XPTEK/XPT2046/1>`__,
`AZ-Delivery`_) with ESPHome. Many cheap LCD displays contain this controller.
@ -28,32 +25,20 @@ The :ref:`SPI <spi>` is required to be set up in your configuration for this sen
.. code-block:: yaml
# Example configuration entry
xpt2046:
id: touchscreen
touchscreen:
platform: xpt2046
id: my_touchscreen
cs_pin: 17
irq_pin: 16
interrupt_pin: 16
update_interval: 50ms
report_interval: 1s
threshold: 400
dimension_x: 240
dimension_y: 320
calibration_x_min: 3860
calibration_x_max: 280
calibration_y_min: 340
calibration_y_max: 3860
swap_x_y: false
binary_sensor:
- platform: xpt2046
xpt2046_id: touchscreen
id: touch_key0
x_min: 80
x_max: 160
y_min: 106
y_max: 212
on_state:
- lambda: 'ESP_LOGI("main", "key0: %s", (x ? "touch" : "release"));'
Configuration variables:
------------------------
@ -66,12 +51,12 @@ Base Configuration:
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The chip select pin.
Often marked ``T_CS`` on the board.
- **irq_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
- **interrupt_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The touch detection pin.
Often marked ``T_IRQ`` on the board. If not specified the component will use polling
via SPI.
via SPI. This key is renamed from **irq_pin**
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. If ``irq_pin`` is specified the touch will be detected nearly instantaneously and this setting
sensor. If ``interrupt_pin`` is specified the touch will be detected nearly instantaneously and this setting
will be used only for the release detection. Defaults to ``50ms``.
- **report_interval** (*Optional*, :ref:`config-time`): The interval to periodically
@ -79,12 +64,6 @@ Base Configuration:
- **threshold** (*Optional*, int): The value to detect the touch or release. Defaults to ``400``.
- **dimension_x** (*Optional*, int): The dimension of the display in the horizontal
direction. Usually in pixels but a percentage can be useful as well. Defaults to ``100``.
- **dimension_y** (*Optional*, int): The dimension of the display in the vertical
direction. Usually in pixels but a percentage can be useful as well. Defaults to ``100``.
- **calibration_x_min** (*Optional*, int): The raw value corresponding to the left
(or top if ``swap_x_y`` is specified) edge of the display. See :ref:`xpt2046-calibration`
for the process to calibrate the touch screen. Defaults to ``0``.
@ -100,65 +79,8 @@ Base Configuration:
- **swap_x_y** (*Optional*, boolean): If true the x and y axes are swapped. Defaults to ``false``.
- **on_state** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when the touch screen is pressed or released. See :ref:`xpt2046-on_state`.
- All other options from :ref:`config-touchscreen`.
.. _xpt2046-on_state:
``on_state`` Action
-------------------
This automation will be triggered when the XPT2046 touch screen detects a touch, a release
or periodically each ``report_interval`` while touched.
This trigger provides three arguments: ``x`` and ``y`` are of the type int and specify the
coordinates of the touch and a bool ``touched`` specifying whether a touch or release was
detected.
Additionally to the coordinates, the touch status and the raw values needed for the calibration
can be accessed as member variables.
The following code
.. code-block:: yaml
xpt2046:
on_state:
- lambda: |-
ESP_LOGI("main", "args x=%d, y=%d, touched=%s", x, y, (touched ? "touch" : "release"));
ESP_LOGI("main", "member x=%d, y=%d, touched=%d, x_raw=%d, y_raw=%d, z_raw=%d",
id(touchscreen).x,
id(touchscreen).y,
(int) id(touchscreen).touched,
id(touchscreen).x_raw,
id(touchscreen).y_raw,
id(touchscreen).z_raw
);
produces
.. code-block:: none
[20:17:37][I][main:065]: args x=145, y=261, touched=touch
[20:17:37][I][main:073]: member x=145, y=261, touched=1, x_raw=1686, y_raw=3218, z_raw=424
[20:17:37][I][main:065]: args x=145, y=261, touched=release
[20:17:37][I][main:073]: member x=145, y=261, touched=0, x_raw=0, y_raw=0, z_raw=0
Binary Sensor
-------------
The ``xpt2046`` binary sensor allows you to setup areas on the touch screen as virtual
buttons. First, setup a :ref:`xpt2046-component` and then use this binary sensor platform
to create individual binary sensors for each virtual button.
- **name** (*Optional*, string): The name for the binary sensor.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **xpt2046_id** (*Optional*, :ref:`config-id`): Specify the ID of the component the sensor is part of. Useful when you have more than one touch screen.
- **x_min** (**Required**, int): Left coordinate of the screen area to be detected as the virtual button.
- **x_max** (**Required**, int): Right coordinate of the screen area to be detected as the virtual button.
- **y_min** (**Required**, int): Top coordinate of the screen area to be detected as the virtual button.
- **y_max** (**Required**, int): Bottom coordinate of the screen area to be detected as the virtual button.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. _xpt2046-calibration:
@ -168,7 +90,7 @@ Calibration
To match the point of the touch to the display coordinates the touch screen has to be calibrated.
The XPT2046 component returns raw values in the 0 to 4095 range. Those raw values are available
as the ``x_raw`` and ``y_raw`` member variables and for example write them out as in the example
:ref:`xpt2046-on_state`. The goal of the calibration is to identify the raw values corresponding
:ref:`touchscreen-on_touch`. The goal of the calibration is to identify the raw values corresponding
to the edges of the screen.
The calibration assumes a display oriented in a way that you will be using it, i.e. your
@ -179,20 +101,17 @@ values nor ``swap_x_y``.
.. code-block:: yaml
# Touchscreen
xpt2046:
id: touchscreen
touchscreen:
platform: xpt2046
id: my_touchscreen
cs_pin: 17
irq_pin: 16
dimension_x: 240
dimension_y: 320
on_state:
on_touch:
- lambda: |-
if (touched)
ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%d",
id(touchscreen).x,
id(touchscreen).y,
id(touchscreen).x_raw,
id(touchscreen).y_raw
ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%0d",
id(my_touchscreen).x,
id(my_touchscreen).y,
id(my_touchscreen).x_raw,
id(my_touchscreen).y_raw
);
Get a stylus or a similar object, run the project and touch the corners of the screen at
@ -230,7 +149,8 @@ The vertical direction is fine. The configuration would thus be
.. code-block:: yaml
xpt2046:
touchscreen:
platform: xpt2046
calibration_x_min: 3848
calibration_x_max: 281
calibration_y_min: 347
@ -250,14 +170,14 @@ Note that the touch screen is not extremely precise and there might be nonlinear
or similar errors so don't expect a pixel-perfect precision. You can verify the touchpoint
using a display lambda similar to the following.
.. code-block:: none
.. code-block:: yaml
display:
- platform: ili9341
lambda: |-
it.fill(BLACK);
if (id(touchscreen).touched)
it.filled_circle(id(touchscreen).x, id(touchscreen).y, 10, RED);
if (id(my_touchscreen).touched)
it.filled_circle(id(my_touchscreen).x, id(my_touchscreen).y, 10, RED);
To be exact, the component does the following

4
components/tuya.rst
View File

@ -107,7 +107,7 @@ The type of ``x`` variable is depending on ``datapoint_type`` configuration vari
datapoint_type: raw
then:
- lambda: |-
ESP_LOGD("main", "on_datapoint_update %s", hexencode(x).c_str());
ESP_LOGD("main", "on_datapoint_update %s", format_hex_pretty(x).c_str());
id(voltage).publish_state((x[0] << 8 | x[1]) * 0.1);
id(current).publish_state((x[3] << 8 | x[4]) * 0.001);
id(power).publish_state((x[6] << 8 | x[7]) * 0.1);
@ -126,7 +126,7 @@ The type of ``x`` variable is depending on ``datapoint_type`` configuration vari
then:
- lambda: |-
if (x.type == tuya::TuyaDatapointType::RAW) {
ESP_LOGD("main", "on_datapoint_update %s", hexencode(x.value_raw).c_str());
ESP_LOGD("main", "on_datapoint_update %s", format_hex_pretty(x.value_raw).c_str());
} else {
ESP_LOGD("main", "on_datapoint_update %hhu", x.type);
}

2
components/web_server.rst
View File

@ -110,8 +110,10 @@ Force to turn off OTA function because the missing authentication.
# Example configuration entry V1
web_server:
port: 80
version: 1
ota: false
css_include: "../../../esphome-docs/_static/webserver-v1.min.css"
css_url: ""
js_include: "../../../esphome-docs/_static/webserver-v1.min.js"
js_url: ""

9
components/wifi.rst
View File

@ -120,6 +120,15 @@ devices name as the ssid with no password.
ap:
password: "W1PBGyrokfLz"
User Entered Credentials
------------------------
Some components such as :doc:`captive_portal`, :doc:`improv_serial` and :doc:`esp32_improv`
enable the user to send and save Wi-Fi credentials to the device. Beginning in 2022.11.0,
as long as no credentials are set in the config file, and firmware is uploaded without erasing
the flash (via OTA), the device will keep the saved credentials.
.. _wifi-manual_ip:
Manual IPs

6
conf.py
View File

@ -40,7 +40,7 @@ extensions = [
"github",
"seo",
"components",
"sitemap"
"sitemap",
]
# Add any paths that contain templates here, relative to this directory.
@ -67,9 +67,9 @@ author = "ESPHome"
# built documents.
#
# The short X.Y version.
version = "2022.9"
version = "2022.11"
# The full version, including alpha/beta/rc tags.
release = "2022.9.4"
release = "2022.11.3"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

7
cookbook/ble_itag.rst
View File

@ -55,6 +55,7 @@ Configuration example:
# a notification is received, the corresponding binary_sensor
# is briefly toggled.
- platform: ble_client
type: characteristic
ble_client_id: itag_black
name: "Black iTag btn"
service_uuid: 'ffe0'
@ -73,12 +74,18 @@ Configuration example:
# support this characteristic, you will see 'Unknown' in the
# HA frontend.
- platform: ble_client
type: characteristic
ble_client_id: itag_black
name: "Black iTag Battery"
service_uuid: '180f'
characteristic_uuid: '2a19'
icon: 'mdi:battery'
unit_of_measurement: '%'
# This entry queries polls the RSSI when the tag is connected.
- platform: ble_client
type: rssi
ble_client_id: itag_black
name: "Black iTag RSSI"
Explanation
-----------

80
cookbook/geiger-counter.rst Normal file
View File

@ -0,0 +1,80 @@
Geiger counter RadiationD v1.1 (CAJOE)
======================================
.. seo::
:description: Instructions for setting up RadiationD v1.1(CAJOE) sensor in ESPHome and calculate the current radation level.
:image: radiationD-v1-1-cajoe_small.jpg
:keywords: Radiation Geiger counter
With the help of :doc:`/components/sensor/pulse_counter` and the RadiationD v1.1(CAJOE) you can make your own Geiger counter, which will give you
a more or less precise messurement of the current radation level. But it should be good enough to warn you about critical events.
Assambly:
---------
.. figure:: images/radiationD-v1-1-cajoe_small.jpg
:align: center
:width: 100.0%
The first step is to connect the sensor.
You just need to connect the +5V, the ground and a GPIO pin to the ESP.
In my case I used the pin 34 for the signal. (The print on the PCB is wrong VIN is the signal.)
This setup should give you the pulse of each messurement or count. For more information check the Video of `Andreas Spiess <https://www.youtube.com/watch?v=K28Az3-gV7E>`__.
Housing:
*********
I just 3D printed an small housing the avoid touching the high voltage Geiger Mueller tube.
`Counter Tube Case <https://www.thingiverse.com/thing:5425224>`__
(The tube should not be in direct sunlight. So maybe you will need another case.)
Configuartion:
---------------
The block :doc:`/components/sensor/pulse_counter` will count the radation events per minute.
With the found specs of the tube you will be able to calculate the radiation in μSv/h.
It's just the counts per minute (CPM) times the factor of your Geiger Mueller tube you're using. It should be the J305ß, which comes with the PCB.
(To make sure - check your printing on the tube)
μSv/h = (CPM - Tube noise) * Factor
According to the video of `Andreas Spiess <https://www.youtube.com/watch?v=K28Az3-gV7E>`__ the tube should have about 12 CPM as background noise.
.. note::
The current version of the pack comes with the J305ß Geiger tube which detectes Beta and Gamma radiation. Specifications:
Manufacturer: North Optic Radiation Detection: β, γ Length: 111mm Diameter: 11mm Recommended Voltage: 350V Plateau Voltage: 360-440V
Sensitivy γ (60Co): 65cps/(μR/s)
Sensitivy γ (equivalent Sievert): 108cpm / (μSv/h)
Max cpm: 30000
cps/mR/h: 18
cpm/m/h: 1080
cpm/μSv/h: 123.147092360319
Factor: 0.00812037037037
`Source: opengeiger.de/LibeliumDoku.pdf <http://www.opengeiger.de/LibeliumDoku.pdf>`__.
.. code-block:: yaml
sensor:
- platform: pulse_counter
pin: 34
name: "Radiation"
unit_of_measurement: 'μSv/h'
count_mode:
rising_edge: DISABLE
falling_edge: INCREMENT
filters:
- offset: -12.0 # J305ß Geiger Mueller tube background noise 0.2 pulses / sec x 60 sec = 12 CPM (Counts per Minute)
- multiply: 0.00812037037037 # Factor: 0.00812037037037
See Also
--------
- :doc:`/components/sensor/pulse_counter`
- :ghedit:`Edit`

BIN
cookbook/images/radiationD-v1-1-cajoe_small.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

7
custom/custom_component.rst
View File

@ -49,6 +49,9 @@ And in YAML:
- lambda: |-
auto my_custom = new MyCustomComponent();
return {my_custom};
components:
- id: my_custom_id
Configuration variables:
@ -154,7 +157,7 @@ custom components that communicate using MQTT.
publish("the/other/topic", 42);
}
}
void on_json_message(JsonObject &root) {
void on_json_message(JsonObject root) {
if (!root.containsKey("key"))
return;
@ -162,7 +165,7 @@ custom components that communicate using MQTT.
// do something with Json Object
// publish JSON using lambda syntax
publish_json("the/other/json/topic", [=](JsonObject &root2) {
publish_json("the/other/json/topic", [=](JsonObject root2) {
root2["key"] = "Hello World";
});
}

60
devices/esp32.rst
View File

@ -1,60 +0,0 @@
Generic ESP32
=============
.. seo::
:description: Information about how to use generic ESP32 boards in ESPHome.
:image: esp32.svg
:keywords: ESP32
All devices based on the original ESP32 are supported by ESPHome. Simply select ``ESP32`` when
the ESPHome wizard asks you for your platform and choose a board type
from `this link <https://registry.platformio.org/platforms/platformio/espressif32/boards>`__ when the wizard
asks you for the board type.
.. code-block:: yaml
# Example configuration entry
esphome:
name: livingroom
esp32:
board: <BOARD_TYPE>
.. note::
Support for the ESP32-S2 and ESP32-C3 is currently in development.
The ESP32 boards often use the internal GPIO pin numbering on the board, this means that
you don't have to worry about other kinds of pin numberings, yay!
Some notes about the pins on the ESP32:
- ``GPIO0`` is used to determine the boot mode on startup. It should therefore not be pulled LOW
on startup to avoid booting into flash mode. You can, however, still use this as an output pin.
- ``GPIO34``-``GPIO39`` can not be used as outputs (even though GPIO stands for "general purpose input
**output**"...).
- ``GPIO32``-``GPIO39``: These pins can be used with the :doc:`/components/sensor/adc` to measure
voltages.
- ``GPIO2``: This pin is connected to the blue LED on the board. It also supports
the :doc:`touch pad binary sensor </components/binary_sensor/esp32_touch>` like some other
pins.
.. code-block:: yaml
# Example configuration entry
esphome:
name: livingroom
esp32:
board: <BOARD_TYPE>
binary_sensor:
- platform: gpio
name: "Pin GPIO23"
pin: GPIO23
See Also
--------
- :doc:`nodemcu_esp32`
- :ghedit:`Edit`

199
devices/esp8266.rst
View File

@ -1,199 +0,0 @@
Generic ESP8266
===============
.. seo::
:description: Instructions for using generic ESP8266s with ESPHome.
:image: esp8266.svg
:keywords: ESP8266
All ESP8266-based devices are supported by ESPHome. Simply select ``ESP8266`` when
the ESPHome wizard asks you for your platform and choose a board type
from `this link <https://registry.platformio.org/platforms/platformio/espressif8266/boards>`__ when the wizard
asks you for the board type.
.. code-block:: yaml
# Example configuration entry
esphome:
name: livingroom
esp8266:
board: <BOARD_TYPE>
Many boards have a pin numbering for the exposed pins that is different from the internally used
ones. ESPHome tries to map the silk-screen pin numbers into the internal pin numbers with a few
boards, but for generic ESP8266 boards it is often required to just use the internal pin numbers.
To do this, just prefix all pins with ``GPIO``, for example ``GPIO0`` for the pin with the internal pin
number 0.
Some notes on the pins:
- ``GPIO6`` - ``GPIO11``, ``GPIO0``, ``GPIO2`` and ``GPIO15`` are often already used by the internal
flash interface and boot mode detection. So it's best to avoid using these pins.
- ``GPIO17`` additionally has an ADC connected to it. See the :doc:`/components/sensor/adc`
to read voltages (in the range from 0 to 1.0V) on this pin.
.. code-block:: yaml
# Example configuration entry
esphome:
name: livingroom
esp8266:
board: nodemcuv2
binary_sensor:
- platform: gpio
name: "Pin GPIO17"
pin: GPIO17
Special Pins
------------
=================== =============================================
``GPIO0`` Controls Boot Mode
------------------- ---------------------------------------------
``GPIO1`` UART TX pin
------------------- ---------------------------------------------
``GPIO2`` Controls Boot Mode
------------------- ---------------------------------------------
``GPIO3`` UART RX pin
------------------- ---------------------------------------------
``GPIO6`` SDIO/Flash CLK pin
------------------- ---------------------------------------------
``GPIO7`` SDIO/Flash Data 0 pin
------------------- ---------------------------------------------
``GPIO8`` SDIO/Flash Data 1 pin
------------------- ---------------------------------------------
``GPIO9`` SDIO/Flash Data 2 pin (qio/qout only)
------------------- ---------------------------------------------
``GPIO10`` SDIO/Flash Data 3 pin (qio/qout only)
------------------- ---------------------------------------------
``GPIO11`` SDIO/Flash CMD pin
------------------- ---------------------------------------------
``GPIO12`` Attached to Hardware SPI controller MISO
------------------- ---------------------------------------------
``GPIO13`` Attached to Hardware SPI controller MOSI
------------------- ---------------------------------------------
``GPIO14`` Attached to Hardware SPI controller CLK
------------------- ---------------------------------------------
``GPIO15`` Controls Boot Mode; Attached to Hardware SPI
controller CS
------------------- ---------------------------------------------
``GPIO16`` Special pin that can be accessed from RTC,
and is Deep-Sleep wakeup pin
------------------- ---------------------------------------------
TOUT aka ``GPIO17`` ADC pin for measuring voltages, can only be
used as analog input pin
=================== =============================================
This means effectively only the following pins can be used as general purpose GPIO:
========== ============================== ==============================
**Pin** **Restrictions** **State after Reset**
---------- ------------------------------ ------------------------------
``GPIO0`` If HIGH on boot Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO2`` If HIGH on boot Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO4`` High Impedance
---------- ------------------------------ ------------------------------
``GPIO5`` High Impedance
---------- ------------------------------ ------------------------------
``GPIO6`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO12`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO13`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO14`` Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO15`` If LOW on boot Weak Pull Up
---------- ------------------------------ ------------------------------
``GPIO16`` Has pull-down (but no pull-up) Weak Pull Down
resistor
========== ============================== ==============================
Boot Modes
----------
On each boot, the ESP8266 will check three pins to determine in which boot mode to enter.
There are three boot modes:
========================= ========= ========= ========== ==============
**Mode** ``GPIO0`` ``GPIO2`` ``GPIO15`` ``boot mode:``
------------------------- --------- --------- ---------- --------------
Boot from Flash (normal) HIGH HIGH LOW 3
------------------------- --------- --------- ---------- --------------
Download Code from UART LOW HIGH LOW 1
------------------------- --------- --------- ---------- --------------
Boot from SD-Card ANY ANY HIGH 4-7
========================= ========= ========= ========== ==============
You can identify these on boot-up by looking at the UART output, the first number
in the ``boot mode:`` line tells you what mode was selected
.. code-block:: text
ets Jan 8 2013,rst cause:4, boot mode:(3,6)
The first lines when viewing the UART logs might have unrecognized characters. This is
because the effective baudrate of the ESP8266 bootloader is 74800, whereas the program uses 115200.
Reset Causes
------------
Additionally, the first line also contains the **reset cause**.
These reset causes `are documented
<https://www.espressif.com/sites/default/files/documentation/esp8266_reset_causes_and_common_fatal_exception_causes_en.pdf>`__:
== ===================================
0 Undefined
-- -----------------------------------
1 Power On Reboot
-- -----------------------------------
2 External reset or deep-sleep wakeup
-- -----------------------------------
4 Hardware WDT reset
== ===================================
After a software reset, the reset cause will not change.
Electrical Characteristics
--------------------------
=========================================================== =========== =========== =========== ===========
**Parameter** **Min.** **Typical** **Max.** **Unit**
----------------------------------------------------------- ----------- ----------- ----------- -----------
Operating Temperature -40 125 °C
----------------------------------------------------------- ----------- ----------- ----------- -----------
Working Voltage ``V_IO`` 2.5 3.3 3.6 V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_IL`` - INPUT voltage level to be considered LOW -0.3 0.25*V_IO V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_IH`` - INPUT voltage level to be considered HIGH 0.75*V_IO 3.6 V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_OL`` - OUTPUT voltage level for LOW 0.1*V_IO V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``V_OH`` - OUTPUT voltage level for HIGH 0.8*V_IO V
----------------------------------------------------------- ----------- ----------- ----------- -----------
``I_MAX`` - Maximum current for GPIO 12 mA
----------------------------------------------------------- ----------- ----------- ----------- -----------
Power Consumption in Deep Sleep 20 µA
----------------------------------------------------------- ----------- ----------- ----------- -----------
Power Consumption in Active Mode 120 mA
=========================================================== =========== =========== =========== ===========
Source: `ESP8266EX datasheet <https://www.espressif.com/sites/default/files/documentation/0a-esp8266ex_datasheet_en.pdf>`__
The internal pull up/down resistors have values of 30kΩ to 100kΩ
(`source <https://bbs.espressif.com/viewtopic.php?t=1079>`__).
See Also
--------
- :doc:`nodemcu_esp8266`
- :ghedit:`Edit`

2
devices/nodemcu_esp32.rst
View File

@ -61,6 +61,6 @@ Note that in certain conditions you *can* use the pins marked as ``INTERNAL`` in
See Also
--------
- :doc:`esp32`
- :doc:`/components/esp32`
- :doc:`nodemcu_esp8266`
- :ghedit:`Edit`

2
devices/nodemcu_esp8266.rst
View File

@ -73,6 +73,6 @@ Note that in certain conditions you *can* use the pins marked as ``INTERNAL`` in
See Also
--------
- :doc:`esp8266`
- :doc:`/components/esp8266`
- :doc:`nodemcu_esp32`
- :ghedit:`Edit`

4
devices/sonoff.rst
View File

@ -5,7 +5,7 @@ Generic Sonoff
:description: Instructions for using generic Sonoff devices with ESPHome.
:image: sonoff.svg
In principle ESPHome supports all Sonoff devices, but as these devices are quite cheap
ESPHome supports Sonoff devices with ESP based chips inside, but as these devices are quite cheap
and shipping from China takes a long time, I've only set up dedicated guides for the
:doc:`Sonoff S20 <sonoff_s20>` and :doc:`Sonoff 4CH <sonoff_4ch>`.
@ -421,5 +421,5 @@ See Also
- :doc:`sonoff_s20`
- :doc:`sonoff_4ch`
- :doc:`sonoff_basic`
- :doc:`esp8266`
- :doc:`/components/esp8266`
- :ghedit:`Edit`

59
guides/automations.rst
View File

@ -712,9 +712,45 @@ Configuration variables:
- **max_runs** (*Optional*, int): Allows limiting the maxiumun number of runs when using script
modes ``queued`` and ``parallel``, use value ``0`` for unlimited runs. Defaults to ``0``.
- **parameters** (*Optional*, :ref:`Script Parameters <script-parameters>`): A script can define one
or more parameters that must be provided in order to execute. All parameters defined here are
mandatory and must be given when calling the script.
- **then** (**Required**, :ref:`Action <config-action>`): The action to perform.
.. _script-parameters:
``Script Parameters``
---------------------
Scripts can be defined with parameters. The arguments given when calling the script can be used within
the script's lambda actions. To define the parameters, add the parameter names under `parameters:` key
and specify the data type for that parameter.
Supported data types:
* `bool`: A boolean true/false. C++ type: `bool`
* `int`: An integer. C++ type: `int32_t`
* `float`: A floating point number. C++ type: `float`
* `string`: A string. C++ type: `std::string`
Each of these also exist in array form:
* `bool[]`: An array of boolean values. C++ type: `std::vector<bool>`
* Same for other types.
.. code-block:: yaml
script:
- id: blink_light
parameters:
delay_ms: int
then:
- light.turn_on: status_light
# The param delay_ms is accessible using a lambda
- delay: !lambda return delay_ms;
- light.turn_off: status_light
.. _script-execute_action:
``script.execute`` Action
@ -729,12 +765,17 @@ script was already running.
on_...:
then:
- script.execute: my_script
# Calling a non-parameterised script in a lambda
- lambda: id(my_script).execute();
or as lambda
# Calling a script with parameters
- script.execute:
id: blink_light
delay_ms: 500
.. code-block:: yaml
lambda: 'id(my_script).execute();
# Calling a parameterised script inside a lambda
- lambda: id(blink_light)->execute(1000);
.. _script-stop_action:
@ -795,13 +836,7 @@ of the script are running in parallel, this will block until all of them have te
- script.execute: my_script
- script.wait: my_script
or as lambda
.. code-block:: yaml
lambda: |-
id(my_script).execute();
id(my_script).wait();
This can't be used in a lambda as it would block all functioning of the device. The script wouldn't even get to run.
.. _script-is_running_condition:
@ -810,7 +845,7 @@ or as lambda
This :ref:`condition <config-condition>` allows you to check if a given script is running.
In case scripts are run in ``parallel``, this condition only tells you if at least one script
of the given id is running, not how many.
of the given id is running, not how many. Not designed for use with :ref:`while <while_action>`, instead try :ref:`script.wait <script-wait_action>`.
.. code-block:: yaml

26
guides/contributing.rst
View File

@ -681,32 +681,6 @@ Standard for the esphome-core codebase:
ESPHome via Gitpod
******************
An alternative to a local checkout and build is doing so via `Gitpod <https://www.gitpod.io>`__.
ESPHome will be installed for you and the dashboard wizard will run on startup.
You can also run the steps manually.
.. code-block:: bash
python setup.py install
To start a command line wizard, run
.. code-block:: bash
python esphome my_configuration.yaml wizard
To get the web-based dashboard, use
.. code-block:: bash
python esphome my_configuration.yaml dashboard
and allow exposing the web app at port 6052.
See Also
--------

3
guides/creators.rst
View File

@ -49,6 +49,9 @@ Example configuration
# In combination with the `ap` this allows the user
# to provision wifi credentials to the device.
captive_portal:
# Optionally, preserve provisioned credentials
# over subsequent OTA updates.
keep_user_credentials: true
# Sets up Bluetooth LE (Only on ESP32) to allow the user
# to provision wifi credentials to the device.

1
guides/diy.rst
View File

@ -56,6 +56,7 @@ Blog Posts & Videos
- `ESP32 AM312 motion sensor : light automation <https://omarghader.github.io/esp32-am312-pir-motion-sensor/>`__ by `Omar GHADER <https://omarghader.github.io/post>`__
- `Little thermostat based on AZ-Touch hardware and esphome <https://github.com/ingbenna/AZ-Touch_esphome_thermostat/>`_ by ingbenna
- `Converting a Carro Home DC Fan to ESPHome <https://1projectaweek.com/blog/2022/2/8/converting-a-carro-home-dc-fan-to-esp-home>`__ by `Bill Church <https://1projectaweek.com>`__
- `Automated Coffee Bean Roaster <https://hackaday.io/project/186852-automated-coffee-bean-roaster>`__ by `brooksben11 <https://hackaday.io/brooksben11>`__
Custom Components & Code
------------------------

2
guides/faq.rst
View File

@ -385,7 +385,7 @@ And a docker compose file looks like this:
Notes on disabling mDNS
------------------------------------------------------------------------------
Some of ESPHome's functionalities rely on mDNS, so naturally :ref:`disabling <wifi-configuration_variables>` it will cause these features to stop working.
Some of ESPHome's functionalities rely on mDNS, so naturally :doc:`disabling </components/mdns>` it will cause these features to stop working.
Generally speaking, disabling mDNS without setting a :ref:`static IP address <wifi-manual_ip>` (or a static DHCP lease) is bound to cause problems. This is due to the fact that mDNS is used to find the IP address of each ESPHome nodes.
- You will not be able to use the node's hostname to ping, find it's IP address or connect to it.

4
guides/getting_started_hassio.rst
View File

@ -76,6 +76,10 @@ The configuration files for ESPHome can be found and edited under ``<HOME_ASSIST
For example the configuration for the ``garage-door`` node in the picture above can be found
in ``/config/esphome/garage-door.yaml``.
.. note::
Since Home Assistant add-ons run as indvidual containers, accessing these through command line is not very straightforward, but it's possible. To do that, install Home Assistant's SSH addon, configure a username and a password, and disable `Protection Mode` (please assess the risks you take with that). Then, for example to access the logs form a device through an SSH client, log in, and you can use a command like `docker exec -it addon_15ef4d2f_esphome esphome logs /config/esphome/garage-door.yaml`. See :doc:`getting_started_command_line` for more.
Now go ahead and use one of the :ref:`devices guides <devices>` to extend your configuration.
Adding some (basic) features

8
guides/migrate_espeasy.rst
View File

@ -47,12 +47,8 @@ Happy Hacking!
See Also
--------
- :doc:`/devices/nodemcu_esp8266`
- :doc:`/devices/nodemcu_esp32`
- :doc:`/devices/esp8266`
- :doc:`/devices/esp32`
- :doc:`/devices/sonoff_s20`
- :doc:`/devices/sonoff_4ch`
- :doc:`/components/esp8266`
- :doc:`/components/esp32`
- :doc:`migrate_espurna`
- :doc:`migrate_sonoff_tasmota`
- :ghedit:`Edit`

8
guides/migrate_espurna.rst
View File

@ -52,12 +52,8 @@ Happy Hacking!
See Also
--------
- :doc:`/devices/nodemcu_esp8266`
- :doc:`/devices/nodemcu_esp32`
- :doc:`/devices/esp8266`
- :doc:`/devices/esp32`
- :doc:`/devices/sonoff_s20`
- :doc:`/devices/sonoff_4ch`
- :doc:`/components/esp8266`
- :doc:`/components/esp32`
- :doc:`migrate_espeasy`
- :doc:`migrate_sonoff_tasmota`
- :ghedit:`Edit`

14
guides/migrate_sonoff_tasmota.rst
View File

@ -11,8 +11,7 @@ ESPHome create a binary for you and then upload that in the Tasmota web interfac
Getting the Binary
------------------
First follow the guides for the :ref:`different supported devices <devices>` and create a configuration
file. Then, generate and download the binary:
First create a configuration for your device. Then, generate and download the legacy binary:
- **Using the Home Assistant add-on/dashboard**: Just click the ``COMPILE``
button, wait for the compilation to end and press the ``DOWNLOAD BINARY``
@ -60,17 +59,12 @@ Happy Hacking!
.. note::
If you are using Tasmota 8+ and get an error after uploading the firmware, go to the console and type ```SetOption78 1```, then restart the device and try the firmware again.
See Also
--------
- :doc:`/devices/sonoff_s20`
- :doc:`/devices/sonoff_4ch`
- :doc:`/devices/sonoff`
- :doc:`/devices/nodemcu_esp8266`
- :doc:`/devices/nodemcu_esp32`
- :doc:`/devices/esp8266`
- :doc:`/devices/esp32`
- :doc:`/components/esp8266`
- :doc:`/components/esp32`
- :doc:`migrate_espurna`
- :doc:`migrate_espeasy`
- :ghedit:`Edit`

57
guides/supporters.rst
View File

@ -17,10 +17,10 @@ Contributors
(in alphabetical order)
- `0hax (@0hax) <https://github.com/0hax>`__
- `Nikola (@0nikola1) <https://github.com/0nikola1>`__
- `0x0a11c0de (@0x0a11c0de) <https://github.com/0x0a11c0de>`__
- `Tercio Filho (@0x3333) <https://github.com/0x3333>`__
- `2016for (@2016for) <https://github.com/2016for>`__
- `2mikrobi (@2mikrobi) <https://github.com/2mikrobi>`__
- `Pavel Golovin (@31337Ghost) <https://github.com/31337Ghost>`__
- `David Martin (@3ative) <https://github.com/3ative>`__
- `Alessandro Campolo (@a13ssandr0) <https://github.com/a13ssandr0>`__
@ -55,7 +55,6 @@ Contributors
- `Alex Iribarren (@alexiri) <https://github.com/alexiri>`__
- `Alex Mekkering (@AlexMekkering) <https://github.com/AlexMekkering>`__
- `Alex (@alexyao2015) <https://github.com/alexyao2015>`__
- `alva (@alva-seal) <https://github.com/alva-seal>`__
- `Andreas Mandel (@amandel) <https://github.com/amandel>`__
- `Amish Vishwakarma (@amishv) <https://github.com/amishv>`__
- `Jason Nader (@ammgws) <https://github.com/ammgws>`__
@ -106,6 +105,7 @@ Contributors
- `Viktr (@BbIKTOP) <https://github.com/BbIKTOP>`__
- `J. Nick Koston (@bdraco) <https://github.com/bdraco>`__
- `Maxim Ocheretianko (@bearpawmaxim) <https://github.com/bearpawmaxim>`__
- `Benjamin Freeman (@Beetix) <https://github.com/Beetix>`__
- `Benno Pütz (@bennop) <https://github.com/bennop>`__
- `Benoit3 (@Benoit3) <https://github.com/Benoit3>`__
- `Ben Suffolk (@bensuffolk) <https://github.com/bensuffolk>`__
@ -137,6 +137,7 @@ Contributors
- `Brett Profitt (@brettp) <https://github.com/brettp>`__
- `Brian Hanifin (@brianhanifin) <https://github.com/brianhanifin>`__
- `brianrjones69 (@brianrjones69) <https://github.com/brianrjones69>`__
- `Ben Brooks (@brooksben11) <https://github.com/brooksben11>`__
- `buddydvd (@buddydvd) <https://github.com/buddydvd>`__
- `Jon Little (@burundiocibu) <https://github.com/burundiocibu>`__
- `buxtronix (@buxtronix) <https://github.com/buxtronix>`__
@ -152,6 +153,7 @@ Contributors
- `Ciprian Constantinescu (@cciprian5) <https://github.com/cciprian5>`__
- `Marco (@cdrfun) <https://github.com/cdrfun>`__
- `Cellie (@CelliesProjects) <https://github.com/CelliesProjects>`__
- `Chris Feenstra (@cfeenstra1024) <https://github.com/cfeenstra1024>`__
- `Kostas Chatzikokolakis (@chatziko) <https://github.com/chatziko>`__
- `chris-jennings (@chris-jennings) <https://github.com/chris-jennings>`__
- `Chris (@chrismaki) <https://github.com/chrismaki>`__
@ -166,6 +168,7 @@ Contributors
- `code-review-doctor (@code-review-doctor) <https://github.com/code-review-doctor>`__
- `CODeRUS (@CODeRUS) <https://github.com/CODeRUS>`__
- `Cody James (@codyjamestechnical) <https://github.com/codyjamestechnical>`__
- `Colin Leroy-Mira (@colinleroy) <https://github.com/colinleroy>`__
- `Conclusio (@Conclusio) <https://github.com/Conclusio>`__
- `John Coggeshall (@coogle) <https://github.com/coogle>`__
- `James Crook (@cooljimy84) <https://github.com/cooljimy84>`__
@ -175,11 +178,13 @@ Contributors
- `Dmitry Berezovsky (@corvis) <https://github.com/corvis>`__
- `Cougar (@Cougar) <https://github.com/Cougar>`__
- `Connor Prussin (@cprussin) <https://github.com/cprussin>`__
- `Corey Rice (@crice009) <https://github.com/crice009>`__
- `cryptelli (@cryptelli) <https://github.com/cryptelli>`__
- `cstaahl (@cstaahl) <https://github.com/cstaahl>`__
- `Chris Talkington (@ctalkington) <https://github.com/ctalkington>`__
- `Massimo Cetra (@ctrix) <https://github.com/ctrix>`__
- `cvwillegen (@cvwillegen) <https://github.com/cvwillegen>`__
- `Christoph Wempe (@CWempe) <https://github.com/CWempe>`__
- `cwitting (@cwitting) <https://github.com/cwitting>`__
- `Alex Solomaha (@CyanoFresh) <https://github.com/CyanoFresh>`__
- `Luar Roji (@cyberplant) <https://github.com/cyberplant>`__
@ -210,31 +215,30 @@ Contributors
- `Donovan Baarda (@dbaarda) <https://github.com/dbaarda>`__
- `David Buezas (@dbuezas) <https://github.com/dbuezas>`__
- `dckiller51 (@dckiller51) <https://github.com/dckiller51>`__
- `Daniel Correa Lobato (@dclobato) <https://github.com/dclobato>`__
- `Debashish Sahu (@debsahu) <https://github.com/debsahu>`__
- `declanshanaghy (@declanshanaghy) <https://github.com/declanshanaghy>`__
- `Maximilian (@DeerMaximum) <https://github.com/DeerMaximum>`__
- `definitio (@definitio) <https://github.com/definitio>`__
- `Christiaan Blom (@Deinara) <https://github.com/Deinara>`__
- `Mickaël Le Baillif (@demikl) <https://github.com/demikl>`__
- `Dennis (@dennisvbussel) <https://github.com/dennisvbussel>`__
- `dentra (@dentra) <https://github.com/dentra>`__
- `Davide Depau (@Depau) <https://github.com/Depau>`__
- `Davide Depau (@depau) <https://github.com/depau>`__
- `dependabot[bot] (@dependabot[bot]) <https://github.com/dependabot[bot]>`__
- `Joeri Colman (@depuits) <https://github.com/depuits>`__
- `Destix (@Destix) <https://github.com/Destix>`__
- `Develo (@devyte) <https://github.com/devyte>`__
- `Dezorian (@Dezorian) <https://github.com/Dezorian>`__
- `dgtal1 (@dgtal1) <https://github.com/dgtal1>`__
- `Dan Halbert (@dhalbert) <https://github.com/dhalbert>`__
- `Alain Turbide (@Dilbert66) <https://github.com/Dilbert66>`__
- `Mark (@Diramu) <https://github.com/Diramu>`__
- `Dirk Heinke (@DirkHeinke) <https://github.com/DirkHeinke>`__
- `Dirk Jahnke (@dirkj) <https://github.com/dirkj>`__
- `Johann V. (@divinitas) <https://github.com/divinitas>`__
- `djwlindenaar (@djwlindenaar) <https://github.com/djwlindenaar>`__
- `Marcos Pérez Ferro (@djwmarcx) <https://github.com/djwmarcx>`__
- `Dan Mannock (@dmannock) <https://github.com/dmannock>`__
- `Dmitriy Lopatko (@dmitriy5181) <https://github.com/dmitriy5181>`__
- `dmkif (@dmkif) <https://github.com/dmkif>`__
- `Farzad E. (@dnetguru) <https://github.com/dnetguru>`__
- `DrZoid (@docteurzoidberg) <https://github.com/docteurzoidberg>`__
- `Dominik (@DomiStyle) <https://github.com/DomiStyle>`__
@ -247,7 +251,6 @@ Contributors
- `Drew Perttula (@drewp) <https://github.com/drewp>`__
- `drmpf (@drmpf) <https://github.com/drmpf>`__
- `DrRob (@DrRob) <https://github.com/DrRob>`__
- `drug123 (@drug123) <https://github.com/drug123>`__
- `Daniel Müller (@dtmuller) <https://github.com/dtmuller>`__
- `dubit0 (@dubit0) <https://github.com/dubit0>`__
- `Sergey V. DUDANOV (@dudanov) <https://github.com/dudanov>`__
@ -268,7 +271,6 @@ Contributors
- `Eike (@ei-ke) <https://github.com/ei-ke>`__
- `Elazar Leibovich (@elazarl) <https://github.com/elazarl>`__
- `Elkropac (@Elkropac) <https://github.com/Elkropac>`__
- `elyorkhakimov (@elyorkhakimov) <https://github.com/elyorkhakimov>`__
- `EmbeddedDevver (@EmbeddedDevver) <https://github.com/EmbeddedDevver>`__
- `EmmanuelLM (@EmmanuelLM) <https://github.com/EmmanuelLM>`__
- `Emory Dunn (@emorydunn) <https://github.com/emorydunn>`__
@ -297,12 +299,11 @@ Contributors
- `Christian Ferbar (@ferbar) <https://github.com/ferbar>`__
- `FeuerSturm (@FeuerSturm) <https://github.com/FeuerSturm>`__
- `Frank Riley (@fhriley) <https://github.com/fhriley>`__
- `fkirill (@fkirill) <https://github.com/fkirill>`__
- `Frédéric Jouault (@fjouault) <https://github.com/fjouault>`__
- `Sean Vig (@flacjacket) <https://github.com/flacjacket>`__
- `Diego Elio Pettenò (@Flameeyes) <https://github.com/Flameeyes>`__
- `Flaviu Tamas (@flaviut) <https://github.com/flaviut>`__
- `风飘雨 (@flyrainning) <https://github.com/flyrainning>`__
- `foxsam21 (@foxsam21) <https://github.com/foxsam21>`__
- `Fractal147 (@Fractal147) <https://github.com/Fractal147>`__
- `Francis-labo (@Francis-labo) <https://github.com/Francis-labo>`__
- `Francisk0 (@Francisk0) <https://github.com/Francisk0>`__
@ -348,6 +349,7 @@ Contributors
- `Stefan Grufman (@GruffyPuffy) <https://github.com/GruffyPuffy>`__
- `gsexton (@gsexton) <https://github.com/gsexton>`__
- `Gabriel Sieben (@gsieben) <https://github.com/gsieben>`__
- `Jadson Santos (@gtjadsonsantos) <https://github.com/gtjadsonsantos>`__
- `Guillaume DELVIT (@guiguid) <https://github.com/guiguid>`__
- `guillempages (@guillempages) <https://github.com/guillempages>`__
- `Guyohms (@Guyohms) <https://github.com/Guyohms>`__
@ -367,6 +369,7 @@ Contributors
- `HepoH3 (@HepoH3) <https://github.com/HepoH3>`__
- `Hermann Kraus (@herm) <https://github.com/herm>`__
- `Hamish Moffatt (@hmoffatt) <https://github.com/hmoffatt>`__
- `Marcel Hoppe (@hobbypunk90) <https://github.com/hobbypunk90>`__
- `Sebastian Raff (@hobbyquaker) <https://github.com/hobbyquaker>`__
- `MoA (@honomoa) <https://github.com/honomoa>`__
- `Hopperpop (@Hopperpop) <https://github.com/Hopperpop>`__
@ -388,6 +391,8 @@ Contributors
- `imgbot[bot] (@imgbot[bot]) <https://github.com/imgbot[bot]>`__
- `ImSorryButWho (@ImSorryButWho) <https://github.com/ImSorryButWho>`__
- `Lorenzo Ortiz (@Infinitte) <https://github.com/Infinitte>`__
- `Dom (@Ing-Dom) <https://github.com/Ing-Dom>`__
- `Ingurum (@Ingurum) <https://github.com/Ingurum>`__
- `Ivo Roefs (@Ironirc) <https://github.com/Ironirc>`__
- `irtimaled (@irtimaled) <https://github.com/irtimaled>`__
- `Ingo Theiss (@itn3rd77) <https://github.com/itn3rd77>`__
@ -399,6 +404,7 @@ Contributors
- `James Braid (@jamesbraid) <https://github.com/jamesbraid>`__
- `James Duke (@jamesduke) <https://github.com/jamesduke>`__
- `James Gao (@jamesgao) <https://github.com/jamesgao>`__
- `James Lakin (@jamesorlakin) <https://github.com/jamesorlakin>`__
- `Juraj Andrássy (@JAndrassy) <https://github.com/JAndrassy>`__
- `Jan Grewe (@jangrewe) <https://github.com/jangrewe>`__
- `János Rusiczki (@janosrusiczki) <https://github.com/janosrusiczki>`__
@ -414,7 +420,6 @@ Contributors
- `Jonathan Burns (@jburns20) <https://github.com/jburns20>`__
- `James Callaghan (@jcallaghan) <https://github.com/jcallaghan>`__
- `Josh Willox (@jcwillox) <https://github.com/jcwillox>`__
- `jddonovan (@jddonovan) <https://github.com/jddonovan>`__
- `JeeCee1 (@JeeCee1) <https://github.com/JeeCee1>`__
- `jeff-h (@jeff-h) <https://github.com/jeff-h>`__
- `Jeffrey Borg (@jeffborg) <https://github.com/jeffborg>`__
@ -428,6 +433,7 @@ Contributors
- `Joe (@jhansche) <https://github.com/jhansche>`__
- `Jim Bauwens (@jimbauwens) <https://github.com/jimbauwens>`__
- `jimtng (@jimtng) <https://github.com/jimtng>`__
- `Jeroen (@jjansen85) <https://github.com/jjansen85>`__
- `Jérémy JOURDIN (@JJK801) <https://github.com/JJK801>`__
- `Jonathan Jefferies (@jjok) <https://github.com/jjok>`__
- `John K. Luebs (@jkl1337) <https://github.com/jkl1337>`__
@ -440,19 +446,19 @@ Contributors
- `Johan van der Kuijl (@johanvanderkuijl) <https://github.com/johanvanderkuijl>`__
- `Johboh (@Johboh) <https://github.com/Johboh>`__
- `John Erik Halse (@johnerikhalse) <https://github.com/johnerikhalse>`__
- `John Moxley (@johnmoxley) <https://github.com/johnmoxley>`__
- `JonasEr (@JonasEr) <https://github.com/JonasEr>`__
- `Jonathan Adams (@jonathanadams) <https://github.com/jonathanadams>`__
- `Jonathan Treffler (@JonathanTreffler) <https://github.com/JonathanTreffler>`__
- `JonnyaiR (@jonnyair) <https://github.com/jonnyair>`__
- `Jonathan V (@jonofmac) <https://github.com/jonofmac>`__
- `Joppy (@JoppyFurr) <https://github.com/JoppyFurr>`__
- `joseph douce (@josephdouce) <https://github.com/josephdouce>`__
- `Joshua Spence (@joshuaspence) <https://github.com/joshuaspence>`__
- `Joscha Wagner (@jowgn) <https://github.com/jowgn>`__
- `Javier Peletier (@jpeletier) <https://github.com/jpeletier>`__
- `jsuanet (@jsuanet) <https://github.com/jsuanet>`__
- `James Szalay (@jtszalay) <https://github.com/jtszalay>`__
- `junnikokuki (@junnikokuki) <https://github.com/junnikokuki>`__
- `Julie Koubová (@juliekoubova) <https://github.com/juliekoubova>`__
- `Justahobby01 (@Justahobby01) <https://github.com/Justahobby01>`__
- `Mike Ryan (@justfalter) <https://github.com/justfalter>`__
- `Justin Gerhardt (@justin-gerhardt) <https://github.com/justin-gerhardt>`__
@ -483,10 +489,8 @@ Contributors
- `Kevin Lewis (@kll) <https://github.com/kll>`__
- `Koen Vervloesem (@koenvervloesem) <https://github.com/koenvervloesem>`__
- `Petr Vraník (@konikvranik) <https://github.com/konikvranik>`__
- `korellas (@korellas) <https://github.com/korellas>`__
- `Kevin Pelzel (@kpelzel) <https://github.com/kpelzel>`__
- `Karl Q. (@kquinsland) <https://github.com/kquinsland>`__
- `krahabb (@krahabb) <https://github.com/krahabb>`__
- `Kodey Converse (@krconv) <https://github.com/krconv>`__
- `KristopherMackowiak (@KristopherMackowiak) <https://github.com/KristopherMackowiak>`__
- `kroimon (@kroimon) <https://github.com/kroimon>`__
@ -499,6 +503,7 @@ Contributors
- `Kyle Manna (@kylemanna) <https://github.com/kylemanna>`__
- `Kalashnikov Ilya (@l1bbcsg) <https://github.com/l1bbcsg>`__
- `Limor "Ladyada" Fried (@ladyada) <https://github.com/ladyada>`__
- `Lakshantha Dissanayake (@lakshanthad) <https://github.com/lakshanthad>`__
- `Luca Adrian L (@lal12) <https://github.com/lal12>`__
- `Fredrik Lindqvist (@Landrash) <https://github.com/Landrash>`__
- `Laszlo Gazdag (@lazlyhu) <https://github.com/lazlyhu>`__
@ -512,6 +517,7 @@ Contributors
- `Lubos Horacek (@lhoracek) <https://github.com/lhoracek>`__
- `Juraj Liso (@LiJu09) <https://github.com/LiJu09>`__
- `lingex (@lingex) <https://github.com/lingex>`__
- `lkomurcu (@lkomurcu) <https://github.com/lkomurcu>`__
- `Lazar Obradovic (@lobradov) <https://github.com/lobradov>`__
- `Lode Vermeiren (@lodev) <https://github.com/lodev>`__
- `Barry Loong (@loongyh) <https://github.com/loongyh>`__
@ -542,8 +548,10 @@ Contributors
- `Marcio Granzotto Rodrigues (@marciogranzotto) <https://github.com/marciogranzotto>`__
- `Marc Teale (@marcteale) <https://github.com/marcteale>`__
- `marecabo (@marecabo) <https://github.com/marecabo>`__
- `Ben Marengo (@marengaz) <https://github.com/marengaz>`__
- `Marvin Gaube (@margau) <https://github.com/margau>`__
- `Martynas Griškonis (@Margriko) <https://github.com/Margriko>`__
- `maringeph (@maringeph) <https://github.com/maringeph>`__
- `Mario (@mario-tux) <https://github.com/mario-tux>`__
- `Marek Marczykowski-Górecki (@marmarek) <https://github.com/marmarek>`__
- `Matthew Harrold (@marrold) <https://github.com/marrold>`__
@ -611,19 +619,16 @@ Contributors
- `Martin Weinelt (@mweinelt) <https://github.com/mweinelt>`__
- `Igor Scheller (@MyIgel) <https://github.com/MyIgel>`__
- `Mynasru (@Mynasru) <https://github.com/Mynasru>`__
- `Niels Ulrik Andersen (@myplacedk) <https://github.com/myplacedk>`__
- `Kevin Uhlir (@n0bel) <https://github.com/n0bel>`__
- `Erik Näsström (@Naesstrom) <https://github.com/Naesstrom>`__
- `H. Árkosi Róbert (@nagyrobi) <https://github.com/nagyrobi>`__
- `Viktor Nagy (@nagyv) <https://github.com/nagyv>`__
- `Oskar Napieraj (@napieraj) <https://github.com/napieraj>`__
- `Patrick ZAJDA (@Nardol) <https://github.com/Nardol>`__
- `Nate Lust (@natelust) <https://github.com/natelust>`__
- `ueno (@nayuta-ueno) <https://github.com/nayuta-ueno>`__
- `Nazar Mokrynskyi (@nazar-pc) <https://github.com/nazar-pc>`__
- `Bergont Nicolas (@nbergont) <https://github.com/nbergont>`__
- `NMC (@ncareau) <https://github.com/ncareau>`__
- `Nebula (@nebula-it) <https://github.com/nebula-it>`__
- `NeoAcheron (@NeoAcheron) <https://github.com/NeoAcheron>`__
- `Mike Meessen (@netmikey) <https://github.com/netmikey>`__
- `Nick B. (@NickB1) <https://github.com/NickB1>`__
@ -635,9 +640,7 @@ Contributors
- `niklasweber (@niklasweber) <https://github.com/niklasweber>`__
- `Niorix (@Niorix) <https://github.com/Niorix>`__
- `Zvonimir Haramustek (@nitko12) <https://github.com/nitko12>`__
- `Nikolay Kitanov (@nkitanov) <https://github.com/nkitanov>`__
- `nldroid (@nldroid) <https://github.com/nldroid>`__
- `Nicolas Liaudat (@nliaudat) <https://github.com/nliaudat>`__
- `Niccolò Maggioni (@nmaggioni) <https://github.com/nmaggioni>`__
- `Jan Sandbrink (@NobodysNightmare) <https://github.com/NobodysNightmare>`__
- `Łukasz Śliwiński (@nonameplum) <https://github.com/nonameplum>`__
@ -651,24 +654,21 @@ Contributors
- `Ockert Marais (@OckertM) <https://github.com/OckertM>`__
- `Dave Walker (@oddsockmachine) <https://github.com/oddsockmachine>`__
- `Andrey Ganzevich (@odya) <https://github.com/odya>`__
- `Olivér Falvai (@ofalvai) <https://github.com/ofalvai>`__
- `ogatatsu (@ogatatsu) <https://github.com/ogatatsu>`__
- `Oğuzhan Başer (@oguzhanbaser) <https://github.com/oguzhanbaser>`__
- `Omar Ghader (@omarghader) <https://github.com/omarghader>`__
- `Ömer Şiar Baysal (@omersiar) <https://github.com/omersiar>`__
- `Oncleben31 (@oncleben31) <https://github.com/oncleben31>`__
- `optimusprimespace (@optimusprimespace) <https://github.com/optimusprimespace>`__
- `Oscar Bolmsten (@oscar-b) <https://github.com/oscar-b>`__
- `Trammell Hudson (@osresearch) <https://github.com/osresearch>`__
- `Otamay (@Otamay) <https://github.com/Otamay>`__
- `Otto Winter (@OttoWinter) <https://github.com/OttoWinter>`__
- `Ben Owen (@owenb321) <https://github.com/owenb321>`__
- `Oxan van Leeuwen (@oxan) <https://github.com/oxan>`__
- `Pack3tL0ss (@Pack3tL0ss) <https://github.com/Pack3tL0ss>`__
- `Pablo Clemente Maseda (@paclema) <https://github.com/paclema>`__
- `Derrick Lyndon Pallas (@pallas) <https://github.com/pallas>`__
- `Panuruj Khambanonda (PK) (@panuruj) <https://github.com/panuruj>`__
- `Pasi Suominen (@pasiz) <https://github.com/pasiz>`__
- `Patrick Felstead (@patfelst) <https://github.com/patfelst>`__
- `Patrick van der Leer (@patvdleer) <https://github.com/patvdleer>`__
- `Paul Deen (@PaulAntonDeen) <https://github.com/PaulAntonDeen>`__
- `Paul Monigatti (@paulmonigatti) <https://github.com/paulmonigatti>`__
@ -691,7 +691,6 @@ Contributors
- `probonopd (@probonopd) <https://github.com/probonopd>`__
- `Mike Lynch (@Prow7) <https://github.com/Prow7>`__
- `Peter Tatrai (@ptatrai) <https://github.com/ptatrai>`__
- `Patrick Toal (@ptoal) <https://github.com/ptoal>`__
- `Leandro Puerari (@puerari) <https://github.com/puerari>`__
- `puuu (@puuu) <https://github.com/puuu>`__
- `Pascal Vizeli (@pvizeli) <https://github.com/pvizeli>`__
@ -699,6 +698,7 @@ Contributors
- `Qc (@qc24) <https://github.com/qc24>`__
- `Karol Zlot (@qqgg231) <https://github.com/qqgg231>`__
- `Tommy Jonsson (@quazzie) <https://github.com/quazzie>`__
- `Quentin Smith (@quentinmit) <https://github.com/quentinmit>`__
- `Quinn Hosler (@quinnhosler) <https://github.com/quinnhosler>`__
- `Johannes Rebling (@r0oland) <https://github.com/r0oland>`__
- `Richard Kuhnt (@r15ch13) <https://github.com/r15ch13>`__
@ -741,6 +741,7 @@ Contributors
- `Silvio (@s1lvi0) <https://github.com/s1lvi0>`__
- `Jan Čermák (@sairon) <https://github.com/sairon>`__
- `sascha lammers (@sascha432) <https://github.com/sascha432>`__
- `Søren Christian Aarup (@scaarup) <https://github.com/scaarup>`__
- `Nils Schulte (@Schnilz) <https://github.com/Schnilz>`__
- `Wolle (@schreibfaul1) <https://github.com/schreibfaul1>`__
- `Ville Skyttä (@scop) <https://github.com/scop>`__
@ -755,7 +756,6 @@ Contributors
- `sherbang (@sherbang) <https://github.com/sherbang>`__
- `Shish (@shish) <https://github.com/shish>`__
- `SiliconAvatar (@SiliconAvatar) <https://github.com/SiliconAvatar>`__
- `SirSydom (@SirSydom) <https://github.com/SirSydom>`__
- `Derek Hageman (@Sizurka) <https://github.com/Sizurka>`__
- `Stephen Tierney (@sjtrny) <https://github.com/sjtrny>`__
- `Niklas Wagner (@Skaronator) <https://github.com/Skaronator>`__
@ -799,7 +799,6 @@ Contributors
- `Ryan Hoffman (@tekmaven) <https://github.com/tekmaven>`__
- `testbughub (@testbughub) <https://github.com/testbughub>`__
- `Greg Lincoln (@tetious) <https://github.com/tetious>`__
- `Nejc (@thedexboy) <https://github.com/thedexboy>`__
- `Thomas Eckerstorfer (@TheEggi) <https://github.com/TheEggi>`__
- `Theexternaldisk (@Theexternaldisk) <https://github.com/Theexternaldisk>`__
- `TheGroundZero (@TheGroundZero) <https://github.com/TheGroundZero>`__
@ -874,7 +873,7 @@ Contributors
- `WJCarpenter (@wjcarpenter) <https://github.com/wjcarpenter>`__
- `Wouter van der Wal (@wjtje) <https://github.com/wjtje>`__
- `Artur 'Wodor' Wielogorski (@wodor) <https://github.com/wodor>`__
- `Rick van Hattem (@WoLpH) <https://github.com/WoLpH>`__
- `Rick van Hattem (@wolph) <https://github.com/wolph>`__
- `workingmanrob (@workingmanrob) <https://github.com/workingmanrob>`__
- `Sven Serlier (@wrt54g) <https://github.com/wrt54g>`__
- `Wojtek Strzalka (@wstrzalka) <https://github.com/wstrzalka>`__
@ -898,4 +897,4 @@ Contributors
- `Zack Barett (@zsarnett) <https://github.com/zsarnett>`__
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
*This page was last updated October 7, 2022.*
*This page was last updated November 24, 2022.*

BIN
images/adc128s102.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
images/ezo-pmp.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.2 KiB

BIN
images/lcd_menu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
images/radiationD-v1-1-cajoe_small.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

62
images/rp2040.svg Normal file
View File

@ -0,0 +1,62 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
width="108.44565mm"
height="25.000002mm"
viewBox="0 0 108.44565 25.000002"
version="1.1"
id="svg8"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/">
<defs
id="defs2" />
<metadata
id="metadata5">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
</cc:Work>
</rdf:RDF>
</metadata>
<g
id="layer1">
<path
id="rect833"
style="stroke-width:0.133497"
d="m 5,0 h 98.44565 c 2.77,0 5,2.23 5,5 v 15 c 0,2.77 -2.23,5 -5,5 H 5 C 2.23,25 0,22.77 0,20 V 5 C 0,2.23 2.23,0 5,0 Z" />
<g
aria-label="RP2040"
id="text837"
style="font-size:10.5833px;line-height:1.25;letter-spacing:1.08479px;fill:#fffffc;stroke-width:0.264583">
<path
d="m 15.353522,20.665705 -2.686758,-3.973693 h -1.44498 v 3.973693 H 5.8934233 V 4.8612442 h 7.6087187 q 2.190047,0 3.815649,0.7224896 1.625601,0.7224896 2.506135,2.0771577 0.880535,1.354668 0.880535,3.1608925 0,1.693335 -0.767646,2.957691 -0.767645,1.264357 -2.212624,2.009425 l 3.318937,4.876805 z m -0.02258,-9.843921 q 0,-0.8805346 -0.541867,-1.3546684 -0.541865,-0.4967117 -1.6256,-0.4967117 h -1.941691 v 3.7027591 h 1.941691 q 1.083735,0 1.625602,-0.474134 0.541867,-0.496711 0.541867,-1.377245 z"
style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
id="path414" />
<path
d="m 31.407412,4.8612442 q 2.190046,0 3.815648,0.7224896 1.625602,0.7224896 2.506136,2.0771577 0.880534,1.354668 0.880534,3.1608925 0,1.806224 -0.880534,3.160892 -0.880534,1.354668 -2.506136,2.077157 -1.625602,0.72249 -3.815648,0.72249 h -2.280358 v 3.883382 H 23.798693 V 4.8612442 Z m -0.338667,7.8119188 q 1.083734,0 1.625601,-0.474134 0.541868,-0.496711 0.541868,-1.377245 0,-0.8805346 -0.541868,-1.3546684 -0.541867,-0.4967117 -1.625601,-0.4967117 h -1.941691 v 3.7027591 z"
style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
id="path416" />
<path
d="m 48.228949,16.533967 h 5.328361 v 4.131738 H 40.891163 v -3.273781 l 5.712184,-5.283206 q 0.745067,-0.699912 0.993423,-1.196623 0.248356,-0.496712 0.248356,-0.9708456 0,-0.5870228 -0.4064,-0.9031121 -0.383823,-0.338667 -1.12889,-0.338667 -0.72249,0 -1.354668,0.3838226 -0.632179,0.3838227 -0.970846,1.0837341 L 39.965474,8.1576031 q 0.903112,-1.693335 2.641602,-2.6641805 1.738491,-0.9934232 4.199471,-0.9934232 1.873958,0 3.318937,0.6096006 1.444979,0.6096006 2.25778,1.7384907 0.812801,1.12889 0.812801,2.5964471 0,1.3095122 -0.564445,2.4609802 -0.541867,1.12889 -2.144891,2.573869 z"
style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
id="path418" />
<path
d="m 62.882996,21.02695 q -2.099736,0 -3.725337,-0.970846 -1.603024,-0.993423 -2.528714,-2.844803 -0.903112,-1.873957 -0.903112,-4.447827 0,-2.573869 0.903112,-4.4252485 0.92569,-1.8739574 2.528714,-2.8448029 1.625601,-0.9934232 3.725337,-0.9934232 2.099735,0 3.702759,0.9934232 1.625602,0.9708455 2.528714,2.8448029 0.92569,1.8513795 0.92569,4.4252485 0,2.57387 -0.92569,4.447827 -0.903112,1.85138 -2.528714,2.844803 -1.603024,0.970846 -3.702759,0.970846 z m 0,-4.267205 q 1.806224,0 1.806224,-3.996271 0,-3.9962703 -1.806224,-3.9962703 -1.806224,0 -1.806224,3.9962703 0,3.996271 1.806224,3.996271 z"
style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
id="path420" />
<path
d="m 85.665039,13.824631 h 2.099735 v 4.131738 h -2.099735 v 2.709336 h -5.170317 v -2.709336 h -8.195741 v -3.38667 l 6.705606,-9.7084548 h 5.463828 l -5.960539,8.9633868 h 2.144891 v -2.415825 h 5.012272 z"
style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
id="path422" />
<path
d="m 96.751789,21.02695 q -2.099735,0 -3.725337,-0.970846 -1.603024,-0.993423 -2.528713,-2.844803 -0.903112,-1.873957 -0.903112,-4.447827 0,-2.573869 0.903112,-4.4252485 0.925689,-1.8739574 2.528713,-2.8448029 1.625602,-0.9934232 3.725337,-0.9934232 2.099736,0 3.702761,0.9934232 1.6256,0.9708455 2.52871,2.8448029 0.92569,1.8513795 0.92569,4.4252485 0,2.57387 -0.92569,4.447827 -0.90311,1.85138 -2.52871,2.844803 -1.603025,0.970846 -3.702761,0.970846 z m 0,-4.267205 q 1.806224,0 1.806224,-3.996271 0,-3.9962703 -1.806224,-3.9962703 -1.806224,0 -1.806224,3.9962703 0,3.996271 1.806224,3.996271 z"
style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
id="path424" />
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB

32
index.rst
View File

@ -113,26 +113,14 @@ ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configu
.. _devices:
Devices
-------
This list contains a bunch of getting started and more advanced guides for using ESPHome.
Technically, all ESP8266/ESP32 devices are supported by ESPHome.
Platforms
---------
.. imgtable::
Generic ESP8266, devices/esp8266, esp8266.svg
Generic ESP32, devices/esp32, esp32.svg
NodeMCU ESP8266, devices/nodemcu_esp8266, nodemcu_esp8266.jpg
NodeMCU ESP32, devices/nodemcu_esp32, nodemcu_esp32.jpg
Sonoff S20, devices/sonoff_s20, sonoff_s20.jpg
Sonoff 4CH, devices/sonoff_4ch, sonoff_4ch.jpg
Generic Sonoff, devices/sonoff, sonoff.svg
Sonoff Basic, devices/sonoff_basic, sonoff_basic.jpg
Sonoff T1 UK 3 Gang V1.1, devices/sonoff_t1_uk_3gang_v1.1, sonoff_t1_uk_3g_v1.1.jpg
Sonoff T3 EU 3 Gang V1.0, devices/sonoff_t3_eu_3gang_v1.0, sonoff_t3_eu_3g_v1.0.jpg
ESP8266, components/esp8266, esp8266.svg
ESP32, components/esp32, esp32.svg
RP2040, components/rp2040, rp2040.svg
Core Components
---------------
@ -207,6 +195,7 @@ Analogue
.. imgtable::
ADC, components/sensor/adc, flash.svg, ESP internal
ADC128S102, components/sensor/adc128s102, adc128s102.png , 8-channel ADC
ADS1115, components/sensor/ads1115, ads1115.jpg, 4-channel ADC
CD74HC4067, components/sensor/cd74hc4067, cd74hc4067.jpg, 16-channel analog multiplexer
MCP3008, components/sensor/mcp3008, mcp3008.jpg, 8-channel ADC
@ -594,12 +583,14 @@ Text Sensor Components
MQTT Subscribe Text, components/text_sensor/mqtt_subscribe, mqtt.png
Version, components/text_sensor/version, new-box.svg
WiFi Info, components/text_sensor/wifi_info, network-wifi.svg
Ethernet Info, components/text_sensor/ethernet_info, ethernet.svg
BLE Scanner, components/text_sensor/ble_scanner, bluetooth.svg
Modbus Text Sensor, components/text_sensor/modbus_controller, modbus.png
Template Text Sensor, components/text_sensor/template, description.svg
Custom Text Sensor, components/text_sensor/custom, language-cpp.svg
Nextion Text Sensor, components/text_sensor/nextion, nextion.jpg
Tuya Text Sensor, components/text_sensor/tuya, tuya.png
WL-134 Pet Tag Sensor , components/text_sensor/wl_134, fingerprint.svg
Climate Components
------------------
@ -659,12 +650,11 @@ Misc Components
.. imgtable::
ESP8266, components/esp8266, esp8266.svg
ESP32, components/esp32, esp32.svg
Remote Receiver, components/remote_receiver, remote.svg
Remote Transmitter, components/remote_transmitter, remote.svg
Status LED, components/status_led, led-on.svg
Display Menu Core, components/display_menu/index, folder-open.svg
LCD Menu, components/display_menu/lcd_menu, lcd_menu.png
HTTP Request, components/http_request, connection.svg
mDNS, components/mdns, radio-tower.svg
@ -707,6 +697,7 @@ Misc Components
PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg
Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg
SML, components/sml, sml.svg
Atlas Scientific Peristaltic Pump, components/ezo_pmp, ezo-pmp.jpg
Demo, components/demo, description.svg
Copy, components/copy, content-copy.svg
@ -756,6 +747,7 @@ Cookbook
EPEVER Tracer, cookbook/tracer-an, tracer-an.jpg
Ilonda Wifi Smart Fish Feeder, cookbook/ilonda-wifi-smart-fish-feeder, ilonda-wifi-smart-fish-feeder-cookbook.jpg
AirGradient DIY Air Quality Sensor, cookbook/air_gradient_diy_air_quality_sensor, air_gradient_diy_air_quality_sensor.jpg
Geiger Counter, cookbook/geiger-counter, radiationD-v1-1-cajoe_small.jpg
Do you have other awesome automations or cool setups? Please feel free to add them to the
documentation for others to copy. See :doc:`Contributing </guides/contributing>`.

24
schema_doc.py
View File

@ -620,9 +620,15 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
component_parts = split_text[0].split(".")
if len(component_parts) == 3:
cv = get_component_file(self.app, component_parts[1])[
component_parts[1] + "." + component_parts[0]
][split_text[1].lower()][component_parts[2]]
try:
cv = get_component_file(self.app, component_parts[1])[
component_parts[1] + "." + component_parts[0]
][split_text[1].lower()][component_parts[2]]
except KeyError:
logger.warn(
f"In {self.docname} cannot found schema of {title_text}"
)
cv = None
if cv is not None:
cv["docs"] = description
self.props = self.find_props(cv.get("schema", {}))
@ -934,7 +940,12 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
# this is e.g. when a property has a list inside, and the list inside are the options.
# just validate **prop_name**
s3 = re.search(r"\* \*\*(\w*)\*\*:\s", name_type)
prop_name = s3.group(1)
if s3 is not None:
prop_name = s3.group(1)
else:
logger.info(
f"In '{self.docname} {self.previous_title_text} Invalid list format: {node.rawsource}"
)
param_type = None
else:
logger.info(
@ -1150,9 +1161,10 @@ def handle_component(app, doctree, docname):
doctree.walkabout(v)
except Exception as e:
err_str = f"In {docname}.rst: {str(e)}"
logger.warning(err_str)
# print stack
# if you put a breakpoint here get call-stack in the console by entering
# import traceback
# traceback.print_exc()
logger.warning(err_str)
def build_finished(app, exception):