diff --git a/components/ota.rst b/components/ota.rst index e36c53063..5707e1093 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 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 --------