2024-05-22 03:08:59 +02:00
|
|
|
Safe Mode
|
|
|
|
|
=========
|
|
|
|
|
|
|
|
|
|
.. seo::
|
|
|
|
|
:description: Instructions for setting up ESPHome's Safe Mode to help recover from repeated boot failures.
|
|
|
|
|
:image: system-update.svg
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
2024-05-22 21:43:18 +02:00
|
|
|
.. _safe_mode-configuration_variables:
|
2024-05-22 03:08:59 +02:00
|
|
|
|
|
|
|
|
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``.
|
2024-05-22 21:43:18 +02:00
|
|
|
- **on_safe_mode** (*Optional*, :ref:`Automation <automation>`): An action to be performed once when safe mode is invoked.
|
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
The ``on_safe_mode`` :ref:`automation <automation>` is intended for use by recovery actions **only**.
|
|
|
|
|
|
|
|
|
|
As mentioned above, in safe mode, all components are disabled except serial logging, network (Wi-Fi or Ethernet)
|
|
|
|
|
and OTA component(s).
|
|
|
|
|
|
|
|
|
|
**All other components (for example, displays and sensors) are disabled and cannot be used.**
|
2024-05-22 03:08:59 +02:00
|
|
|
|
|
|
|
|
See Also
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
- :apiref:`safe_mode/safe_mode.h`
|
|
|
|
|
- :doc:`/components/button/safe_mode`
|
|
|
|
|
- :doc:`/components/switch/safe_mode`
|
|
|
|
|
- :ghedit:`Edit`
|
