mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-09-27 04:13:07 +02:00
96 lines
3.4 KiB
ReStructuredText
96 lines
3.4 KiB
ReStructuredText
ESPHome OTA Updates
|
|
===================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up ESPHome's Over-The-Air (OTA) platform to allow remote updating of devices.
|
|
:image: system-update.svg
|
|
|
|
.. _config-ota_esphome:
|
|
|
|
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.
|
|
|
|
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 OTA updates, ESPHome also supports a "safe mode" to help with recovery if/when updates don't work as
|
|
expected. This is automatically enabled by this component, but it may be disabled if desired. See
|
|
:doc:`/components/safe_mode` for details.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
ota:
|
|
- platform: esphome
|
|
password: !secret ota_password
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **password** (*Optional*, string): The password to use for updates.
|
|
- **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.
|
|
- **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``.
|
|
- All :ref:`automations <automation>` supported by :doc:`/components/ota/index`.
|
|
|
|
.. note::
|
|
|
|
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.
|
|
|
|
Updating the Password
|
|
---------------------
|
|
|
|
Changing an Existing Password
|
|
*****************************
|
|
|
|
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
|
|
|
|
esphome:
|
|
on_boot:
|
|
- lambda: |-
|
|
id(my_ota).set_auth_password("New password");
|
|
|
|
ota:
|
|
- platform: esphome
|
|
id: my_ota
|
|
password: "Old password"
|
|
|
|
The "id: my_ota" in the OTA block is important. This is referenced in the lambda.
|
|
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.
|
|
|
|
Adding a Password
|
|
*****************
|
|
|
|
If OTA is already enabled without a password, simply add a ``password:`` line to the existing ``ota:`` config block.
|
|
|
|
Removing a Password
|
|
*******************
|
|
|
|
- If you know your password but want to remove it, enter an empty string: ``id(my_ota).set_auth_password("");`` instead of changing.
|
|
- If you no longer know your password and the web server has been activated:
|
|
|
|
- Remove the OTA password from the configuration
|
|
- Build a new image locally.
|
|
- Execute the OTA update directly via the ESP web server.
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :apiref:`ota/ota_component.h`
|
|
- :doc:`/components/ota/index`
|
|
- :doc:`/components/ota/http_request`
|
|
- :doc:`/components/safe_mode`
|
|
- :ghedit:`Edit`
|