mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-26 17:27:47 +01:00
OTA docs update for esphome/esphome#6459 (#3782)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
Keith Burzinski
GitHub
parent
3ce46e7405
commit
a30541482e
@ -1,89 +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</components/button/safe_mode>` or :doc:`switch</components/switch/safe_mode>` 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
|
||||
- ``8892`` for Beken chips
|
||||
- **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<automation>`): An action to be
|
||||
performed when an OTA update is started. See :ref:`ota-on_begin`.
|
||||
- **on_progress** (*Optional*, :ref:`Automation<automation>`): An action to be
|
||||
performed (multiple times) during an OTA update. See :ref:`ota-on_progress`.
|
||||
- **on_end** (*Optional*, :ref:`Automation<automation>`): An action to be
|
||||
performed after a successful OTA update. See :ref:`ota-on_end`.
|
||||
- **on_error** (*Optional*, :ref:`Automation<automation>`): An action to be
|
||||
performed after a failed OTA update. See :ref:`ota-on_error`.
|
||||
- **on_state_change** (*Optional*, :ref:`Automation<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<automation>`): An action to be performed when an OTA update is started.
|
||||
See :ref:`ota-on_begin`.
|
||||
- **on_progress** (*Optional*, :ref:`Automation<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<automation>`): An action to be performed after a successful OTA update.
|
||||
See :ref:`ota-on_end`.
|
||||
- **on_error** (*Optional*, :ref:`Automation<automation>`): An action to be performed after a failed OTA update.
|
||||
See :ref:`ota-on_error`.
|
||||
- **on_state_change** (*Optional*, :ref:`Automation<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:
|
||||
|
||||
@ -104,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
|
||||
|
||||
@ -122,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
|
||||
|
||||
@ -142,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
|
||||
|
||||
@ -162,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``
|
||||
|
||||
@ -182,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 <file> 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 <file>`` command
|
||||
won't work. This issue can be worked around by executing the operations separately with an ``on_boot`` trigger:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -198,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
|
||||
--------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user