diff --git a/Doxygen b/Doxygen
index 45420066e..fe95949b2 100644
--- a/Doxygen
+++ b/Doxygen
@@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
# could be handy for archiving the generated documentation or if some version
# control system is used.
-PROJECT_NUMBER = 2022.10.2
+PROJECT_NUMBER = 2022.11.1
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
diff --git a/Makefile b/Makefile
index 7ae0cf4bb..da05b2951 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2022.10.2
+ESPHOME_REF = 2022.11.1
.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
diff --git a/_redirects b/_redirects
index 7ed3fa34a..dfa37018e 100644
--- a/_redirects
+++ b/_redirects
@@ -4,3 +4,5 @@
# 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
diff --git a/_static/changelog-2022.11.0.png b/_static/changelog-2022.11.0.png
new file mode 100644
index 000000000..3d28c77c9
Binary files /dev/null and b/_static/changelog-2022.11.0.png differ
diff --git a/_static/version b/_static/version
index 8fd513888..8512b9247 100644
--- a/_static/version
+++ b/_static/version
@@ -1 +1 @@
-2022.10.2
\ No newline at end of file
+2022.11.1
\ No newline at end of file
diff --git a/_static/webserver-v1.js b/_static/webserver-v1.js
index f82011ae5..781253c0c 100644
--- a/_static/webserver-v1.js
+++ b/_static/webserver-v1.js
@@ -23,7 +23,7 @@ source.addEventListener('log', function (e) {
log.innerHTML += '' + e.data.substr(7, e.data.length - 11) + "\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"],
];
diff --git a/_static/webserver-v1.min.js b/_static/webserver-v1.min.js
index fe912baf0..5c6a80518 100644
--- a/_static/webserver-v1.min.js
+++ b/_static/webserver-v1.min.js
@@ -1 +1 @@
-const source=new EventSource("/events");source.addEventListener("log",function(t){const e=document.getElementById("log");let n=[["[1;31m","e"],["[0;33m","w"],["[0;32m","i"],["[0;35m","c"],["[0;36m","d"],["[0;37m","v"]],o="";for(const e of n)t.data.startsWith(e[0])&&(o=e[1]);""==o&&(e.innerHTML+=t.data+"\n"),e.innerHTML+=''+t.data.substr(7,t.data.length-11)+"\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'+t.data.substr(7,t.data.length-11)+"\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`__ 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`
+
+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`
diff --git a/changelog/index.rst b/changelog/index.rst
index babc04499..ab582c12b 100644
--- a/changelog/index.rst
+++ b/changelog/index.rst
@@ -2,7 +2,7 @@ Changelog
=========
.. redirect::
- :url: /changelog/2022.10.0.html
+ :url: /changelog/2022.11.0.html
.. toctree::
:glob:
diff --git a/components/bluetooth_proxy.rst b/components/bluetooth_proxy.rst
index 3e5bb8b44..5db10d5cd 100644
--- a/components/bluetooth_proxy.rst
+++ b/components/bluetooth_proxy.rst
@@ -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 `__ 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 `__ 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 `__ 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 `__ 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
--------
diff --git a/components/captive_portal.rst b/components/captive_portal.rst
index e9c4a741e..4b2543347 100644
--- a/components/captive_portal.rst
+++ b/components/captive_portal.rst
@@ -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
--------
diff --git a/components/climate/climate_ir.rst b/components/climate/climate_ir.rst
index 6773d5c4b..c60fa8b46 100644
--- a/components/climate/climate_ir.rst
+++ b/components/climate/climate_ir.rst
@@ -27,6 +27,8 @@ submit a feature request (see FAQ).
+---------------------------------------+---------------------+----------------------+
| Daikin | ``daikin`` | yes |
+---------------------------------------+---------------------+----------------------+
+| :ref:`Daikin BRC` | ``daikin_brc`` | yes |
++---------------------------------------+---------------------+----------------------+
| :ref:`Delonghi` | ``delonghi`` | yes |
+---------------------------------------+---------------------+----------------------+
| Fujitsu General | ``fujitsu_general`` | yes |
@@ -211,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
diff --git a/components/display/images/lcd_gpio.svg b/components/display/images/lcd_gpio.svg
new file mode 100644
index 000000000..e0a4699c5
--- /dev/null
+++ b/components/display/images/lcd_gpio.svg
@@ -0,0 +1,10604 @@
+
+
+
+
diff --git a/components/display/lcd_display.rst b/components/display/lcd_display.rst
index ba6440a70..8527c9b39 100644
--- a/components/display/lcd_display.rst
+++ b/components/display/lcd_display.rst
@@ -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 `__
-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 `, 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 `, 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 `, 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 `__
-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 `.
-.. 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 `): 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 `): The pin you have ``EN`` hooked up to.
-- **rs_pin** (**Required**, :ref:`Pin Schema `): The pin you have ``RS`` hooked up to.
-- **rw_pin** (*Optional*, :ref:`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 `): 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 `): The pin you have ``E`` (``06``) hooked up to.
+- **rs_pin** (**Required**, :ref:`pin `): The pin you have ``RS`` (``04``) hooked up to.
+- **rw_pin** (*Optional*, :ref:`pin `): 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 `): 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 `__ 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 `
- :doc:`/components/pcf8574`
-- :apiref:`lcd_base/lcd_display.h`
+- `HD44780U (LCD-II) datasheet `__
+- `Charset cheatsheet `__
+- `Custom Character Generator `__
- `Arduino LiquidCrystal Library `__
+- :apiref:`lcd_base/lcd_display.h`
- :ghedit:`Edit`
diff --git a/components/display_menu/images/lcd_menu.png b/components/display_menu/images/lcd_menu.png
new file mode 100644
index 000000000..be3ebd427
Binary files /dev/null and b/components/display_menu/images/lcd_menu.png differ
diff --git a/components/display_menu/index.rst b/components/display_menu/index.rst
new file mode 100644
index 000000000..3f0e4d54e
--- /dev/null
+++ b/components/display_menu/index.rst
@@ -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 ` 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 `,
+ the anticlockwise one to :ref:`display_menu.up ` and the switch
+ to :ref:`display_menu.enter ` action. The ``joystick`` mode
+ expects the up, down, left and right buttons wired to the :ref:`display_menu.up `,
+ :ref:`display_menu.down `, :ref:`display_menu.left `
+ and :ref:`display_menu.right ` actions and the middle button
+ to the :ref:`display_menu.enter ` action. Defaults to ``rotary``.
+- **menu** (**Required**): The first level of the menu.
+
+Automations:
+
+- **on_enter** (*Optional*, :ref:`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 `): 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 `): 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 `): An automation to perform
+ when the menu level is entered. See :ref:`display_menu-on_enter`.
+- **on_leave** (*Optional*, :ref:`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 `. Defaults to ``false``.
+- **select** (**Required**, :ref:`config-id`): A ``select`` component managing
+ the edited value.
+- **value_lambda** (*Optional*, :ref:`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 `): An automation to perform
+ when the editing mode is activated. See :ref:`display_menu-on_enter`.
+- **on_leave** (*Optional*, :ref:`Automation `): An automation to perform
+ when the editing mode is exited.
+ See :ref:`display_menu-on_leave`.
+- **on_value** (*Optional*, :ref:`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 `. 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 `):
+ 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 `): An automation to perform
+ when the editing mode is activated. See :ref:`display_menu-on_enter`.
+- **on_leave** (*Optional*, :ref:`Automation `): An automation to perform
+ when the editing mode is exited.
+ See :ref:`display_menu-on_leave`.
+- **on_value** (*Optional*, :ref:`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 `. 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 `):
+ 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 `): An automation to perform
+ when the editing mode is activated. See :ref:`display_menu-on_enter`.
+- **on_leave** (*Optional*, :ref:`Automation `): An automation to perform
+ when the editing mode is exited.
+ See :ref:`display_menu-on_leave`.
+- **on_value** (*Optional*, :ref:`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 `): 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 `. Defaults to ``false``.
+- **value_lambda** (*Optional*, :ref:`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 `): An automation to perform
+ when the editing mode is activated. See :ref:`display_menu-on_enter`.
+- **on_leave** (*Optional*, :ref:`Automation `): An automation to perform
+ when the editing mode is exited.
+ See :ref:`display_menu-on_leave`.
+- **on_value** (*Optional*, :ref:`Automation `): An automation to perform
+ when the value is changed.
+ See :ref:`display_menu-on_value`.
+- **on_next** (*Optional*, :ref:`Automation `): An automation to perform
+ when the user navigates to the next value.
+ See :ref:`display_menu-on_next`.
+- **on_prev** (*Optional*, :ref:`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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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`
diff --git a/components/display_menu/lcd_menu.rst b/components/display_menu/lcd_menu.rst
new file mode 100644
index 000000000..c254331e7
--- /dev/null
+++ b/components/display_menu/lcd_menu.rst
@@ -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 ` 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 ` 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 `
+- :doc:`/components/sensor/rotary_encoder`
+- :doc:`/components/binary_sensor/index`
+- :apiref:`lcd_menu/lcd_menu.h`
+- :ghedit:`Edit`
diff --git a/components/esp32.rst b/components/esp32.rst
index 32692f96f..6e9bb7758 100644
--- a/components/esp32.rst
+++ b/components/esp32.rst
@@ -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 ` like some other
+ pins.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ binary_sensor:
+ - platform: gpio
+ name: "Pin GPIO23"
+ pin: GPIO23
+
Arduino framework
-----------------
diff --git a/components/esp32_ble_beacon.rst b/components/esp32_ble_beacon.rst
index dac949dee..79e350c7a 100644
--- a/components/esp32_ble_beacon.rst
+++ b/components/esp32_ble_beacon.rst
@@ -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 `__
+ 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
----------
diff --git a/components/esp8266.rst b/components/esp8266.rst
index 10ded12f7..5fa9ff86d 100644
--- a/components/esp8266.rst
+++ b/components/esp8266.rst
@@ -20,7 +20,7 @@ Configuration variables:
- **board** (**Required**, string): The PlatformIO board ID that should
be used. Choose the appropriate board from
- `this list `__ (the icon next to the
+ `this list `__ (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
+`__:
+
+== ===================================
+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 `__
+
+The internal pull up/down resistors have values of 30kΩ to 100kΩ
+(`source `__).
+
See Also
--------
diff --git a/components/esphome.rst b/components/esphome.rst
index e5393ed6d..c5a25ac38 100644
--- a/components/esphome.rst
+++ b/components/esphome.rst
@@ -53,6 +53,8 @@ Advanced options:
- **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 ` and
:doc:`esp8266 ` sections but are still accepted here for compatibility reasons (usage not
diff --git a/components/ezo_pmp.rst b/components/ezo_pmp.rst
new file mode 100644
index 000000000..d373e7e71
--- /dev/null
+++ b/components/ezo_pmp.rst
@@ -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 `__)
+and EZO-PMP-L (`datasheet `__) are supported.
+The :ref:`I²C Bus ` 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 `.
+
+.. _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 `.
+
+.. _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 `.
+
+.. _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 `.
+
+.. _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 ` 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 `.
+
+.. _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 `.
+
+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 `.
+
+.. _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 `.
+
+
+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 `.
+
+.. _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 `.
+
+Actions
+-----------------------------
+
+.. _ezo_pmp-dose_continuously_action:
+
+``ezo_pmp.dose_continuously`` Action
+------------------------------------
+
+Use this action in an :ref:`automations ` to have the peristaltic pump dose continuously
+at the :ref:`Maximum Flow Rate `. 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 ` to have the peristaltic pump dose an specific volume (in milliliters)
+at the :ref:`Maximum Flow Rate `. 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 `): 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 ` 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 `): The volume to dose in milliliters. If negative, pump will run in reverse.
+- **duration** (**Required**, int, :ref:`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 ` 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 `): The volume to dose in milliliters every minute. If negative, pump will run in reverse.
+- **duration** (**Required**, int, :ref:`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 ` 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 `, :ref:`Total Volume Dosed `
+and :ref:`Absolute Total Volume Dosed ` 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` 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 `): 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` 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 `): 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 `, 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`
diff --git a/components/images/ezo-pmp.jpg b/components/images/ezo-pmp.jpg
new file mode 100644
index 000000000..de1f85ea0
Binary files /dev/null and b/components/images/ezo-pmp.jpg differ
diff --git a/components/index.rst b/components/index.rst
index 15a1cda2c..a873c9e66 100644
--- a/components/index.rst
+++ b/components/index.rst
@@ -20,5 +20,6 @@ Components
stepper/index
touchscreen/index
lock/index
+ display_menu/index
media_player/index
*
diff --git a/components/ota.rst b/components/ota.rst
index 1e053fa4f..c05e9f33e 100644
--- a/components/ota.rst
+++ b/components/ota.rst
@@ -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``.
diff --git a/components/rp2040.rst b/components/rp2040.rst
new file mode 100644
index 000000000..6adcb8f6f
--- /dev/null
+++ b/components/rp2040.rst
@@ -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 `__ 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`
diff --git a/components/sensor/adc.rst b/components/sensor/adc.rst
index 21fa50d61..a8c03e99c 100644
--- a/components/sensor/adc.rst
+++ b/components/sensor/adc.rst
@@ -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
---------------------
diff --git a/components/sensor/adc128s102.rst b/components/sensor/adc128s102.rst
new file mode 100644
index 000000000..779997910
--- /dev/null
+++ b/components/sensor/adc128s102.rst
@@ -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 `__,
+`Texas Instruments `__) in ESPHome.
+It uses the :ref:`SPI Bus ` 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 ` 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`
diff --git a/components/sensor/esp32_hall.rst b/components/sensor/esp32_hall.rst
index 00cf7a13d..436b8610a 100644
--- a/components/sensor/esp32_hall.rst
+++ b/components/sensor/esp32_hall.rst
@@ -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`
diff --git a/components/sensor/ezo.rst b/components/sensor/ezo.rst
index 042722250..fd7e2b7a4 100644
--- a/components/sensor/ezo.rst
+++ b/components/sensor/ezo.rst
@@ -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 ` is
required to be set up in your configuration for this sensor to work.
+All embedded solutions from EZO can be found `here `__.
+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 `.
+.. _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 `, you can set the temperature compensation for the
-sensors that support that option.
+From :ref:`lambdas `, 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_low(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
--------
diff --git a/components/sensor/hmc5883l.rst b/components/sensor/hmc5883l.rst
index b1bf83c2c..c2551acb0 100644
--- a/components/sensor/hmc5883l.rst
+++ b/components/sensor/hmc5883l.rst
@@ -52,7 +52,6 @@ Configuration variables:
- **heading** (*Optional*): The heading of the sensor in degrees. All options from
:ref:`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``.
diff --git a/components/sensor/homeassistant.rst b/components/sensor/homeassistant.rst
index 35f8c5d44..c30f7e95f 100644
--- a/components/sensor/homeassistant.rst
+++ b/components/sensor/homeassistant.rst
@@ -16,7 +16,7 @@ states from your Home Assistant instance using the :doc:`native API `.
- 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 `
@@ -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 `.
+
+.. 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
--------
diff --git a/components/sensor/images/adc128s102.png b/components/sensor/images/adc128s102.png
new file mode 100644
index 000000000..0bd81d055
Binary files /dev/null and b/components/sensor/images/adc128s102.png differ
diff --git a/components/sensor/pzemac.rst b/components/sensor/pzemac.rst
index ebb96be95..cebb686a1 100644
--- a/components/sensor/pzemac.rst
+++ b/components/sensor/pzemac.rst
@@ -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
diff --git a/components/sensor/scd4x.rst b/components/sensor/scd4x.rst
index 99955c423..04796d3d3 100644
--- a/components/sensor/scd4x.rst
+++ b/components/sensor/scd4x.rst
@@ -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 `__) sensors with ESPHome.
+(`datasheet `__) sensors with ESPHome.
The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work.
.. figure:: images/scd4x.jpg
diff --git a/components/sensor/sgp4x.rst b/components/sensor/sgp4x.rst
index 313a5cc3b..8e375c1be 100644
--- a/components/sensor/sgp4x.rst
+++ b/components/sensor/sgp4x.rst
@@ -27,7 +27,7 @@ The :ref:`I²C Bus ` is required to be set up in your configuration for thi
# Example configuration entry
sensor:
- - platform: sgp4x
+ - platform: sgp4x
voc:
name: "VOC Index"
nox:
diff --git a/components/sensor/sm300d2.rst b/components/sensor/sm300d2.rst
index 2a2d1dc71..1e0ac5ade 100644
--- a/components/sensor/sm300d2.rst
+++ b/components/sensor/sm300d2.rst
@@ -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 ` regarding powering everything).
+
Make sure you have a :ref:`UART bus ` 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 `.
-- **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 `.
-- **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 `.
-- **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 `.
-- **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 `.
-- **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 `.
-- **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
--------
diff --git a/components/sensor/uptime.rst b/components/sensor/uptime.rst
index c8ea1a9e6..c1f6db763 100644
--- a/components/sensor/uptime.rst
+++ b/components/sensor/uptime.rst
@@ -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 `.
-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
--------
diff --git a/components/text_sensor/ethernet_info.rst b/components/text_sensor/ethernet_info.rst
new file mode 100644
index 000000000..fde771542
--- /dev/null
+++ b/components/text_sensor/ethernet_info.rst
@@ -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 `.
+
+See Also
+--------
+
+- :apiref:`ethernet_info/ethernet_info_text_sensor.h`
+- :ghedit:`Edit`
diff --git a/components/text_sensor/homeassistant.rst b/components/text_sensor/homeassistant.rst
index 7d514ad10..31f332f8e 100644
--- a/components/text_sensor/homeassistant.rst
+++ b/components/text_sensor/homeassistant.rst
@@ -16,7 +16,7 @@ states from your Home Assistant instance using the :doc:`native API `.
diff --git a/components/text_sensor/wl_134.rst b/components/text_sensor/wl_134.rst
new file mode 100644
index 000000000..a8bfe6c33
--- /dev/null
+++ b/components/text_sensor/wl_134.rst
@@ -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 `.
+
+See Also
+--------
+
+- :apiref:`wl_134/wl_134.h`
+- :ghedit:`Edit`
diff --git a/components/web_server.rst b/components/web_server.rst
index 78c95f4c4..4e1e29efe 100644
--- a/components/web_server.rst
+++ b/components/web_server.rst
@@ -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: ""
diff --git a/components/wifi.rst b/components/wifi.rst
index bfc2378e5..4899a2303 100644
--- a/components/wifi.rst
+++ b/components/wifi.rst
@@ -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
diff --git a/conf.py b/conf.py
index f608e9923..4138c96e5 100644
--- a/conf.py
+++ b/conf.py
@@ -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.10"
+version = "2022.11"
# The full version, including alpha/beta/rc tags.
-release = "2022.10.2"
+release = "2022.11.1"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/devices/esp32.rst b/devices/esp32.rst
deleted file mode 100644
index 75a32f216..000000000
--- a/devices/esp32.rst
+++ /dev/null
@@ -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 `__ when the wizard
-asks you for the board type.
-
-.. code-block:: yaml
-
- # Example configuration entry
- esphome:
- name: livingroom
-
- esp32:
- board:
-
-.. 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 ` like some other
- pins.
-
-.. code-block:: yaml
-
- # Example configuration entry
- esphome:
- name: livingroom
-
- esp32:
- board:
-
- binary_sensor:
- - platform: gpio
- name: "Pin GPIO23"
- pin: GPIO23
-
-See Also
---------
-
-- :doc:`nodemcu_esp32`
-- :ghedit:`Edit`
diff --git a/devices/esp8266.rst b/devices/esp8266.rst
deleted file mode 100644
index 0f922ebb2..000000000
--- a/devices/esp8266.rst
+++ /dev/null
@@ -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 `__ when the wizard
-asks you for the board type.
-
-
-.. code-block:: yaml
-
- # Example configuration entry
- esphome:
- name: livingroom
-
- esp8266:
- board:
-
-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
-`__:
-
-== ===================================
-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 `__
-
-The internal pull up/down resistors have values of 30kΩ to 100kΩ
-(`source `__).
-
-See Also
---------
-
-- :doc:`nodemcu_esp8266`
-- :ghedit:`Edit`
diff --git a/devices/nodemcu_esp32.rst b/devices/nodemcu_esp32.rst
index 164b5c514..cbfadfb6b 100644
--- a/devices/nodemcu_esp32.rst
+++ b/devices/nodemcu_esp32.rst
@@ -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`
diff --git a/devices/nodemcu_esp8266.rst b/devices/nodemcu_esp8266.rst
index 3b2d759b4..7772abafa 100644
--- a/devices/nodemcu_esp8266.rst
+++ b/devices/nodemcu_esp8266.rst
@@ -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`
diff --git a/devices/sonoff.rst b/devices/sonoff.rst
index d7844d38f..a7eaf3ce0 100644
--- a/devices/sonoff.rst
+++ b/devices/sonoff.rst
@@ -421,5 +421,5 @@ See Also
- :doc:`sonoff_s20`
- :doc:`sonoff_4ch`
- :doc:`sonoff_basic`
-- :doc:`esp8266`
+- :doc:`/components/esp8266`
- :ghedit:`Edit`
diff --git a/guides/automations.rst b/guides/automations.rst
index 20de1ecc9..785abdea0 100644
--- a/guides/automations.rst
+++ b/guides/automations.rst
@@ -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 `): 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 `): 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`
+* 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:
diff --git a/guides/creators.rst b/guides/creators.rst
index c5be31e35..e41e9ac2b 100644
--- a/guides/creators.rst
+++ b/guides/creators.rst
@@ -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.
diff --git a/guides/migrate_espeasy.rst b/guides/migrate_espeasy.rst
index 6eba19454..b0f954d63 100644
--- a/guides/migrate_espeasy.rst
+++ b/guides/migrate_espeasy.rst
@@ -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`
diff --git a/guides/migrate_espurna.rst b/guides/migrate_espurna.rst
index 3d5b82a44..09505a24e 100644
--- a/guides/migrate_espurna.rst
+++ b/guides/migrate_espurna.rst
@@ -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`
diff --git a/guides/migrate_sonoff_tasmota.rst b/guides/migrate_sonoff_tasmota.rst
index a0ada06e4..8f3accd06 100644
--- a/guides/migrate_sonoff_tasmota.rst
+++ b/guides/migrate_sonoff_tasmota.rst
@@ -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 ` 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`
diff --git a/guides/supporters.rst b/guides/supporters.rst
index cccb67bad..5fe228a0e 100644
--- a/guides/supporters.rst
+++ b/guides/supporters.rst
@@ -17,10 +17,10 @@ Contributors
(in alphabetical order)
- `0hax (@0hax) `__
-- `Nikola (@0nikola1) `__
- `0x0a11c0de (@0x0a11c0de) `__
- `Tercio Filho (@0x3333) `__
- `2016for (@2016for) `__
+- `2mikrobi (@2mikrobi) `__
- `Pavel Golovin (@31337Ghost) `__
- `David Martin (@3ative) `__
- `Alessandro Campolo (@a13ssandr0) `__
@@ -105,6 +105,7 @@ Contributors
- `Viktr (@BbIKTOP) `__
- `J. Nick Koston (@bdraco) `__
- `Maxim Ocheretianko (@bearpawmaxim) `__
+- `Benjamin Freeman (@Beetix) `__
- `Benno Pütz (@bennop) `__
- `Benoit3 (@Benoit3) `__
- `Ben Suffolk (@bensuffolk) `__
@@ -136,6 +137,7 @@ Contributors
- `Brett Profitt (@brettp) `__
- `Brian Hanifin (@brianhanifin) `__
- `brianrjones69 (@brianrjones69) `__
+- `Ben Brooks (@brooksben11) `__
- `buddydvd (@buddydvd) `__
- `Jon Little (@burundiocibu) `__
- `buxtronix (@buxtronix) `__
@@ -166,6 +168,7 @@ Contributors
- `code-review-doctor (@code-review-doctor) `__
- `CODeRUS (@CODeRUS) `__
- `Cody James (@codyjamestechnical) `__
+- `Colin Leroy-Mira (@colinleroy) `__
- `Conclusio (@Conclusio) `__
- `John Coggeshall (@coogle) `__
- `James Crook (@cooljimy84) `__
@@ -175,11 +178,13 @@ Contributors
- `Dmitry Berezovsky (@corvis) `__
- `Cougar (@Cougar) `__
- `Connor Prussin (@cprussin) `__
+- `Corey Rice (@crice009) `__
- `cryptelli (@cryptelli) `__
- `cstaahl (@cstaahl) `__
- `Chris Talkington (@ctalkington) `__
- `Massimo Cetra (@ctrix) `__
- `cvwillegen (@cvwillegen) `__
+- `Christoph Wempe (@CWempe) `__
- `cwitting (@cwitting) `__
- `Alex Solomaha (@CyanoFresh) `__
- `Luar Roji (@cyberplant) `__
@@ -232,11 +237,9 @@ Contributors
- `Dirk Heinke (@DirkHeinke) `__
- `Dirk Jahnke (@dirkj) `__
- `Johann V. (@divinitas) `__
-- `djwlindenaar (@djwlindenaar) `__
- `Marcos Pérez Ferro (@djwmarcx) `__
- `Dan Mannock (@dmannock) `__
- `Dmitriy Lopatko (@dmitriy5181) `__
-- `dmkif (@dmkif) `__
- `Farzad E. (@dnetguru) `__
- `DrZoid (@docteurzoidberg) `__
- `Dominik (@DomiStyle) `__
@@ -249,7 +252,6 @@ Contributors
- `Drew Perttula (@drewp) `__
- `drmpf (@drmpf) `__
- `DrRob (@DrRob) `__
-- `drug123 (@drug123) `__
- `Daniel Müller (@dtmuller) `__
- `dubit0 (@dubit0) `__
- `Sergey V. DUDANOV (@dudanov) `__
@@ -432,6 +434,7 @@ Contributors
- `Joe (@jhansche) `__
- `Jim Bauwens (@jimbauwens) `__
- `jimtng (@jimtng) `__
+- `Jeroen (@jjansen85) `__
- `Jérémy JOURDIN (@JJK801) `__
- `Jonathan Jefferies (@jjok) `__
- `John K. Luebs (@jkl1337) `__
@@ -444,6 +447,7 @@ Contributors
- `Johan van der Kuijl (@johanvanderkuijl) `__
- `Johboh (@Johboh) `__
- `John Erik Halse (@johnerikhalse) `__
+- `John Moxley (@johnmoxley) `__
- `JonasEr (@JonasEr) `__
- `Jonathan Adams (@jonathanadams) `__
- `Jonathan Treffler (@JonathanTreffler) `__
@@ -455,6 +459,7 @@ Contributors
- `Javier Peletier (@jpeletier) `__
- `jsuanet (@jsuanet) `__
- `James Szalay (@jtszalay) `__
+- `Julie Koubová (@juliekoubova) `__
- `Justahobby01 (@Justahobby01) `__
- `Mike Ryan (@justfalter) `__
- `Justin Gerhardt (@justin-gerhardt) `__
@@ -499,6 +504,7 @@ Contributors
- `Kyle Manna (@kylemanna) `__
- `Kalashnikov Ilya (@l1bbcsg) `__
- `Limor "Ladyada" Fried (@ladyada) `__
+- `Lakshantha Dissanayake (@lakshanthad) `__
- `Luca Adrian L (@lal12) `__
- `Fredrik Lindqvist (@Landrash) `__
- `Laszlo Gazdag (@lazlyhu) `__
@@ -546,6 +552,7 @@ Contributors
- `Ben Marengo (@marengaz) `__
- `Marvin Gaube (@margau) `__
- `Martynas Griškonis (@Margriko) `__
+- `maringeph (@maringeph) `__
- `Mario (@mario-tux) `__
- `Marek Marczykowski-Górecki (@marmarek) `__
- `Matthew Harrold (@marrold) `__
@@ -613,7 +620,6 @@ Contributors
- `Martin Weinelt (@mweinelt) `__
- `Igor Scheller (@MyIgel) `__
- `Mynasru (@Mynasru) `__
-- `Niels Ulrik Andersen (@myplacedk) `__
- `Kevin Uhlir (@n0bel) `__
- `Erik Näsström (@Naesstrom) `__
- `H. Árkosi Róbert (@nagyrobi) `__
@@ -624,7 +630,6 @@ Contributors
- `Nazar Mokrynskyi (@nazar-pc) `__
- `Bergont Nicolas (@nbergont)