diff --git a/Doxygen b/Doxygen index 24d21982a..0d7fd3113 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.1.3 +PROJECT_NUMBER = 2022.2.0b1 # 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 467ee7708..8b4daf24e 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2022.1.3 +ESPHOME_REF = 2022.2.0b1 .PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify diff --git a/_static/version b/_static/version index 6d55c1a97..97a9afacc 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2022.1.3 \ No newline at end of file +2022.2.0b1 \ No newline at end of file diff --git a/_static/webserver-v1.js b/_static/webserver-v1.js index 1f66a04a9..f82011ae5 100644 --- a/_static/webserver-v1.js +++ b/_static/webserver-v1.js @@ -2,25 +2,40 @@ const source = new EventSource("/events"); source.addEventListener('log', function (e) { const log = document.getElementById("log"); + let log_prefs = [ + ["\u001b[1;31m", 'e'], + ["\u001b[0;33m", 'w'], + ["\u001b[0;32m", 'i'], + ["\u001b[0;35m", 'c'], + ["\u001b[0;36m", 'd'], + ["\u001b[0;37m", 'v'], + ]; + let klass = ''; - if (e.data.startsWith("")) { - klass = 'e'; - } else if (e.data.startsWith("")) { - klass = 'w'; - } else if (e.data.startsWith("")) { - klass = 'i'; - } else if (e.data.startsWith("")) { - klass = 'c'; - } else if (e.data.startsWith("")) { - klass = 'd'; - } else if (e.data.startsWith("")) { - klass = 'v'; - } else { + for (const log_pref of log_prefs){ + if (e.data.startsWith(log_pref[0])) { + klass = log_pref[1]; + } + } + if (klass == ''){ log.innerHTML += e.data + '\n'; } - log.innerHTML += '' + e.data.substr(7, e.data.length - 10) + "\n"; + log.innerHTML += '' + e.data.substr(7, e.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 (e) { const data = JSON.parse(e.data); document.getElementById(data.id).children[1].innerText = data.state; @@ -32,73 +47,27 @@ for (; row = states.rows[i]; i++) { if (!row.children[2].children.length) { continue; } - - if (row.classList.contains("switch")) { - (function(id) { - row.children[2].children[0].addEventListener('click', function () { - const xhr = new XMLHttpRequest(); - xhr.open("POST", '/switch/' + id.substr(7) + '/toggle', true); - xhr.send(); - }); - })(row.id); - } - if (row.classList.contains("fan")) { - (function(id) { - row.children[2].children[0].addEventListener('click', function () { - const xhr = new XMLHttpRequest(); - xhr.open("POST", '/fan/' + id.substr(4) + '/toggle', true); - xhr.send(); - }); - })(row.id); - } - if (row.classList.contains("light")) { - (function(id) { - row.children[2].children[0].addEventListener('click', function () { - const xhr = new XMLHttpRequest(); - xhr.open("POST", '/light/' + id.substr(6) + '/toggle', true); - xhr.send(); - }); - })(row.id); - } - if (row.classList.contains("cover")) { - (function(id) { - row.children[2].children[0].addEventListener('click', function () { - const xhr = new XMLHttpRequest(); - xhr.open("POST", '/cover/' + id.substr(6) + '/open', true); - xhr.send(); - }); - row.children[2].children[1].addEventListener('click', function () { - const xhr = new XMLHttpRequest(); - xhr.open("POST", '/cover/' + id.substr(6) + '/close', true); - xhr.send(); - }); - })(row.id); - } - if (row.classList.contains("select")) { - (function(id) { + + for (const domain of actions){ + if (row.classList.contains(domain[0])) { + let id = row.id.substr(domain[0].length+1); + for (let j=0;j'+t.data.substr(7,t.data.length-10)+"\n"})),source.addEventListener("state",(function(t){const n=JSON.parse(t.data);document.getElementById(n.id).children[1].innerText=n.state}));const states=document.getElementById("states");let row,i=0;for(;row=states.rows[i];i++)row.children[2].children.length&&(row.classList.contains("switch")&&function(t){row.children[2].children[0].addEventListener("click",(function(){const n=new XMLHttpRequest;n.open("POST","/switch/"+t.substr(7)+"/toggle",!0),n.send()}))}(row.id),row.classList.contains("fan")&&function(t){row.children[2].children[0].addEventListener("click",(function(){const n=new XMLHttpRequest;n.open("POST","/fan/"+t.substr(4)+"/toggle",!0),n.send()}))}(row.id),row.classList.contains("light")&&function(t){row.children[2].children[0].addEventListener("click",(function(){const n=new XMLHttpRequest;n.open("POST","/light/"+t.substr(6)+"/toggle",!0),n.send()}))}(row.id),row.classList.contains("cover")&&function(t){row.children[2].children[0].addEventListener("click",(function(){const n=new XMLHttpRequest;n.open("POST","/cover/"+t.substr(6)+"/open",!0),n.send()})),row.children[2].children[1].addEventListener("click",(function(){const n=new XMLHttpRequest;n.open("POST","/cover/"+t.substr(6)+"/close",!0),n.send()}))}(row.id),row.classList.contains("select")&&function(t){row.children[2].children[0].addEventListener("change",(function(){const n=new XMLHttpRequest;n.open("POST","/select/"+t.substr(7)+"/set?option="+encodeURIComponent(this.value),!0),n.send()}))}(row.id),row.classList.contains("number")&&function(t){row.children[2].children[0].addEventListener("change",(function(){const n=new XMLHttpRequest;n.open("POST","/number/"+t.substr(7)+"/set?value="+encodeURIComponent(this.value),!0),n.send()}))}(row.id),row.classList.contains("button")&&function(t){row.children[2].children[0].addEventListener("click",(function(){const n=new XMLHttpRequest;n.open("POST","/button/"+t.substr(7)+"/press",!0),n.send()}))}(row.id)); +const source=new EventSource("/events");source.addEventListener("log",function(t){const e=document.getElementById("log");let n=[["","e"],["","w"],["","i"],["","c"],["","d"],["","v"]],o="";for(const e of n)t.data.startsWith(e[0])&&(o=e[1]);""==o&&(e.innerHTML+=t.data+"\n"),e.innerHTML+=''+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`. + +.. note:: + + When used with a :doc:`/components/output/gpio`, the pin will be low by default and pulled high when the button is + pressed. To invert this behaviour and have the pin pulled low when the button is pressed, set the `inverted` option + in the :ref:`config-pin_schema`. + +See Also +-------- + +- :doc:`/components/output/index` +- :apiref:`output/button/output_button.h` +- :ghedit:`Edit` diff --git a/components/button/wake_on_lan.rst b/components/button/wake_on_lan.rst new file mode 100644 index 000000000..3d702036a --- /dev/null +++ b/components/button/wake_on_lan.rst @@ -0,0 +1,32 @@ +Wake-on-LAN Button +==================== + +.. seo:: + :description: Instructions for setting up buttons that can send wakeup packets to computers on the network. + :image: radio-tower.svg + +The ``wake_on_lan`` button platform allows you to send a Wake-on-LAN magic packet to a computer on the network +by specifying its MAC address. + +.. code-block:: yaml + + # Example configuration entry + button: + - platform: wake_on_lan + name: "Start the Server" + target_mac_address: E9:48:B8:CA:58:A1 + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name for the button. +- **target_mac_address** (**Required**, MAC Address): The MAC Address of the target computer. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Button `. + +See Also +-------- + +- :doc:`template` +- :apiref:`wake_on_lan/wake_on_lan.h` +- :ghedit:`Edit` diff --git a/components/debug.rst b/components/debug.rst index c632ff41a..4c63451fc 100644 --- a/components/debug.rst +++ b/components/debug.rst @@ -7,6 +7,8 @@ Debug Component The ``debug`` component can be used to debug problems with ESPHome. At startup, it prints a bunch of useful information like reset reason, free heap size, ESPHome version and so on. +It also allows you get the same information as a text sensor, and to monitor the state of the +ESP heap memory (free space, maximum free block size and fragmentation level) and the main-loop timing. .. figure:: images/debug.png :align: center @@ -17,16 +19,86 @@ a bunch of useful information like reset reason, free heap size, ESPHome version # Example configuration entry debug: + update_interval: 5s + + text_sensor: + - platform: debug + device: + name: "Device Info" + + sensor: + - platform: debug + free: + name: "Heap Free" + fragmentation: + name: "Heap Fragmentation" + block: + name: "Heap Max Block" + loop_time: + name: "Loop Time" # Logger must be at least debug (default) logger: level: debug -No configuration variables. +Text Sensor +------------ +Configuration variables: + +- **device** (*Optional*): Reports the following device information: + + - ESPHome Version + - Free heap size at startup + - Flash chip size, speed and mode + - ESP32: + + - Chip model, cores, revision + - Chip features (BLE / BT / WiFi_BGN / EMB_FLASH / ...) + - ESP-IDF version + - EFuse MAC + - Reset reason + - Wakeup reason + - ESP8266: + + - Chip id, frequency + - Flash id + - SDK, Core & Boot versions + - Reset reason & information + + Accepts these options: + + - **name** (**Required**, string): The name of the sensor. + - All other options from :ref:`Text Sensor `. + +Sensor +------- +Configuration variables: + +- **free** (*Optional*): Reports the free heap size in bytes. + + - **name** (**Required**, string): The name of the sensor. + - All other options from :ref:`Sensor `. + +- **fragmentation** (*Optional*): Reports the fragmentation metric of the heap + (0% is clean, more than ~50% is not harmless). Only available on ESP8266 with Arduino 2.5.2+. + + - **name** (**Required**, string): The name of the sensor. + - All other options from :ref:`Sensor `. + +- **block** (*Optional*): Reports the largest contiguous free RAM block on the heap in bytes. + + - **name** (**Required**, string): The name of the sensor. + - All other options from :ref:`Sensor `. + +- **loop_time** (*Optional*): Reports the longest time between successive iterations of the main loop. + + - **name** (**Required**, string): The name of the sensor. + - All other options from :ref:`Sensor `. See Also -------- +- :ref:`sensor-filters` - :doc:`logger` - :apiref:`debug/debug_component.h` - :ghedit:`Edit` diff --git a/components/display/index.rst b/components/display/index.rst index 60431b81b..435ccdc80 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -482,6 +482,42 @@ And then later in code: - Axis labels are currently not possible without manually placing them. - The grid and border color is set with it.graph(), while the traces are defined separately. +QR Codes +******** + +Use this component to generate a QR-code containing a string on the device, which can then be drawn on compatible displays. + +.. code-block:: yaml + + qr_code: + - id: homepage_qr + value: esphome.io + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the QR-code later + in your display code. +- **value** (**Required**, string): The string which you want to encode in the QR-code. +- **ecc** (*Optional*, string): The error correction code level you want to use. Defaults to ``LOW``. You can use one of the following values: + + - ``LOW`` - The QR Code can tolerate about 7% erroneous codewords + - ``MEDIUM`` - The QR Code can tolerate about 15% erroneous codewords + - ``QUARTILE`` - The QR Code can tolerate about 25% erroneous codewords + - ``HIGH`` - The QR Code can tolerate about 30% erroneous codewords + +To draw the QR-code, call the ``it.qr_code`` function from your render lambda: + +.. code-block:: yaml + + display: + - platform: ... + # ... + pages: + - id: page1 + lambda: |- + // Draw the QR-code at position [x=50,y=0] with white color and a 2x scale + it.qr_code(50, 0, id(homepage_qr), Color(255,255,255), 2); + Images ****** @@ -507,6 +543,8 @@ Configuration variables: per pixel, 8 pixels per byte. - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. + - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel + will be the on color. Uses 1 bit per pixel, 8 pixels per byte. - **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here `__ and `here `__. diff --git a/components/display/inkplate6.rst b/components/display/inkplate6.rst index 803a5d268..df467cc86 100644 --- a/components/display/inkplate6.rst +++ b/components/display/inkplate6.rst @@ -1,13 +1,14 @@ -Inkplate 6 and Inkplate 10 -========================== +Inkplate 6, 10 and 6 Plus +========================= .. seo:: :description: Instructions for setting up Inkplate E-Paper displays in ESPHome. :image: inkplate6.jpg -All-in-one e-paper display ``Inkplate 6`` and ``Inkplate 10``. +All-in-one e-paper display ``Inkplate 6``, ``Inkplate 10`` and ``Inkplate 6 Plus``. -The Inkplate 6 and Inkplate 10 are powerful, Wi-Fi enabled ESP32 based six-inch e-paper displays – recycled from a Kindle e-reader. Its main feature is simplicity. +The Inkplate 6, 10 and 6 Plus are powerful, Wi-Fi enabled ESP32 based six-inch e-paper displays - +recycled from a Kindle e-reader. Its main feature is simplicity. Learn more at `Inkplate's website `__ @@ -73,7 +74,11 @@ Configuration variables: ************************ - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **model** (*Optional*, enum): Specify the model ``inkplate_6`` or ``inkplate_10``. Defaults to ``inkplate_6``. +- **model** (*Optional*, enum): Specify the model. Defaults to ``inkplate_6``. + - ``inkplate_6`` + - ``inkplate_10`` + - ``inkplate_6_plus`` + - **greyscale** (*Optional*, boolean): Makes the screen display 3 bit colors. Defaults to ``false`` - **partial_updating** (*Optional*, boolean): Makes the screen update partially, which is faster, but leaves burnin. Defaults to ``false`` - **full_update_every** (*Optional*, int): When partial updating is enabled, forces a full screen update after chosen number of updates. Defaults to ``10`` @@ -113,8 +118,8 @@ Configuration variables: Defaults to GPIO27. -Complete example -**************** +Complete Inkplate 6 example +*************************** The following is a complete example YAML configuration that does a few things beyond the usual Wi-Fi, API, and OTA configuration. @@ -273,9 +278,33 @@ Wi-Fi, API, and OTA configuration. } +Inkplate 6 Plus Touchscreen +*************************** + +The Inkplate 6 Plus has a built in touchscreen supported by ESPHome. +Below is a config example: + +.. code-block:: yaml + + touchscreen: + - platform: ektf2232 + interrupt_pin: GPIO36 + rts_pin: + mcp23xxx: mcp23017_hub + number: 10 + on_touch: + - logger.log: + format: "Touch: {x}, {y}" + args: + - touch.x + - touch.y + + + See Also -------- - :doc:`index` +- :doc:`/components/touchscreen/ektf2232` - `Arduino Inkplate 6 library `__ by `E-radionica.com `__ - :ghedit:`Edit` diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst index cd0a2a599..5eebf2e98 100644 --- a/components/display/waveshare_epaper.rst +++ b/components/display/waveshare_epaper.rst @@ -92,6 +92,7 @@ Configuration variables: - ``4.20in-bV2`` (B/W rendering only) - ``5.83in`` - ``7.50in`` + - ``7.50in-bV2`` (also supports v3, B/W rendering only) - ``7.50in-bc`` (display with version sticker '(C)' on the back, B/W rendering only) - ``7.50inV2`` (Can't use with an ESP8266 as it runs out of RAM) diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst index 6746014db..4f2757bac 100644 --- a/components/esp32_camera.rst +++ b/components/esp32_camera.rst @@ -74,6 +74,9 @@ Frame Settings: Up to 60Hz is possible (with reduced frame sizes), but beware of overheating. Defaults to ``10 fps``. - **idle_framerate** (*Optional*, float): The framerate to capture images at when no client is requesting a full stream. Defaults to ``0.1 fps``. + +Image Settings: + - **resolution** (*Optional*, enum): The resolution the camera will capture images at. Higher resolutions require more memory, if there's not enough memory you will see an error during startup. @@ -90,15 +93,64 @@ Frame Settings: - **jpeg_quality** (*Optional*, int): The JPEG quality that the camera should encode images with. From 10 (best) to 63 (worst). Defaults to ``10``. - +- **vertical_flip** (*Optional*, boolean): Whether to flip the image vertically. Defaults to ``true``. +- **horizontal_mirror** (*Optional*, boolean): Whether to mirror the image horizontally. Defaults to ``true``. - **contrast** (*Optional*, int): The contrast to apply to the picture, from -2 to 2. Defaults to ``0``. - **brightness** (*Optional*, int): The brightness to apply to the picture, from -2 to 2. Defaults to ``0``. - **saturation** (*Optional*, int): The saturation to apply to the picture, from -2 to 2. Defaults to ``0``. -- **vertical_flip** (*Optional*, boolean): Whether to flip the image vertically. Defaults to ``true``. -- **horizontal_mirror** (*Optional*, boolean): Whether to mirror the image horizontally. Defaults to ``true``. -- **aec2** (*Optional*, boolean): Whether to enable Auto Exposure Control 2. Defaults to ``false``. -- **ae_level** (*Optional*, int): The auto exposure level to apply to the picture, from -2 to 2. Defaults to ``0``. -- **aec_value** (*Optional*, int): The Auto Exposure Control 2 value to apply to the picture, from 0 to 1200. Defaults to ``300``. +- **special_effect** (*Optional*, enum): The effect to apply to the picture. Defaults to ``none`` (picture without effect). + + - ``none``: Picture without effect + - ``negative``: Colors of picture are inverted + - ``grayscale``: Only luminance of picture is kept + - ``red_tint``: Picture appear red-tinted + - ``green_tint``: Picture appear green-tinted + - ``blue_tint``: Picture appear blue-tinted + - ``sepia``: Sepia effect is applied to picture + +Exposure Settings: + +- **aec_mode** (*Optional*, enum): The mode of exposure module. Defaults to ``auto`` (leave camera to automatically adjust exposure). + + - ``manual``: Exposure can be manually set, with **aec_value** parameter. **ae_level** has no effect here + - ``auto``: Camera manage exposure automatically. Compensation can be applied, thanks to **ae_level** parameter. **aec_value** has no effect here + +- **aec2** (*Optional*, boolean): Whether to enable Auto Exposure Control 2. Seems to change computation method of automatic exposure. Defaults to ``false``. +- **ae_level** (*Optional*, int): The auto exposure level to apply to the picture (when **aec_mode** is set to ``auto``), from -2 to 2. Defaults to ``0``. +- **aec_value** (*Optional*, int): The Exposure value to apply to the picture (when **aec_mode** is set to ``manual``), from 0 to 1200. Defaults to ``300``. + +Sensor Gain Settings: + +- **agc_mode** (*Optional*, enum): The mode of gain control module. Defaults to ``auto`` (leave camera to automatically adjust sensor gain). + + - ``manual``: Gain can be manually set, with **agc_value** parameter. **agc_gain_ceiling** has no effect here + - ``auto``: Camera manage sensor gain automatically. Maximum gain can be defined, thanks to **agc_gain_ceiling** parameter. **agc_value** has no effect here + +- **agc_value** (*Optional*, int): The gain value to apply to the picture (when **aec_mode** is set to ``manual``), from 0 to 30. Defaults to ``0``. +- **agc_gain_ceiling** (*Optional*, enum): The maximum gain allowed, when **agc_mode** is set to ``auto``. This parameter seems act as "ISO" setting. Defaults to ``2x``. + + - ``2x``: Camera is less sensitive, picture is clean (without visible noise) + - ``4x`` + - ``8x`` + - ``16x`` + - ``32x`` + - ``64x`` + - ``128x``: Camera is more sensitive, but picture contain lot of noise + +White Balance Setting: + +- **wb_mode** (*Optional*, enum): The mode of white balace module. Defaults to ``auto``. + + - ``auto``: Camera choose best white balance setting + - ``sunny``: White balance sunny mode + - ``cloudy``: White balance cloudy mode + - ``office``: White balance office mode + - ``home``: White balance home mode + +Test Setting: + +- **test_pattern** (*Optional*, boolean): For tests purposes, it's possible to replace picture get from sensor by a test color pattern. Defaults to ``false``. + .. note:: diff --git a/components/ethernet.rst b/components/ethernet.rst index 1a296c886..7ff2b3f34 100644 --- a/components/ethernet.rst +++ b/components/ethernet.rst @@ -150,6 +150,7 @@ Configuration for Wireless Tag WT32-ETH01 See Also -------- +- :doc:`network` - :apiref:`ethernet/ethernet_component.h` - `ESP32 Ethernet PHY connection info `__ - :ghedit:`Edit` diff --git a/components/fan/hbridge.rst b/components/fan/hbridge.rst index 2aacdb4d5..dc145aee9 100644 --- a/components/fan/hbridge.rst +++ b/components/fan/hbridge.rst @@ -5,7 +5,7 @@ H-bridge Fan :description: Instructions for setting up hbridge controlled fans (or motors). :image: fan.svg -The `'hbridge`' fan platform allows you to use a compatible `h-bridge` (L298N, DRV8871, MX1508, BTS7960, L9110S, DRV8833, TB6612, etc.) to control a fan (or motor/solenoid). +The ``hbridge`` fan platform allows you to use a compatible `h-bridge` (L298N, DRV8871, MX1508, BTS7960, L9110S, DRV8833, TB6612, etc.) to control a fan (or motor/solenoid). .. figure:: images/L298N_module.jpg :align: center diff --git a/components/fan/index.rst b/components/fan/index.rst index 4809f2432..1fe4f2b51 100644 --- a/components/fan/index.rst +++ b/components/fan/index.rst @@ -6,11 +6,9 @@ Fan Component :image: folder-open.svg With the ``fan`` domain you can create components that appear as fans in -the Home Assistant frontend. A fan can be switched ON or OFF, optionally -has a speed level between 1 and the maximum supported speed level of the fan, and can have an -oscillate and direction output. - -This component restores its state on reboot/reset. +the Home Assistant frontend. A fan can be switched on or off, optionally +has a speed between 1 and the maximum supported speed of the fan, and can have an +oscillation and direction output. .. figure:: images/fan-ui.png :align: center @@ -30,10 +28,20 @@ Configuration variables: - **name** (**Required**, string): The name of the fan. - **icon** (*Optional*, icon): Manually set the icon to use for the fan in the frontend. +- **restore_mode** (*Optional*): Control how the fan attempts to restore state on boot. + + - ``NO_RESTORE`` - Don't restore any state. + - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore (default). + - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. + - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF. + - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON. + - ``ALWAYS_OFF`` - Always initialize the fan as OFF on bootup. + - ``ALWAYS_ON`` - Always initialize the fan as ON on bootup. + - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without a ``name`` will implicitly set this to true. -- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend, +- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Requires Home Assistant 2021.9 or newer. Defaults to ``false``. - **entity_category** (*Optional*, string): The category of the entity. @@ -116,7 +124,7 @@ Configuration options: - **speed** (*Optional*, int, :ref:`templatable `): Set the speed level of the fan. Can be a number between 1 and the maximum speed level of the fan. - **direction** (*Optional*, string, :ref:`templatable `): - Set the diretion of the fan. Can be either ``forward`` or ``reverse``. Defaults to not changing the direction. + Set the direction of the fan. Can be either ``forward`` or ``reverse``. Defaults to not changing the direction. .. _fan-cycle_speed_action: @@ -138,7 +146,7 @@ Increments through speed levels of the fan with the given ID when executed. If t ``fan.is_on`` / ``fan.is_off`` Condition ---------------------------------------- -This :ref:`condition ` passes if the given fan is on/off. +This :ref:`condition ` passes if the given fan is on or off. .. code-block:: yaml @@ -228,7 +236,7 @@ advanced stuff (see the full API Reference for more info). .. code-block:: yaml // Within lambda, get the fan direction and conditionally do something - if (id(my_fan).direction == FanDirection::FAN_DIRECTION_FORWARD) { + if (id(my_fan).direction == FanDirection::FORWARD) { // Fan direction is forward, do something here } else { // Fan direction is reverse, do something else here @@ -248,7 +256,7 @@ advanced stuff (see the full API Reference for more info). auto call = id(my_fan).turn_on(); call.set_speed(2); call.set_oscillating(true); - call.set_direction(FanDirection::FAN_DIRECTION_REVERSE); + call.set_direction(FanDirection::REVERSE); call.perform(); // Toggle the fan on/off diff --git a/components/fingerprint_grow.rst b/components/fingerprint_grow.rst index 6edddd3ff..b972c88db 100644 --- a/components/fingerprint_grow.rst +++ b/components/fingerprint_grow.rst @@ -5,7 +5,7 @@ Grow Fingerprint Reader :description: Instructions for setting up Grow Fingerprint Reader integration in ESPHome. :image: fingerprint.svg -The ``fingerprint_grow`` component allows you to use your R307, R503, ZFM-20, ... fingerprint sensors with ESPHome. +The ``fingerprint_grow`` component allows you to use your R307, R503, R503-RGB, ZFM-20, ... fingerprint sensors with ESPHome. .. figure:: images/r307-full.jpg :align: center @@ -25,7 +25,7 @@ Component/Hub The reader can be powered by the 3.3V output of an NodeMCU. As the communication with the reader is done using UART (default baud rate is 57600), you need to have an :ref:`UART bus ` in your configuration with the ``rx_pin`` connected to the reader's ``TX`` and the ``tx_pin`` connected to the reader's ``RX``. -If available on your reader model, it's recommended to connect 3.3VT (touch induction power supply) to 3.3V; WAKEUP (finger detection signal) to a free GPIO pin and define it with the ``sensing_pin`` option to allow the polling function to quickly return when there's no finger on the reader. +If available on your reader model, it's recommended to connect 3.3VT (touch induction power supply) & 3.3V to 3.3V; WAKEUP (finger detection signal) to a free GPIO pin and define it with the ``sensing_pin`` option to allow the polling function to quickly return when there's no finger on the reader. .. code-block:: yaml @@ -353,7 +353,7 @@ Removes all enrolled fingerprints. ``fingerprint_grow.led_control`` Action --------------------------------------- -Turns on or off the LED on the reader. Only available on select models. If you have the R503 use :ref:`fingerprint_grow-aura_led_control` instead. +Turns on or off the LED on the reader. Only available on select models. If you have the R503 or R503-RGB use :ref:`fingerprint_grow-aura_led_control` instead. .. code-block:: yaml @@ -373,7 +373,7 @@ Configuration options: ``fingerprint_grow.aura_led_control`` Action -------------------------------------------- -Controls the Aura LED on the reader. Only available on select models. +Controls the Aura LED on the reader. Only available on select models. NOTE: The R503 has 2 variants with different LED colour options. .. code-block:: yaml @@ -434,7 +434,7 @@ Configuration options: - **state** (**Required**, string, :ref:`templatable `): The state to set the LED. One of ``BREATHING``, ``FLASHING``, ``ALWAYS_ON``, ``ALWAYS_OFF``, ``GRADUAL_ON`` and ``GRADUAL_OFF``. - **speed** (**Required**, int, :ref:`templatable `): The duration each cycle lasts, a factor of 10ms. Only relevant for ``BREATHING``, ``FLASHING``, ``GRADUAL_ON`` and ``GRADUAL_OFF`` states. The total duration is defined by 10ms * speed * count. Range is 0 to 255. -- **color** (**Required**, string, :ref:`templatable `): The LED color to activate. One of ``RED``, ``BLUE`` and ``PURPLE``. +- **color** (**Required**, string, :ref:`templatable `): The LED color to activate. For R503, one of ``RED``, ``BLUE`` and ``PURPLE``. For R503-RGB, one of ``RED``, ``BLUE``, ``PURPLE``, ``GREEN``, ``YELLOW``, ``CYAN`` and ``WHITE``. - **count** (**Required**, int, :ref:`templatable `): How many times to repeat the pattern. Only relevant for ``BREATHING`` and ``FLASHING`` states. 0 for infinite, or 1 to 255. All actions diff --git a/components/http_request.rst b/components/http_request.rst index ff1813f4e..7dadaf537 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -22,6 +22,8 @@ Configuration variables: - **useragent** (*Optional*, string): User-Agent header for requests. Defaults to ``ESPHome``. - **timeout** (*Optional*, :ref:`config-time`): Timeout for request. Defaults to ``5s``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **follow_redirects** (*Optional*, boolean): Enable following HTTP redirects. Defaults to ``true``. +- **redirect_limit** (*Optional*, integer): Maximum amount of redirects to follow when enabled. Defaults to ``3``. ESP8266 Options: diff --git a/components/index.rst b/components/index.rst index 3bc1dc371..2fb325b11 100644 --- a/components/index.rst +++ b/components/index.rst @@ -18,4 +18,6 @@ Components display/index text_sensor/index stepper/index + touchscreen/index + lock/index * diff --git a/components/light/index.rst b/components/light/index.rst index 21fd75887..a9f53da61 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -405,10 +405,10 @@ with the behavior of the ``light.is_on`` and ``light.is_off`` condition above. ``light.on_state`` Trigger ************************** -This trigger is activated each time the set light state is changed. It is not triggered +This trigger is activated each time the set light state is changed. It is not triggered based on current state, but rather, it triggers on the set state which can differ from the current state due to transitions. For example, the ``light.on_state`` trigger can -be used for immediate action when the light is set to off; while ``light.on_turn_off`` +be used for immediate action when the light is set to off; while ``light.on_turn_off`` does not trigger until the light actually achieves the off state. .. code-block:: yaml @@ -586,6 +586,10 @@ Lambda Effect This effect allows you to write completely custom light effects yourself using :ref:`lambdas `. +Available variable in the lambda: + +- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting an effect. + .. code-block:: yaml light: @@ -622,6 +626,7 @@ Configuration variables: - **lambda** (**Required**, :ref:`lambda `): The code to execute. ``static`` variables are especially useful. + Addressable Rainbow Effect ************************** diff --git a/components/lock/images/output-ui.png b/components/lock/images/output-ui.png new file mode 100644 index 000000000..2a9bc2803 Binary files /dev/null and b/components/lock/images/output-ui.png differ diff --git a/components/lock/index.rst b/components/lock/index.rst new file mode 100644 index 000000000..2924e9cf2 --- /dev/null +++ b/components/lock/index.rst @@ -0,0 +1,166 @@ +Lock Component +================ + +.. seo:: + :description: Instructions for setting up generic locks in ESPHome. + :image: folder-open.svg + +The ``lock`` domain includes all platforms that should function like a lock +with lock/unlock actions. + +.. note:: + + ESPHome lock components requires Home Assistant 2022.3 or newer + +.. _config-lock: + +Base Lock Configuration +------------------------- + +.. code-block:: yaml + + lock: + - platform: ... + name: "Lock Name" + +Configuration variables: + +- **name** (**Required**, string): The name of the lock. +- **icon** (*Optional*, icon): Manually set the icon to use for the + lock in the frontend. +- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will + not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without + a ``name`` will implicitly set this to true. +- **on_lock** (*Optional*, :ref:`Action `): An automation to perform + when the lock is locked. See :ref:`lock-on_lock_unlock_trigger`. +- **on_unlock** (*Optional*, :ref:`Action `): An automation to perform + when the lock is unlocked. See :ref:`lock-on_lock_unlock_trigger`.. +- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend, + (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). + Defaults to ``false``. +- **entity_category** (*Optional*, string): The category of the entity. + See https://developers.home-assistant.io/docs/core/entity/#generic-properties + for a list of available options. Set to ``""`` to remove the default entity category. +- If MQTT enabled, All other options from :ref:`MQTT Component `. + +.. _lock-lock_action: + +``lock.lock`` Action +************************* + +This action locks a lock with the given ID on when executed. + +.. code-block:: yaml + + on_...: + then: + - lock.lock: deadbolt_1 + +.. _lock-unlock_action: + +``lock.unlock`` Action +************************** + +This action unlocks a lock with the given ID off when executed. + +.. code-block:: yaml + + on_...: + then: + - lock.unlock: deadbolt_1 + +.. _lock-open_action: + +``lock.open`` Action +************************ + +This action opens (e.g. unlatch) a lock with the given ID off when executed. + +.. code-block:: yaml + + on_...: + then: + - lock.open: doorlock_1 + +.. _lock-is_locked_condition: +.. _lock-is_unlocked_condition: + +``lock.is_locked`` / ``lock.is_unlocked`` Condition +*************************************************** + +This :ref:`Condition ` checks if the given lock is LOCKED (or UNLOCKED). + +.. code-block:: yaml + + # In some trigger: + on_...: + if: + condition: + # Same syntax for is_unlocked + lock.is_locked: my_lock + +.. _lock-lambda_calls: + +lambda calls +************ + +From :ref:`lambdas `, you can call several methods on all locks to do some +advanced stuff (see the full API Reference for more info). + +- ``publish_state()``: Manually cause the lock to publish a new state and store it internally. + If it's different from the last internal state, it's additionally published to the frontend. + + .. code-block:: yaml + + // Within lambda, make the lock report a specific state + id(my_lock).publish_state(LOCK_STATE_LOCKED); + id(my_lock).publish_state(LOCK_STATE_UNLOCKED); + +- ``state``: Retrieve the current state of the lock. + + .. code-block:: yaml + + // Within lambda, get the lock state and conditionally do something + if (id(my_lock).state == LOCK_STATE_LOCKED) { + // Lock is LOCKED, do something here + } + +- ``unlock()``/``lock()``/``open()``: Manually lock/unlock/open a lock from code. + Similar to the ``lock.lock``, ``lock.unlock``, and ``lock.open`` actions, + but can be used in complex lambda expressions. + + .. code-block:: yaml + + id(my_lock).unlock(); + id(my_lock).lock(); + id(my_lock).open(); + +.. _lock-on_lock_unlock_trigger: + +``lock.on_lock`` / ``lock.on_unlock`` Trigger +**************************************************************** + +This trigger is activated each time the lock is locked/unlocked. It becomes active +right after the lock component has acknowledged the state (e.g. after it LOCKED/UNLOCKED itself). + +.. code-block:: yaml + + lock: + - platform: template # or any other platform + # ... + on_lock: + - logger.log: "Door Locked!" + on_unlock: + - logger.log: "Door Unlocked!" + +See Also +-------- + +- :apiref:`lock/lock.h` +- :ghedit:`Edit` + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/components/lock/output.rst b/components/lock/output.rst new file mode 100644 index 000000000..282763eb7 --- /dev/null +++ b/components/lock/output.rst @@ -0,0 +1,39 @@ +Generic Output Lock +===================== + +.. seo:: + :description: Instructions for setting up generic output locks in ESPHome that control an output component. + :image: upload.svg + +The ``output`` lock platform allows you to use any output component as a lock. + +.. figure:: images/output-ui.png + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration entry + output: + - platform: gpio + pin: 25 + id: 'generic_out' + lock: + - platform: output + name: "Generic Output" + output: 'generic_out' + +Configuration variables: +------------------------ + +- **output** (**Required**, :ref:`config-id`): The ID of the output component to use. +- **name** (**Required**, string): The name for the lock. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Lock `. + +See Also +-------- + +- :doc:`/components/output/index` +- :apiref:`output/lock/output_lock.h` +- :ghedit:`Edit` diff --git a/components/lock/template.rst b/components/lock/template.rst new file mode 100644 index 000000000..da81965c1 --- /dev/null +++ b/components/lock/template.rst @@ -0,0 +1,115 @@ +Template Lock +=============== + +.. seo:: + :description: Instructions for setting up template locks that can execute arbitrary actions when locked, unlocked, or opened + :image: description.svg + +The ``template`` lock platform allows you to create simple locks out of just actions and +an optional value lambda. Once defined, it will automatically appear in Home Assistant +as a lock and can be controlled through the frontend. + +.. code-block:: yaml + + # Example configuration entry + lock: + - platform: template + name: "Template Lock" + lambda: |- + if (id(some_binary_sensor).state) { + return LOCK_STATE_LOCKED; + } else { + return LOCK_STATE_UNLOCKED; + } + lock_action: + - switch.turn_on: switch1 + unlock_action: + - switch.turn_off: switch1 + open_action: + - button.press: button1 + + +Possible return values for the optional lambda: + + - ``return LOCK_STATE_LOCKED;`` if the lock should be reported as LOCKED. + - ``return LOCK_STATE_UNLOCKED;`` if the lock should be reported as UNLOCKED. + - ``return LOCK_STATE_JAMMED;`` if the lock should be reported as JAMMED. + - ``return LOCK_STATE_LOCKING;`` if the lock should be reported as LOCKING. + - ``return LOCK_STATE_UNLOCKING;`` if the lock should be reported as UNLOCKING. + - ``return {};`` if the last state should be repeated. + +.. note:: + + Only ``LOCK_STATE_LOCKED`` and ``LOCK_STATE_UNLOCKED`` are supported by the MQTT component in Home Assistant + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the lock. +- **lambda** (*Optional*, :ref:`lambda `): + Lambda to be evaluated repeatedly to get the current state of the lock. +- **lock_action** (*Optional*, :ref:`Action `): The action that should + be performed when the remote (like Home Assistant's frontend) requests the lock to be locked. +- **unlock_action** (*Optional*, :ref:`Action `): The action that should + be performed when the remote (like Home Assistant's frontend) requests the lock to be unlocked. +- **restore_state** (*Optional*, boolean): Sets whether ESPHome should attempt to restore the + state on boot-up and call the lock/unlock actions with the recovered values. Defaults to ``no``. +- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode, + any command sent to the template lock will immediately update the reported state. + Defaults to ``false``. +- **assumed_state** (*Optional*, boolean): Whether the true state of the lock is not known. + This will make the Home Assistant frontend show buttons for both LOCK and UNLOCK actions, instead + of hiding one of them when the lock is LOCKED/UNLOCKED. Defaults to ``false``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Lock `. + +.. _lock-template-publish_action: + +``lock.template.publish`` Action +---------------------------------- + +You can also publish a state to a template lock from elsewhere in your YAML file +with the ``lock.template.publish`` action. + +.. code-block:: yaml + + # Example configuration entry + lock: + - platform: template + name: "Template Lock" + id: template_lock1 + + # in some trigger + on_...: + - lock.template.publish: + id: template_lock1 + state: LOCK_STATE_LOCKED + + # Templated + - lock.template.publish: + id: template_lock1 + state: !lambda 'return LOCK_STATE_LOCKED;' + +Configuration options: + +- **id** (**Required**, :ref:`config-id`): The ID of the template lock. +- **state** (**Required**, boolean, :ref:`templatable `): + The state to publish. + +.. note:: + + This action can also be written in lambdas, the parameter of the `publish_state` method denotes the state the + lock should become: + + .. code-block:: cpp + + id(template_lock1).publish_state(lock::LOCK_STATE_LOCKED); + +See Also +-------- + +- :doc:`/guides/automations` +- :doc:`/components/lock/index` +- :doc:`/components/binary_sensor/index` +- :apiref:`template/lock/template_lock.h` +- :ghedit:`Edit` diff --git a/components/mqtt.rst b/components/mqtt.rst index 6a729a647..b7bd12c15 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -47,6 +47,9 @@ Configuration variables: to use. Can be one of ``legacy`` or ``mac``. Defaults to ``legacy``, which generates unique_id in format ``ESP``. ``mac`` generator uses format ``--``. +- **discovery_object_id_generator** (*Optional*, string): The object_id generator + to use. Can be one of ``none`` or ``device_name``. Defaults to ``none`` which + does not generate object_id. ``device_name`` generator uses format ``_``. - **use_abbreviations** (*Optional*, boolean): Whether to use `Abbreviations `__ in discovery messages. Defaults to ``true``. @@ -160,6 +163,17 @@ This will remove all retained messages with the topic ``/+/NODE_NAME/#``. If you want to purge on another topic, simply add ``--topic `` to the command. +Home Assistant generates entity names for all discovered devices based on entity type and +entity name (e.g. ``sensor.uptime``). Numeric suffixes are appended to entity names when +multiple devices use the same name for a sensor, making it harder to distinguish between +similar sensors on different devices. Home Assistant 2021.12 allows MQTT devices to change +this behaviour by specifying ``object_id`` discovery attribute which replaces the sensor +name part of the generated entity name. Setting ``discovery_object_id_generator: device_name`` +in ESPHome MQTT integration configuration will cause Home Assistant to include device name +in the generated entity names (e.g. ``sensor.uptime`` becomes ``sensor._uptime``), +making it easier to distinguish the entities in various entity lists. + + .. _mqtt-defaults: Defaults @@ -266,6 +280,7 @@ MQTT can have some overrides for specific options. payload_not_available: offline state_topic: livingroom/custom_state_topic command_topic: livingroom/custom_command_topic + command_retain: false Configuration variables: @@ -284,6 +299,8 @@ Configuration variables: - **command_topic** (*Optional*, string): The topic to subscribe to for commands from the remote. Defaults to ``///command``. +- **command_retain** (*Optional*, boolean): Whether MQTT command messages + sent to the device should be retained or not. Default to ``false``. .. warning:: diff --git a/components/network.rst b/components/network.rst new file mode 100644 index 000000000..cef73dc24 --- /dev/null +++ b/components/network.rst @@ -0,0 +1,22 @@ +Network component +================= + +.. seo:: + :description: + :image: network-wifi.svg + :keywords: Network, WiFi, WLAN, Ethernet, ESP32 + +The network component is a global configuration for all types of +networks (WiFi, Ethernet). + +.. code-block:: yaml + + # Example configuration + network: + enable_ipv6: true + +Configuration variables: +------------------------ + +- **enable_ipv6** (*Optional*, boolean): Enables IPv6 support. Defaults to ``false``. Only available on ESP32 with ESP-IDF framework. + diff --git a/components/output/ble_client.rst b/components/output/ble_client.rst index 38ef7111a..bda99d4e9 100644 --- a/components/output/ble_client.rst +++ b/components/output/ble_client.rst @@ -25,6 +25,7 @@ For more information on BLE services and characteristics, see ble_client_id: itag_black service_uuid: "10110000-5354-4F52-5A26-4249434B454C" characteristic_uuid: "10110013-5354-4f52-5a26-4249434b454c" + require_response: false Configuration variables: ------------------------ @@ -33,6 +34,8 @@ Configuration variables: - **service_uuid** (**Required**, UUID): UUID of the service on the device. - **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to write to. - **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. +- **require_response** (*Optional*, boolean): Control whether to require a remote response from the device when writing. + Whether or not this is required will vary by device. Defaults to ``false`` - All other options from :ref:`Output `. See Also diff --git a/components/output/slow_pwm.rst b/components/output/slow_pwm.rst index c23d5b7d4..ccb3781ca 100644 --- a/components/output/slow_pwm.rst +++ b/components/output/slow_pwm.rst @@ -37,7 +37,9 @@ Configuration variables: - **state_change_action** (*Optional*, :ref:`Automation `): An automation to perform when the load is switched. If a lambda is used the boolean ``state`` parameter holds the new status. - **turn_on_action** (*Optional*, :ref:`Automation `): An automation to perform when the load is turned on. Can be used to control for example a switch or output component. - **turn_off_action** (*Optional*, :ref:`Automation `): An automation to perform when the load is turned off. ``turn_on_action`` and ``turn_off_action`` must be configured together. - +- **restart_cycle_on_state_change** (*Optional*, boolean): Restart a timer of a cycle + when new state is set. Defaults to ``false``. + - All other options from :ref:`Output `. diff --git a/components/select/modbus_controller.rst b/components/select/modbus_controller.rst new file mode 100644 index 000000000..b34cd8c23 --- /dev/null +++ b/components/select/modbus_controller.rst @@ -0,0 +1,143 @@ +Modbus Controller Select +======================== + +.. seo:: + :description: Instructions for setting up Modbus Controller Select(s) with ESPHome. + +The ``modbus_controller`` Select platform allows you to create a Select from modbus +registers. + +.. code-block:: yaml + + # Example configuration entry + select: + - platform: modbus_controller + name: "Modbus Select Register 1000" + address: 1000 + value_type: U_WORD + optionsmap: + "Zero": 0 + "One": 1 + "Two": 2 + "Three": 3 + + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the Select. +- **address**: (**Required**, int): The start address of the first or only register + of the Select. +- **optionsmap**: (**Required**, Map[str, int]): Provide a mapping from options (str) of + this Select to values (int) of the modbus register and vice versa. All options and + all values have to be unique. +- **value_type**: (*Optional*): The datatype of the modbus data. Defaults to ``U_WORD``. + - ``U_WORD`` (unsigned 16 bit integer from 1 register = 16bit) + - ``S_WORD`` (signed 16 bit integer from 1 register = 16bit) + - ``U_DWORD`` (unsigned 32 bit integer from 2 registers = 32bit) + - ``S_DWORD`` (signed 32 bit integer from 2 registers = 32bit) + - ``U_DWORD_R`` (unsigned 32 bit integer from 2 registers low word first) + - ``S_DWORD_R`` (signed 32 bit integer from 2 registers low word first) + - ``U_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) + - ``S_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) + - ``U_QWORD_R`` (unsigned 64 bit integer from 4 registers low word first) + - ``U_QWORD_R`` (signed 64 bit integer from 4 registers low word first) +- **register_count**: (*Optional*): The number of registers which are used for this Select. Only + required for uncommon response encodings or to + :ref:`optimize modbus communications`. Overrides the defaults determined + by ``value_type``. +- **skip_updates**: (*Optional*, int): By default all sensors of of a modbus_controller are + updated together. For data points that don't change very frequently updates can be skipped. A + value of 5 would only update this sensor range in every 5th update cycle. Defaults to ``0``. + Note: The modbus_controller merges several registers into groups which are updated together. For + each group the smallest update cycle is used. +- **force_new_range**: (*Optional*, boolean): If possible sensors with sequential addresses are + grouped together and requested in one range. Setting this to ``true`` enforces the start of a new + range at that address. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated every update interval + to get the current option of the select. +- **write_lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated on every update + of the Sensor, before the new value is written to the modbus registers. +- **use_write_multiple**: (*Optional*, boolean): By default the modbus command ``Preset Single Registers`` + (function code 6) is used for setting the holding register if only 1 register is set. If your device only supports *Preset Multiple Registers* (function code 16) set this option to ``true``. Defaults + to ``false``. +- All other options from :ref:`Select `. + + +Parameters passed into ``lambda`` +--------------------------------- + +- **x** (``int64_t``): The parsed integer value of the modbus data. +- **data** (``const std::vector&``): vector containing the complete raw modbus response bytes for this + sensor. Note: because the response contains data for all registers in the same range you have to + use ``data[item->offset]`` to get the first response byte for your sensor. +- **item** (``ModbusSelect*const``): The sensor object itself. + +Possible return values for the lambda: + + - ``return ;`` The new option for this Select. + - ``return {};`` Use default mapping (see ``optionsmap``). + +.. code-block:: yaml + + # example + lambda: |- + ESP_LOGD("Reg1000", "Received value %lld", x); + ESP_LOGD("Reg1000", "Parsed from bytes 0x%x;0x%x", data[item->offset], data[item->offset + 1]); + if (x > 3) { + return std::string("Three"); + } + + +Parameters passed into ``write_lambda`` +--------------------------------------- + +- **x** (``const std::string&``): The option value to set for this Select. +- **value** (``int64_t``): The mapping value of ``x`` using ``optionsmap``. +- **payload** (``std::vector& payload``): Empty vector for the payload. The lamdba can add + 16 bit raw modbus register words which are send to the modbus device. +- **item** (``ModbusSelect*const``): The sensor object itself. + +Possible return values for the lambda: + + - ``return ;`` the value which should be written to the configured modbus registers. If there were data written to ``payload`` this value is ignored. + - ``return {};`` Skip updating the register. + +.. code-block:: yaml + + # example + write_lambda: |- + ESP_LOGD("Reg1000", "Set option to %s (%lld)", x.c_str(), value); + + // re-use default option value from optionsmap + if (value == 0) { + return value; + } + + // return own option value + if (x == "One") { + return 2; + } + + // write payload + if (x == "Two") { + payload.push_back(0x0001); + return 0; // any value will do + } + + // ignore update + return {}; + + +See Also +-------- +- :doc:`/components/modbus_controller` +- :doc:`/components/sensor/modbus_controller` +- :doc:`/components/binary_sensor/modbus_controller` +- :doc:`/components/switch/modbus_controller` +- :doc:`/components/text_sensor/modbus_controller` +- :doc:`/components/output/modbus_controller` +- :ref:`automation` +- https://www.modbustools.com/modbus.html +- :ghedit:`Edit` diff --git a/components/sensor/cd74hc4067.rst b/components/sensor/cd74hc4067.rst index 5925256a4..1be0db126 100644 --- a/components/sensor/cd74hc4067.rst +++ b/components/sensor/cd74hc4067.rst @@ -14,7 +14,7 @@ and there are also some guides around like the one from `Adam Meyer `) and pass it to the cd74hc4067 sensors with the ``sensor`` option. Each cd74hc4067 sensor is configured for one of the 16 input pins of the multiplexer. @@ -22,20 +22,21 @@ Each cd74hc4067 sensor is configured for one of the 16 input pins of the multipl # Example configuration entry cd74hc4067: - pin_s0: D0 - pin_s1: D1 - pin_s2: D2 - pin_s3: D3 + - id: cd74hc4067_1 + pin_s0: D0 + pin_s1: D1 + pin_s2: D2 + pin_s3: D3 sensor: - - platform: adc + - platform: adc id: adc_sensor pin: A0 - - platform: cd74hc4067 + - platform: cd74hc4067 id: adc_0 number: 0 sensor: adc_sensor - - platform: cd74hc4067 + - platform: cd74hc4067 id: adc_1 number: 1 sensor: adc_sensor @@ -56,13 +57,14 @@ Configuration Variables: ************************ - **sensor** (**Required**, :ref:`config-id`): The source sensor to measure voltage values from, e.g. :doc:`ADC sensor `. +- **cd74hc4067_id** (**Required**, :ref:`config-id`): The id of the cd74hc4067 component to use for this sensor. - **number** (*Required*, int): The number of the cd74hc4067 input pin (0-15) - All other options from :ref:`Sensor `. Application Example ------------------- -In this example, the component is used to measure the AC power output of two solar inverters to integrate them +In this example, the component is used to measure the AC power output of two solar inverters to integrate them as energy sources in `Home Assistant `__. For this purpose, :doc:`CT clamp sensors ` are attached on each of the sensors. @@ -72,42 +74,43 @@ The ``adc`` and ``cd74hc4067`` sensors updates are triggered by the ``ct_clamp`` .. code-block:: yaml cd74hc4067: - pin_s0: D0 - pin_s1: D1 - pin_s2: D2 - pin_s3: D3 + - id: cd74hc4067_1 + pin_s0: D0 + pin_s1: D1 + pin_s2: D2 + pin_s3: D3 sensor: - - platform: adc + - platform: adc id: adc_sensor pin: A0 update_interval: 3600s - - platform: cd74hc4067 + - platform: cd74hc4067 id: solar_1_raw number: 0 sensor: adc_sensor update_interval: 3600s - - platform: cd74hc4067 + - platform: cd74hc4067 id: solar_2_raw number: 1 sensor: adc_sensor update_interval: 3600s - - platform: ct_clamp + - platform: ct_clamp name: "SolarPower1" sensor: solar_1_raw update_interval: 5s unit_of_measurement: "W" device_class: "power" filters: - - lambda: "return x > 0.001 ? x * 56221 : 0;" - - platform: ct_clamp + - lambda: "return x > 0.001 ? x * 56221 : 0;" + - platform: ct_clamp name: "SolarPower2" sensor: solar_2_raw update_interval: 5s unit_of_measurement: "W" device_class: "power" filters: - - lambda: "return x > 0.001 ? x * 57519 : 0;" + - lambda: "return x > 0.001 ? x * 57519 : 0;" See Also -------- diff --git a/components/sensor/images/max9611.jpg b/components/sensor/images/max9611.jpg new file mode 100644 index 000000000..53d2f8833 Binary files /dev/null and b/components/sensor/images/max9611.jpg differ diff --git a/components/sensor/images/mlx90393-full.jpg b/components/sensor/images/mlx90393-full.jpg new file mode 100644 index 000000000..6fcf57ea9 Binary files /dev/null and b/components/sensor/images/mlx90393-full.jpg differ diff --git a/components/sensor/images/radon_eye_rd200.jpg b/components/sensor/images/radon_eye_rd200.jpg new file mode 100644 index 000000000..ef3923323 Binary files /dev/null and b/components/sensor/images/radon_eye_rd200.jpg differ diff --git a/components/sensor/images/xiaomi_mhoc303.jpg b/components/sensor/images/xiaomi_mhoc303.jpg new file mode 100644 index 000000000..ff0db4374 Binary files /dev/null and b/components/sensor/images/xiaomi_mhoc303.jpg differ diff --git a/components/sensor/max9611.rst b/components/sensor/max9611.rst new file mode 100644 index 000000000..4f3b02428 --- /dev/null +++ b/components/sensor/max9611.rst @@ -0,0 +1,78 @@ +MAX9611/9612 High Side Current+Voltage+Temperature Sensor +========================================================= + +.. seo:: + :description: Instructions for setting up MAX9611 MAX9612 High-Side Current-Sense Amplifier + :image: max9611.jpg + :keywords: MAX9611 MAX9612 + +The ``MAX9611`` sensor platform allows you to use your MAX9611/MAX9612 +(`datasheet `__) +High-side current, voltage and temperature sensors with ESPHome. + +This sensor supports up to +60V DC common mode voltage, has a 1.8V to 3.3V logic range, +a 12-Bit integrated ADC with :ref:`I²C `, and is meant to act as a high-side current sense amplifier. + +The :ref:`I²C ` is +required to be set up in your configuration for this sensor to work. + +.. figure:: images/max9611.jpg + :align: center + :width: 50.0% + + MAX9611 High-Side Current-Sense Amplifier + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: max9611 + shunt_resistance: 0.2 ohm + gain: '1X' + voltage: + name: Max9611 Voltage + current: + name: Max9611 Current + power: + name: Max9611 Watts + temperature: + name: Max9611 Temperature + address: 0x70 + update_interval: 60s + +Configuration variables: +------------------------ + +- **shunt_resistance** (*Required*): The value of the High Side Shunt Resistor. + +- **Voltage** (*Optional*): The information for the voltage sensor + + - **name** (**Required**, string): The name for the voltage sensor. + - All other options from :ref:`Sensor `. + +- **Current** (*Optional*): The information for the current sensor, scaled by the gain factor and multiplied by voltage + + - **name** (**Required**, string): The name for the current sensor. + - All other options from :ref:`Sensor `. + +- **Power** (*Optional*): The information for the power sensor + + - **name** (**Required**, string): The name for the power sensor. + - All other options from :ref:`Sensor `. + +- **temperature** (*Optional*): The information for the temperature sensor + + - **name** (**Required**, string): The name for the temperature sensor. + - All other options from :ref:`Sensor `. + + +- **address** (*Optional*, int): Manually specify the I²C address of + the sensor. Defaults to ``0x70``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +See Also +-------- + +- :ref:`sensor-filters` +- :ghedit:`Edit` diff --git a/components/sensor/mlx90393.rst b/components/sensor/mlx90393.rst new file mode 100644 index 000000000..6ffbac5db --- /dev/null +++ b/components/sensor/mlx90393.rst @@ -0,0 +1,115 @@ +MLX90393 Triple-axis Magnetometer +================================= + +.. seo:: + :description: Instructions for setting up MLX90393 Triple-Axis magnetometer sensor. + :image: mlx90393.jpg + :keywords: MLX90393 + +The ``mlx90393`` sensor platform allows you to use your MLX90393 +(`datasheet `__, +`Adafruit`_) three axis magnetometer with ESPHome. The :ref:`I²C ` is required to be set up in +your configuration for this sensor to work. + +.. figure:: images/mlx90393-full.jpg + :align: center + :width: 50.0% + + MLX90393 Triple-axis Magnetometer + +.. _Adafruit: https://www.adafruit.com/product/4022 + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: mlx90393 + id: mlx + x_axis: + name: "x" + y_axis: + name: "y" + z_axis: + name: "z" + +Configuration variables: +------------------------ + +- **x_axis** (*Optional*): The information for the x-axis. + + - **name** (**Required**, string): The name for the x-axis sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - **resolution** (*Optional*, int): Set resolution. Defaults to ``19BIT``. Must be one of: + + - ``16BIT`` + - ``17BIT`` + - ``18BIT`` + - ``19BIT`` + + - All other options from :ref:`Sensor `. + +- **y_axis** (*Optional*): The information for the y-axis. + + - **name** (**Required**, string): The name for the y-axis sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - **resolution** (*Optional*, int): Set resolution. Defaults to ``19BIT``. Must be one of: + + - ``16BIT`` + - ``17BIT`` + - ``18BIT`` + - ``19BIT`` + + - All other options from :ref:`Sensor `. + +- **z_axis** (*Optional*): The information for the z-axis. + + - **name** (**Required**, string): The name for the z-axis sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - **resolution** (*Optional*, int): Set resolution. Defaults to ``16BIT``. Must be one of: + + - ``16BIT`` + - ``17BIT`` + - ``18BIT`` + - ``19BIT`` + + - All other options from :ref:`Sensor `. + +- **temperature** (*Optional*): Built-in temperature sensor. + + - **name** (**Required**, string): The name for the temperature sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - **oversampling** (*Optional*, int): On-chip oversampling for the temperature sensor. Defaults to `0`. Must be between `0` and `3`. + - All other options from :ref:`Sensor `. + +- **drdy_pin** (*Optional*, :ref:`Pin Schema `): Data-ready pin. Often labelled ``INT``. Using this pin might lead to slightly quicker read times. + +- **gain** (*Optional*, int): Specify the gain. Defaults to ``2_5X``. Must be one of + + - ``1X`` + - ``1_33X`` + - ``1_67X`` + - ``2X`` + - ``2_5X`` + - ``3X`` + - ``4X`` + - ``5X`` + +- **oversampling** (*Optional*, int): On-chip oversampling. Defaults to ``2``. Must be between ``0`` and ``3``. + +- **filter** (*Optional*, int): On-chip digital filter. Defaults to ``6``. Must be between ``0`` and ``7``. + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +- **address** (*Optional*, int): Manually specify the I²C address of + the sensor. Defaults to ``0x0C``. + +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you want + to use multiple I²C buses. + +See Also +-------- + +- :ref:`sensor-filters` +- `arduino-MLX90393 `__ +- :ghedit:`Edit` diff --git a/components/sensor/radon_eye_ble.rst b/components/sensor/radon_eye_ble.rst new file mode 100644 index 000000000..f402c387a --- /dev/null +++ b/components/sensor/radon_eye_ble.rst @@ -0,0 +1,102 @@ +Radon Eye BLE Sensors +===================== + +.. seo:: + :description: Instructions for setting up Radon Eye bluetooth-based sensors in ESPHome. + :keywords: Radon, RadonEye, RD200, BLE, Bluetooth, Wave Plus, Wave Mini + +The ``radon_eye_rd200`` sensor platforms lets you track the output of Radon Eye RD200 Bluetooth Low Energy device. + +This component will track radon concentration. + +Device Discovery +----------------- + +RadonEye devices can be found using the ``radon_eye_ble`` ble scanner. + +To find out your device's MAC address, add the following to your ESPHome configuration: + +.. code-block:: yaml + + logger: + level: DEBUG # Required for the tracker to show the device + + esp32_ble_tracker: + radon_eye_ble: + +The device will then listen for nearby devices, and display a message like this one: + +.. code-block:: text + + [D][radon_eye_ble:017]: + Found Radon Eye RD200 device Name: FR:R20:SN1234 (MAC: 01:02:03:04:05:06) + +Once the device is found, remove the ``radon_eye_ble`` device tracker from your configuration and +take note of the device MAC address, and use it when configuring a sensor below. + +Supported Devices +----------------- + +Radon Eye RD200 +*************** + +Radon Eye RD200 tracks radon concentration over short periods (5 min interval) and longer periods +(24h or month). + +The ``radon_long_term`` sensor is populated with the longest available measurement. The RD200 +provides a 24hr measurement and a 1 month measurement. + +If the 1 month isn't available, it will use +the 24hr. If the 24hr isn't available either, it will not publish the value. + +.. figure:: images/radon_eye_rd200.jpg + :align: center + :width: 60.0% + +Configuration example: +********************** + +.. code-block:: yaml + + esp32_ble_tracker: + + ble_client: + - mac_address: 01:02:03:04:05:06 + id: radon_eye_ble_id + + sensor: + - platform: radon_eye_rd200 + ble_client_id: radon_eye_ble_id + update_interval: 5min # default + radon: + name: "Radon" + radon_long_term: + name: "Radon Long Term" + +Here is an example to use pCi/L (to match the value on the device display): + +.. code-block:: yaml + + esp32_ble_tracker: + + ble_client: + - mac_address: 01:02:03:04:05:06 + id: radon_eye_ble_id + + sensor: + - platform: radon_eye_rd200 + ble_client_id: radon_eye_ble_id + update_interval: 5min # default + radon: + name: "Radon" + unit_of_measurement: "pCi/L" + accuracy_decimals: 2 + filters: + - lambda: return x / 37; + radon_long_term: + name: "Radon Long Term" + unit_of_measurement: "pCi/L" + accuracy_decimals: 2 + filters: + - lambda: return x / 37; + diff --git a/components/sensor/tcs34725.rst b/components/sensor/tcs34725.rst index f3bedde2d..251bfc42d 100644 --- a/components/sensor/tcs34725.rst +++ b/components/sensor/tcs34725.rst @@ -49,18 +49,16 @@ required to be set up in your configuration for this sensor to work. Configuration variables: ------------------------ -- **red_channel** (*Optional*): Get the percentage of how strongly the red color channel is activated. +- **red_channel** (*Optional*): Value of the red color channel relative to the clear channel, as a percentage. All options from :ref:`Sensor `. -- **green_channel** (*Optional*): Get the percentage of how strongly the green color channel is activated. +- **green_channel** (*Optional*): Value of the green color channel relative to the clear channel, as a percentage. All options from :ref:`Sensor `. -- **blue_channel** (*Optional*): Get the percentage of how strongly the blue color channel is activated. +- **blue_channel** (*Optional*): Value of the blue color channel relative to the clear channel, as a percentage. All options from :ref:`Sensor `. -- **clear_channel** (*Optional*): Get the percentage of how strongly the clear (without a color filter) - channel is activated. All options from :ref:`Sensor `. +- **clear_channel** (*Optional*): Value of the clear (without a color filter) channel, relative to the maximum value for + the chosen integration time. All options from :ref:`Sensor `. - **illuminance** (*Optional*): Get the total illuminance of the sensor in lx. - All options from :ref:`Sensor `. - **color_temperature** (*Optional*): Get the calculated color temperature of the light in Kelvin. - All options from :ref:`Sensor `. - **gain** (*Optional*): Set the gain for the internal ADCs to work better in certain low-light conditions. Valid values are ``1x`` (default), ``4x``, ``16x``, ``60x`` (highest gain). - **integration_time** (*Optional*): The amount of time the light sensor is exposed. Valid values are @@ -72,6 +70,7 @@ Configuration variables: - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + See Also -------- diff --git a/components/sensor/tsl2591.rst b/components/sensor/tsl2591.rst index f03833604..7c3f24a6a 100644 --- a/components/sensor/tsl2591.rst +++ b/components/sensor/tsl2591.rst @@ -30,6 +30,9 @@ The TSL2591 device is available on breakout boards from a few vendors The sensor claims a dynamic range of 600 million to 1 with an effective maximum of 88000 lux. It achieves that large range by having a configurable ``gain`` value. +For many applications, you can use AUTO gain to have the ESP select a suitable gain setting based on +the previous measurement. If light levels change dramatically this may cause the next reading to saturate, +after which the gain will adjust down and subsequent readings will be in range. Use a higher gain value when measuring less intense light sources. On the other hand, if you get ADC readings of 65,535 for either physical sensor, you may be saturating that sensor and need to reduce the gain. @@ -121,9 +124,10 @@ For the TSL2591 device: You cannot specify an arbitrary gain multiplier. It must be one of: - ``low``, ``1x`` - - ``medium``, ``med``, ``25x`` *(default)* + - ``medium``, ``med``, ``25x`` - ``high``, ``400x`` - ``maximum``, ``max``, ``9500x`` + - ``auto`` *(default)* - **update_interval** (*Optional*, :ref:`config-time`): The interval for checking the sensors. Defaults to ``60s``. diff --git a/components/sensor/xiaomi_ble.rst b/components/sensor/xiaomi_ble.rst index 3cfc5452d..f02a380a1 100644 --- a/components/sensor/xiaomi_ble.rst +++ b/components/sensor/xiaomi_ble.rst @@ -237,6 +237,31 @@ Configuration example for PVVX MiThermometer firmware set to "Custom" advertisem battery_voltage: name: "PVVX Battery-Voltage" +MHO-C303 +******** + +Hygro thermometer clock with alarm, rectangular body, e-ink display, broadcasts temperature, humidity and battery status. Not encrypted. + +.. figure:: images/xiaomi_mhoc303.jpg + :align: center + :width: 30.0% + +Similar to the LYWSD02, with additional clock features (alarm, pomodoro timer). Runs on two AAA batteries. + +Configuration example: + +.. code-block:: yaml + + sensor: + - platform: xiaomi_mhoc303 + mac_address: "E7:50:59:32:A0:1C" + temperature: + name: "MHO-C303 Climate Temperature" + humidity: + name: "MHO-C303 Climate Humidity" + battery_level: + name: "MHO-C303 Climate Battery Level" + MHO-C401 ******** diff --git a/components/switch/index.rst b/components/switch/index.rst index 531c57623..4fe558fa6 100644 --- a/components/switch/index.rst +++ b/components/switch/index.rst @@ -42,6 +42,9 @@ Configuration variables: See https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Requires Home Assistant 2021.11 or newer. Set to ``""`` to remove the default entity category. +- **device_class** (*Optional*, string): The device class for the switch. + See https://developers.home-assistant.io/docs/core/entity/switch/#available-device-classes + for a list of available options. Requires Home Assistant 2022.3 or newer. - If MQTT enabled, All other options from :ref:`MQTT Component `. .. _switch-toggle_action: diff --git a/components/touchscreen/ektf2232.rst b/components/touchscreen/ektf2232.rst new file mode 100644 index 000000000..29aa7237b --- /dev/null +++ b/components/touchscreen/ektf2232.rst @@ -0,0 +1,37 @@ +EKTF2232 Touchscreen Controller +================================ + +.. seo:: + :description: Instructions for setting up EKTF2232 touchscreen controller with ESPHome + :image: ektf2232.svg + :keywords: EKTF2232 + +The ``ektf2232`` component allows using the touchscreen controller +found in the :doc:`Inkplate 6 Plus ` with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. + +.. code-block:: yaml + + # Example configuration entry + touchscreen: + - platform: ektf2232 + interrupt_pin: GPIO36 + rts_pin: GPIO16 + + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **rts_pin** (*Optional*, :ref:`Pin Schema `): The reset pin of the controller. +- **interupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. + +- All other options from :ref:`config-touchscreen`. + +See Also +-------- + +- :doc:`Touchscreen ` +- :doc:`Inkplate 6 Plus ` +- :apiref:`ektf2232/ektf2232.h` +- :ghedit:`Edit` diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst new file mode 100644 index 000000000..4f9781c05 --- /dev/null +++ b/components/touchscreen/index.rst @@ -0,0 +1,90 @@ +Touchscreen Components +====================== + +.. seo:: + :description: Instruction for using touchscreen components. + :image: folder-open.svg + +The ``touchscreen`` component holds the base code for most touchscreen components +available in ESPHome and is responsible for passing the touch events to +``binary_sensors`` with the ``touchscreen`` platform. + +.. _config-touchscreen: + +Base Touchscreen Configuration +------------------------------ + +.. code-block:: yaml + + # Example touchscreen + touchscreen: + - platform: ... + on_touch: + then: + ... + +Configuration variables: +************************ + +- **on_touch** (*Optional*, :ref:`Automation `): An automation to perform + when the touchscreen is touched. See :ref:`touchscreen-on_touch`. +- **display** (**Required**, :ref:`config-id`): The display to use. If only one display is + available, this can be omitted. + +.. _touchscreen-on_touch: + +``on_touch`` Trigger +-------------------- + +This automation will be triggered when the touchscreen detects a touch. + +This trigger provides one arguments of type :apistruct:`touchscreen::TouchPoint` which has two integer members: ``x`` and ``y`` which +represent the position of the touch in relation to the display width and height. It also has optional members that will be set +depending on the touchscreen platform. + +Binary Sensor +------------- + +The ``touchscreen`` binary sensor allows you to setup areas on the touch screen as virtual +buttons. + +.. code-block:: yaml + + binary_sensor: + - platform: touchscreen + name: Top Left Touch Button + x_min: 0 + x_max: 100 + y_min: 0 + y_max: 100 + +Configuration Variables: +************************ + +- **name** (*Optional*, string): The name for the binary sensor. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **touchscreen_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the touchscreen. +- **x_min** (**Required**, int): Left coordinate of the screen area to be detected as the virtual button. +- **x_max** (**Required**, int): Right coordinate of the screen area to be detected as the virtual button. +- **y_min** (**Required**, int): Top coordinate of the screen area to be detected as the virtual button. +- **y_max** (**Required**, int): Bottom coordinate of the screen area to be detected as the virtual button. + +- All other options from :ref:`Binary Sensor `. + + +See Also +-------- + +- :ref:`Binary Sensor Filters ` +- :doc:`Inkplate 6 Plus ` +- :doc:`EKTF2232 ` +- :doc:`XPT2046 ` +- :apiref:`touchscreen/touchscreen.h` +- :apiref:`touchscreen/binary_sensor/touchscreen_binary_sensor.h` +- :ghedit:`Edit` + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/components/touchscreen/lilygo_t5_47.rst b/components/touchscreen/lilygo_t5_47.rst new file mode 100644 index 000000000..4e01bf01a --- /dev/null +++ b/components/touchscreen/lilygo_t5_47.rst @@ -0,0 +1,35 @@ +Lilygo T5 4.7" Touchscreen +========================== + +.. seo:: + :description: Instructions for setting up the Lilygo T5 4.7" Touchscreen with ESPHome + :image: lilygo_t5_47_touch.png + :keywords: Lilygo T5 4.7" Touchscreen + +The ``liygo_t5_47`` touchscreen platform allows using the touchscreen controller +for the Lilygo T5 4.7" e-Paper Display with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration for this touchscreen to work. + +.. code-block:: yaml + + # Example configuration entry + touchscreen: + - platform: lilygo_t5_47 + interrupt_pin: GPIO13 + + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **interupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. + Must be ``GPIO13``. + +- All other options from :ref:`config-touchscreen`. + +See Also +-------- + +- :doc:`Touchscreen ` +- :apiref:`lilygo_t5_47/touchscreen/lilygo_t5_47_touchscreen.h` +- :ghedit:`Edit` diff --git a/components/wifi.rst b/components/wifi.rst index c466e2f3c..35029ba35 100644 --- a/components/wifi.rst +++ b/components/wifi.rst @@ -269,5 +269,6 @@ See Also -------- - :doc:`captive_portal` +- :doc:`network` - :apiref:`wifi/wifi_component.h` - :ghedit:`Edit` diff --git a/conf.py b/conf.py index 087f0799e..9522bc9a4 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ author = "Otto Winter" # built documents. # # The short X.Y version. -version = "2022.1" +version = "2022.2" # The full version, including alpha/beta/rc tags. -release = "2022.1.3" +release = "2022.2.0b1" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/supporters.rst b/guides/supporters.rst index 49bb10a5f..1b9f581c1 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -69,6 +69,7 @@ Contributors - `arantius (@arantius) `__ - `arunderwood (@arunderwood) `__ - `Ash McKenzie (@ashmckenzie) `__ +- `Ashton Kemerling (@AshtonKem) `__ - `Pavel Pletenev (@ASMfreaK) `__ - `Andreas Soehlke (@asoehlke) `__ - `Mike Dunston (@atanisoft) `__ @@ -257,6 +258,7 @@ Contributors - `frippe75 (@frippe75) `__ - `Fritz Mueller (@fritzm) `__ - `Marc Egli (@frog32) `__ +- `functionpointer (@functionpointer) `__ - `mr G1K (@G1K) `__ - `Aljaž Srebrnič (@g5pw) `__ - `Gabe Cook (@gabe565) `__ @@ -324,13 +326,13 @@ Contributors - `Ivo-tje (@Ivo-tje) `__ - `Jan Harkes (@jaharkes) `__ - `Jakob Reiter (@jakommo) `__ -- `James Braid (@jamesbraid) `__ - `James Gao (@jamesgao) `__ - `János Rusiczki (@janosrusiczki) `__ - `Jan Pieper (@janpieper) `__ - `Jason2866 (@Jason2866) `__ - `Jason Hines (@jasonehines) `__ - `Jas Strong (@jasstrong) `__ +- `Jonas Bergler (@jbergler) `__ - `JbLb (@jblb) `__ - `James Callaghan (@jcallaghan) `__ - `Josh Willox (@jcwillox) `__ @@ -338,6 +340,7 @@ Contributors - `JeeCee1 (@JeeCee1) `__ - `jeff-h (@jeff-h) `__ - `Jeffrey Borg (@jeffborg) `__ +- `Jeff Eberl (@jeffeb3) `__ - `Jeff Rescignano (@JeffResc) `__ - `Jej (@jej) `__ - `Jérôme Laban (@jeromelaban) `__ @@ -459,6 +462,7 @@ Contributors - `Matthew Mazzanti (@matthewmazzanti) `__ - `Maurice Schleußinger (@maurice-schleussinger) `__ - `mbo18 (@mbo18) `__ +- `mckaymatthew (@mckaymatthew) `__ - `Me No Dev (@me-no-dev) `__ - `Alexandr Zarubkin (@me21) `__ - `Joseph Mearman (@Mearman) `__ @@ -499,7 +503,6 @@ Contributors - `Murilo (@murilobaliego) `__ - `Michiel van Turnhout (@mvturnho) `__ - `Martin Weinelt (@mweinelt) `__ -- `myhomeiot (@myhomeiot) `__ - `Igor Scheller (@MyIgel) `__ - `Mynasru (@Mynasru) `__ - `Niels Ulrik Andersen (@myplacedk) `__ @@ -785,7 +788,6 @@ Contributors - `Zebble (@Zebble) `__ - `ZJY (@zhangjingye03) `__ - `San (@zhujunsan) `__ -- `ZTX18 (@ZTX18) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated February 2, 2022.* +*This page was last updated February 10, 2022.* diff --git a/images/ektf2232.svg b/images/ektf2232.svg new file mode 100644 index 000000000..3058355dc --- /dev/null +++ b/images/ektf2232.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/lilygo_t5_47_touch.png b/images/lilygo_t5_47_touch.png new file mode 100644 index 000000000..a9ce05038 Binary files /dev/null and b/images/lilygo_t5_47_touch.png differ diff --git a/images/max9611.jpg b/images/max9611.jpg new file mode 100644 index 000000000..f82413301 Binary files /dev/null and b/images/max9611.jpg differ diff --git a/images/mlx90393.jpg b/images/mlx90393.jpg new file mode 100644 index 000000000..f40cd5562 Binary files /dev/null and b/images/mlx90393.jpg differ diff --git a/images/qr-code.svg b/images/qr-code.svg new file mode 100644 index 000000000..1dfbae3cd --- /dev/null +++ b/images/qr-code.svg @@ -0,0 +1,500 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/images/radon_eye_logo.png b/images/radon_eye_logo.png new file mode 100644 index 000000000..ac8c900ea Binary files /dev/null and b/images/radon_eye_logo.png differ diff --git a/index.rst b/index.rst index 9c2cc688f..d16eeef0b 100644 --- a/index.rst +++ b/index.rst @@ -142,6 +142,7 @@ Core Components Core, components/esphome, cloud-circle.svg WiFi, components/wifi, network-wifi.svg MQTT, components/mqtt, mqtt.png + Network, components/network, network-wifi.svg I²C Bus, components/i2c, i2c.svg SPI Bus, components/spi, spi.svg @@ -187,6 +188,7 @@ Air Quality PM1006 Sensor, components/sensor/pm1006, pm1006.jpg, Particulate PMSA003I, components/sensor/pmsa003i, pmsa003i.jpg, Particulate PMSX003, components/sensor/pmsx003, pmsx003.svg, Particulate + RadonEye BLE, components/sensor/radon_eye_ble, radon_eye_logo.png, Radon SDS011 Sensor, components/sensor/sds011, sds011.jpg, Particulate SenseAir, components/sensor/senseair, senseair_s8.jpg, CO2 SCD30, components/sensor/scd30, scd30.jpg, CO2 & Temperature & Humidity @@ -261,6 +263,7 @@ Electricity INA226, components/sensor/ina226, ina226.jpg, DC Current & Power INA260, components/sensor/ina260, ina260.jpg, DC Current & Power INA3221, components/sensor/ina3221, ina3221.jpg, 3-Ch DC current + MAX9611, components/sensor/max9611, max9611.jpg, +60VDC Voltage & Current & Power & Temperature PZEM AC, components/sensor/pzemac, pzem-ac.jpg, Voltage & Current & Power PZEM DC, components/sensor/pzemdc, pzem-dc.jpg, Voltage & Current & Power PZEM004T, components/sensor/pzem004t, pzem004t.svg, Voltage & Current & Power @@ -295,6 +298,7 @@ Environmental MH-Z19, components/sensor/mhz19, mhz19.jpg, CO2 & Temperature MS5611, components/sensor/ms5611, ms5611.jpg, Pressure NTC Thermistor, components/sensor/ntc, ntc.jpg, Temperature + RadonEye BLE, components/sensor/radon_eye_ble, radon_eye_logo.png, Radon RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg, Temperature & Humidity & Accelerometer SCD30, components/sensor/scd30, scd30.jpg, CO2 & Temperature & Humidity SCD4X, components/sensor/scd4x, scd4x.jpg, CO2 & Temperature & Humidity @@ -326,6 +330,7 @@ Magnetic ESP32 Hall Sensor, components/sensor/esp32_hall, magnet.svg, ESP internal HMC5883L, components/sensor/hmc5883l, hmc5883l.jpg, 3-Axis magnetometer + MLX90393, components/sensor/mlx90393, mlx90393.jpg, 3-Axis magnetometer QMC5883L, components/sensor/qmc5883l, qmc5883l.jpg, 3-Axis magnetometer @@ -401,6 +406,7 @@ Binary Sensor Components Modbus Binary Sensor, components/binary_sensor/modbus_controller, modbus.png XPT2046, components/binary_sensor/xpt2046, xpt2046.jpg CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg + Touchscreen, components/touchscreen/index, touch.svg Custom Binary Sensor, components/binary_sensor/custom, language-cpp.svg Output Components @@ -483,7 +489,9 @@ Button Components Button Core, components/button/index, folder-open.svg Template Button, components/button/template, description.svg + Generic Output Button, components/button/output, upload.svg Restart Button, components/button/restart, restart.svg + Wake-on-LAN, components/button/wake_on_lan, power_settings.svg Fan Components -------------- @@ -522,6 +530,15 @@ Display Components Inkplate, components/display/inkplate6, inkplate6.jpg PCD8544 (Nokia 5110/ 3310), components/display/pcd8544, pcd8544.jpg +Touchscreen Components +---------------------- + +.. imgtable:: + + Touchscreen Core, components/touchscreen/index, folder-open.svg + EKTF2232, components/touchscreen/ektf2232, ektf2232.svg, Inkplate 6 Plus + Lilygo T5 4.7", components/touchscreen/lilygo_t5_47, lilygo_t5_47_touch.png + Cover Components ---------------- @@ -585,6 +602,16 @@ Select Components Select Core, components/select/index, folder-open.svg Template Select, components/select/template, description.svg + Modbus Select, components/select/modbus_controller, modbus.png + +Lock Components +----------------- + +.. imgtable:: + + Lock Core, components/lock/index, folder-open.svg + Generic Output Lock, components/lock/output, upload.svg + Template Lock, components/lock/template, description.svg Misc Components ---------------