From d184a6a39fb704f7d420f4d1e3ec01d97c01ad8c Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Mon, 22 Apr 2024 20:56:18 +0000 Subject: [PATCH 1/2] OTA docs update for esphome/esphome#6459 --- components/ota.rst | 162 +++++++++++++++++++++------------------------ 1 file changed, 76 insertions(+), 86 deletions(-) diff --git a/components/ota.rst b/components/ota.rst index e36c53063..cfd37d068 100644 --- a/components/ota.rst +++ b/components/ota.rst @@ -1,88 +1,79 @@ -OTA Update Component -==================== +ESPHome OTA Updates +=================== .. seo:: - :description: Instructions for setting up Over-The-Air (OTA) updates for ESPs to upload firmwares remotely. + :description: Instructions for setting up ESPHome's Over-The-Air (OTA) platform to allow remote updating of devices. :image: system-update.svg .. _config-ota: -With the OTA (Over The Air) update component you can upload your -firmware binaries to your node without having to use a USB cable for -uploads. ESPHome natively supports this through its ``run`` and -``upload`` helper scripts. +ESPHome's Over-The-Air (OTA) platform allows you to remotely install modified/updated firmware binaries onto your +ESPHome devices over their network (Wi-Fi or Ethernet) interface. -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 -switch to do that or by pressing the reset button on the board for ``num_attempts`` times. +This platform is used by both the ESPHome dashboard as well as the command line interface (CLI) (via +``esphome run ...``) to install firmware onto supported devices. +In addition to updates, ESPHome also supports a "safe mode" to help recover from boot failures/reboot loops. After a +specified number (the default is ten) of boot failures, the safe mode may be invoked; in this mode, all components are +disabled except serial logging, network (Wi-Fi or Ethernet) and the OTA component, allowing you to attempt to upload a +new binary. You can also force the invocation of safe mode by configuring a dedicated +:doc:`button` or :doc:`switch` component and/or by pressing +the reset button on the board for ``num_attempts`` times (see below). .. code-block:: yaml # Example configuration entry ota: - safe_mode: true - password: !secret ota_password + - platform: esphome + safe_mode: true + password: !secret ota_password Configuration variables: ------------------------ -- **safe_mode** (*Optional*, boolean): Whether to enable safe mode. - Defaults to ``true``. +- **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: +- **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``. -- **num_attempts** (*Optional*, int): The number of attempts to wait before entering safe mode. Defaults to ``10``. -- **on_begin** (*Optional*, :ref:`Automation`): An action to be - performed when an OTA update is started. See :ref:`ota-on_begin`. -- **on_progress** (*Optional*, :ref:`Automation`): An action to be - performed (multiple times) during an OTA update. See :ref:`ota-on_progress`. -- **on_end** (*Optional*, :ref:`Automation`): An action to be - performed after a successful OTA update. See :ref:`ota-on_end`. -- **on_error** (*Optional*, :ref:`Automation`): An action to be - performed after a failed OTA update. See :ref:`ota-on_error`. -- **on_state_change** (*Optional*, :ref:`Automation`): An action to be - performed when an OTA update state change happens. See :ref:`ota-on_state_change`. -- **version** (*Optional*, int): Version of OTA protocol to use. Version 2 is more stable. - To downgrade to legacy ESPHome, the device should be updated with OTA version 1 first. - Defaults to ``2``. +- **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when in safe mode. + Defaults to ``5min``. +- **num_attempts** (*Optional*, int): The number of failed boot attempts which must occur before invoking safe mode. + Defaults to ``10``. +- **on_begin** (*Optional*, :ref:`Automation`): An action to be performed when an OTA update is started. + See :ref:`ota-on_begin`. +- **on_progress** (*Optional*, :ref:`Automation`): An action to be performed (approximately each second) + while an OTA update is in progress. See :ref:`ota-on_progress`. +- **on_end** (*Optional*, :ref:`Automation`): An action to be performed after a successful OTA update. + See :ref:`ota-on_end`. +- **on_error** (*Optional*, :ref:`Automation`): An action to be performed after a failed OTA update. + See :ref:`ota-on_error`. +- **on_state_change** (*Optional*, :ref:`Automation`): An action to be performed when an OTA update state + change happens. See :ref:`ota-on_state_change`. +- **version** (*Optional*, int): Version of OTA protocol to use. Version 2 is more stable. To downgrade to legacy + ESPHome, the device should be updated with OTA version 1 first. Defaults to ``2``. .. note:: - Please be aware that ESP8266 modules must be reset after a serial - upload before OTA can work. - When you are trying to conduct an OTA update and receive an error message - ``Bad Answer: ERR: ERROR[11]: Invalid bootstrapping`` the reason is - very likely that power-cycling the ESP module is required once after - the serial upload. + After a serial upload, ESP8266 modules must be reset before OTA updates will work. If you attempt to perform an OTA + update and receive the error message ``Bad Answer: ERR: ERROR[11]: Invalid bootstrapping``, the ESP module/board + must be power-cycled. -OTA Automation --------------- +OTA Automations +--------------- -The OTA component provides various automations that can be used to provide feedback -during an OTA update. There are a few things to consider when making use of the -provided automation triggers: +The OTA component provides various automations that can be used to provide feedback during the OTA update process. +When using these automation triggers, note that: -- An OTA update blocks the main loop during its operation. This means that you - won't be able to represent state changes using components that update their - output only from within their ``loop()`` method. Explained differently: if you - try to display the OTA progress using component X, but the update only appears - after the OTA update finished, then component X cannot be used for providing - OTA update feedback. - -- Make sure that your automation actions do not take too much time, to prevent - them from blocking the OTA update code for too long. +- OTA updates block the main application loop while in progress. You won't be able to represent state changes using + components that update their output only from within their ``loop()`` method. Explained differently: if you try to + display the OTA progress using component X, but the update only appears after the OTA update finished, then component + X cannot be used for providing OTA update feedback. +- Your automation action(s) must not consume any significant amount of time; if they do, OTA updates may fail. .. _ota-on_begin: @@ -103,9 +94,8 @@ This automation will be triggered when an OTA update is started. ``on_progress`` *************** -Using this automation, it is possible to report on the OTA update progress. -It will be triggered multiple times during the OTA update. You can get the actual -progress percentage (a value between 0 and 100) from the trigger with variable ``x``. +Using this automation, it is possible to report on the OTA update progress. It will be triggered repeatedly during the +OTA update. You can get the actual progress percentage (a value between 0 and 100) from the trigger with variable ``x``. .. code-block:: yaml @@ -121,13 +111,12 @@ progress percentage (a value between 0 and 100) from the trigger with variable ` ``on_end`` ********** -This automation will be triggered when an OTA update has completed successfully, -right before the device is rebooted. +This automation will be triggered when an OTA update has completed successfully, immediately before the device is +rebooted. -Because the update has completed, you can safely use an automation action that -takes some time to complete. This can for example be useful if you want to flash -a LED or so, in which case a pause would be required to make the LED light up -for long enough, before the reboot turns it off. +Because the update has completed, you can safely use (an) automation action(s) that takes some time to complete. If, +for example, you want to flash an LED, multiple a pauses/delays would be required to make the LED blink a few times, +before the reboot. The OTA update can't fail at this point because it is already complete. .. code-block:: yaml @@ -141,11 +130,10 @@ for long enough, before the reboot turns it off. ``on_error`` ************ -This automation will be triggered when an OTA update has failed. You can get -the internal error code with variable ``x``. +This automation will be triggered when an OTA update has failed. You can get the internal error code with variable ``x``. -Just like for :ref:`ota-on_end`, you can safely use an automation that -takes some time to complete, because the OTA update is no longer busy. +Just like for :ref:`ota-on_end`, you can safely use an automation that takes some time to complete as the OTA update +process has already finished. .. code-block:: yaml @@ -161,12 +149,11 @@ takes some time to complete, because the OTA update is no longer busy. ``on_state_change`` ******************* -This automation will be triggered on every state change. You can get the actual -state with variable ``state``, which will contain one of values for the OTAState -enum. These values are: +This automation will be triggered on every state change. You can get the actual state with variable ``state``, which +will contain one of values for the ``OTAState`` enum. These values are: - ``ota::OTA_STARTED`` -- ``ota::OTA_IN_PROGRESS`` (will be called multiple times during the update) +- ``ota::OTA_IN_PROGRESS`` *(will be called repeatedly during the update)* - ``ota::OTA_COMPLETED`` - ``ota::OTA_ERROR`` @@ -181,15 +168,14 @@ enum. These values are: then: - logger.log: "OTA start" -Updating the password: ----------------------- +Updating the Password +--------------------- -Changing an existing password: -****************************** +Changing an Existing Password +***************************** -Since the password is used both for compiling and uploading the regular ``esphome run`` -won't work of course. This issue can be worked around by executing the operations separately -through an ``on_boot`` trigger: +Since the configured password is used for both compiling and uploading, the regular ``esphome run `` command +won't work. This issue can be worked around by executing the operations separately with an ``on_boot`` trigger: .. code-block:: yaml @@ -197,15 +183,19 @@ through an ``on_boot`` trigger: on_boot: - lambda: |- id(my_ota).set_auth_password("New password"); + ota: - password: "Old password" - id: my_ota + - platform: esphome + id: my_ota + password: "Old password" -Adding a password: -****************** +After this trick has been used to change the password, the ``on_boot`` trigger may be removed and the old password +replaced with the new password in the ``ota:`` section. -If OTA is already enabled without a password, simply add a ``password:`` line to the existing -``ota:`` config block. +Adding a Password +***************** + +If OTA is already enabled without a password, simply add a ``password:`` line to the existing ``ota:`` config block. See Also -------- From 58f283f6ae8db1aef37f7772a0803f0ed4c3b5b5 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Sun, 28 Apr 2024 22:00:14 -0500 Subject: [PATCH 2/2] Typo --- components/ota.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/ota.rst b/components/ota.rst index cfd37d068..5707e1093 100644 --- a/components/ota.rst +++ b/components/ota.rst @@ -115,7 +115,7 @@ This automation will be triggered when an OTA update has completed successfully, rebooted. Because the update has completed, you can safely use (an) automation action(s) that takes some time to complete. If, -for example, you want to flash an LED, multiple a pauses/delays would be required to make the LED blink a few times, +for example, you want to flash an LED, multiple pauses/delays would be required to make the LED blink a few times, before the reboot. The OTA update can't fail at this point because it is already complete. .. code-block:: yaml