diff --git a/Doxygen b/Doxygen index 45420066e..8bc2c31dd 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.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 7ae0cf4bb..709a09d40 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2022.10.2 +ESPHOME_REF = 2022.11.0b1 .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/version b/_static/version index 8fd513888..121de79cf 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2022.10.2 \ No newline at end of file +2022.11.0b1 \ 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=[["","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'+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` 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: + + * diff --git a/components/display_menu/lcd_menu.rst b/components/display_menu/lcd_menu.rst new file mode 100644 index 000000000..af00f765d --- /dev/null +++ b/components/display_menu/lcd_menu.rst @@ -0,0 +1,107 @@ +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 the character based LCD displays. + + +.. figure:: images/lcd_menu.png + :align: center + :width: 50.0% + +.. _lcd_menu: + +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 +at the moment are :ref:`lcd-pcf8574` or a :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 ``i2c`` configuration. + +.. code-block:: yaml + + # Example configuration entry + display: + - platform: lcd_pcf8574 + id: my_lcd + dimensions: 20x4 + ... + user_characters: + - position: 0 + data: + - 0b00100 + - 0b01110 + - 0b10101 + - 0b00100 + - 0b00100 + - 0b00100 + - 0b11100 + - 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: + ... + + # 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: + +- **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 + up arrow, using a user defined character is advisable (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 whole area. + +See Also +-------- + +- :apiref:`lcd_menu/lcd_menu.h` 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/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/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/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/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/conf.py b/conf.py index f608e9923..897e1b72e 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.0b1" # 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..ab29c41f5 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -175,6 +175,7 @@ Contributors - `Dmitry Berezovsky (@corvis) `__ - `Cougar (@Cougar) `__ - `Connor Prussin (@cprussin) `__ +- `Corey Rice (@crice009) `__ - `cryptelli (@cryptelli) `__ - `cstaahl (@cstaahl) `__ - `Chris Talkington (@ctalkington) `__ @@ -499,6 +500,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) `__ @@ -652,12 +654,10 @@ Contributors - `Ockert Marais (@OckertM) `__ - `Dave Walker (@oddsockmachine) `__ - `Andrey Ganzevich (@odya) `__ -- `Olivér Falvai (@ofalvai) `__ - `ogatatsu (@ogatatsu) `__ - `Oğuzhan Başer (@oguzhanbaser) `__ - `Omar Ghader (@omarghader) `__ - `Ömer Şiar Baysal (@omersiar) `__ -- `Oncleben31 (@oncleben31) `__ - `Oscar Bolmsten (@oscar-b) `__ - `Trammell Hudson (@osresearch) `__ - `Otamay (@Otamay) `__ @@ -740,6 +740,7 @@ Contributors - `Silvio (@s1lvi0) `__ - `Jan Čermák (@sairon) `__ - `sascha lammers (@sascha432) `__ +- `Søren Christian Aarup (@scaarup) `__ - `Nils Schulte (@Schnilz) `__ - `Wolle (@schreibfaul1) `__ - `Ville Skyttä (@scop) `__ @@ -896,4 +897,4 @@ Contributors - `Zack Barett (@zsarnett) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated November 1, 2022.* +*This page was last updated November 9, 2022.* diff --git a/images/adc128s102.png b/images/adc128s102.png new file mode 100644 index 000000000..7e5764892 Binary files /dev/null and b/images/adc128s102.png differ diff --git a/images/ezo-pmp.jpg b/images/ezo-pmp.jpg new file mode 100644 index 000000000..de1f85ea0 Binary files /dev/null and b/images/ezo-pmp.jpg differ diff --git a/images/lcd_menu.png b/images/lcd_menu.png new file mode 100644 index 000000000..979951e43 Binary files /dev/null and b/images/lcd_menu.png differ diff --git a/images/rp2040.svg b/images/rp2040.svg new file mode 100644 index 000000000..36e48a00d --- /dev/null +++ b/images/rp2040.svg @@ -0,0 +1,62 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + diff --git a/index.rst b/index.rst index e60884275..6a96a731a 100644 --- a/index.rst +++ b/index.rst @@ -113,26 +113,14 @@ ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configu .. _devices: -Devices -------- - -This list contains a bunch of getting started and more advanced guides for using ESPHome. -Technically, all ESP8266/ESP32 devices are supported by ESPHome. +Platforms +--------- .. imgtable:: - Generic ESP8266, devices/esp8266, esp8266.svg - Generic ESP32, devices/esp32, esp32.svg - NodeMCU ESP8266, devices/nodemcu_esp8266, nodemcu_esp8266.jpg - - NodeMCU ESP32, devices/nodemcu_esp32, nodemcu_esp32.jpg - Sonoff S20, devices/sonoff_s20, sonoff_s20.jpg - Sonoff 4CH, devices/sonoff_4ch, sonoff_4ch.jpg - - Generic Sonoff, devices/sonoff, sonoff.svg - Sonoff Basic, devices/sonoff_basic, sonoff_basic.jpg - Sonoff T1 UK 3 Gang V1.1, devices/sonoff_t1_uk_3gang_v1.1, sonoff_t1_uk_3g_v1.1.jpg - Sonoff T3 EU 3 Gang V1.0, devices/sonoff_t3_eu_3gang_v1.0, sonoff_t3_eu_3g_v1.0.jpg + ESP8266, components/esp8266, esp8266.svg + ESP32, components/esp32, esp32.svg + RP2040, components/rp2040, rp2040.svg Core Components --------------- @@ -207,6 +195,7 @@ Analogue .. imgtable:: ADC, components/sensor/adc, flash.svg, ESP internal + ADC128S102, components/sensor/adc128s102, adc128s102.png , 8-channel ADC ADS1115, components/sensor/ads1115, ads1115.jpg, 4-channel ADC CD74HC4067, components/sensor/cd74hc4067, cd74hc4067.jpg, 16-channel analog multiplexer MCP3008, components/sensor/mcp3008, mcp3008.jpg, 8-channel ADC @@ -594,12 +583,14 @@ Text Sensor Components MQTT Subscribe Text, components/text_sensor/mqtt_subscribe, mqtt.png Version, components/text_sensor/version, new-box.svg WiFi Info, components/text_sensor/wifi_info, network-wifi.svg + Ethernet Info, components/text_sensor/ethernet_info, ethernet.svg BLE Scanner, components/text_sensor/ble_scanner, bluetooth.svg Modbus Text Sensor, components/text_sensor/modbus_controller, modbus.png Template Text Sensor, components/text_sensor/template, description.svg Custom Text Sensor, components/text_sensor/custom, language-cpp.svg Nextion Text Sensor, components/text_sensor/nextion, nextion.jpg Tuya Text Sensor, components/text_sensor/tuya, tuya.png + WL-134 Pet Tag Sensor , components/text_sensor/wl_134, fingerprint.svg Climate Components ------------------ @@ -659,12 +650,11 @@ Misc Components .. imgtable:: - ESP8266, components/esp8266, esp8266.svg - ESP32, components/esp32, esp32.svg - Remote Receiver, components/remote_receiver, remote.svg Remote Transmitter, components/remote_transmitter, remote.svg Status LED, components/status_led, led-on.svg + Display Menu Core, components/display_menu/index, folder-open.svg + LCD Menu, components/display_menu/lcd_menu, lcd_menu.png HTTP Request, components/http_request, connection.svg mDNS, components/mdns, radio-tower.svg