mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-26 22:21:38 +01:00
Safe mode documentation and updates (#3841)
This commit is contained in:
Keith Burzinski
GitHub
parent
c8559c0251
commit
bcb6b5a844
@ -5,10 +5,10 @@ Safe Mode Button
|
||||
:description: Instructions for setting up buttons that can remotely reboot the ESP in ESPHome into safe mode.
|
||||
:image: restart.svg
|
||||
|
||||
The ``safe_mode`` button allows you to remotely reboot your node into :ref:`Safe Mode <config-ota>`. This is useful in certain situations
|
||||
The ``safe_mode`` button allows you to remotely reboot your node into :doc:`/components/safe_mode`. This is useful in certain situations
|
||||
where a misbehaving component is preventing Over-The-Air updates from completing successfully.
|
||||
|
||||
This component requires :ref:`OTA <config-ota>` to be configured.
|
||||
This component requires :doc:`/components/safe_mode` to be configured.
|
||||
|
||||
.. figure:: images/safemode-ui.png
|
||||
:align: center
|
||||
|
||||
@ -13,12 +13,9 @@ 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 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).
|
||||
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
|
||||
|
||||
@ -31,7 +28,6 @@ the reset button on the board for ``num_attempts`` times (see below).
|
||||
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:
|
||||
|
||||
@ -40,10 +36,6 @@ Configuration variables:
|
||||
- ``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 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)
|
||||
|
||||
42
components/safe_mode.rst
Normal file
42
components/safe_mode.rst
Normal file
@ -0,0 +1,42 @@
|
||||
Safe Mode
|
||||
=========
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up ESPHome's Safe Mode to help recover from repeated boot failures.
|
||||
:image: system-update.svg
|
||||
|
||||
.. _config-safe_mode:
|
||||
|
||||
Sometimes hardware and/or software doesn't behave as expected. ESPHome supports a "safe mode" to help recover from
|
||||
repeated 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(s). In most cases, this will temporarily mitigate the issue, allowing you a chance to correct it, perhaps by
|
||||
uploading 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 repeatedly pressing the reset button on the board
|
||||
for ``num_attempts`` times (see below).
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
safe_mode:
|
||||
|
||||
|
||||
Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **disabled** (*Optional*, boolean): Set to ``true`` to disable safe_mode. :doc:`/components/ota` automatically sets
|
||||
up safe mode; this allows disabling it if/when it is not wanted.
|
||||
- **num_attempts** (*Optional*, int): The number of failed boot attempts which must occur before invoking safe mode.
|
||||
Defaults to ``10``.
|
||||
- **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when in safe mode.
|
||||
Defaults to ``5min``.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :apiref:`safe_mode/safe_mode.h`
|
||||
- :doc:`/components/button/safe_mode`
|
||||
- :doc:`/components/switch/safe_mode`
|
||||
- :ghedit:`Edit`
|
||||
@ -5,9 +5,9 @@ Safe Mode Switch
|
||||
:description: Instructions for setting up switches that can remotely reboot the ESP in ESPHome into safe mode.
|
||||
:image: restart.svg
|
||||
|
||||
The ``safe_mode`` switch allows you to remotely reboot your node into :ref:`Safe Mode <config-ota>`. This is useful in certain situations where a misbehaving component, or low memory state is preventing Over-The-Air updates from completing successfully.
|
||||
The ``safe_mode`` switch allows you to remotely reboot your node into :doc:`/components/safe_mode`. This is useful in certain situations where a misbehaving component, or low memory state is preventing Over-The-Air updates from completing successfully.
|
||||
|
||||
This component requires :ref:`OTA <config-ota>` to be configured.
|
||||
This component requires :doc:`/components/safe_mode` to be configured.
|
||||
|
||||
.. figure:: images/safemode-ui.png
|
||||
:align: center
|
||||
|
||||
@ -197,6 +197,7 @@ Management and Monitoring
|
||||
Logger, components/logger, file-document-box.svg, dark-invert
|
||||
OTA Updates, components/ota, system-update.svg, dark-invert
|
||||
Prometheus, components/prometheus, prometheus.svg
|
||||
Safe Mode, components/safe_mode, restart-alert.svg
|
||||
Web Server, components/web_server, http.svg, dark-invert
|
||||
ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user