esphome-docs/components/safe_mode.rst
2024-06-21 18:36:52 +12:00

54 lines
2.3 KiB
ReStructuredText

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:
.. _safe_mode-configuration_variables:
Configuration variables:
------------------------
- **disabled** (*Optional*, boolean): Set to ``true`` to disable safe_mode. :doc:`/components/ota/index` automatically
sets up safe mode; this allows disabling it if/when it is not wanted.
- **boot_is_good_after** (*Optional*, :ref:`config-time`): The amount of time after which the boot is considered successful.
Defaults to ``1min``.
- **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``.
- **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.**
See Also
--------
- :apiref:`safe_mode/safe_mode.h`
- :doc:`/components/button/safe_mode`
- :doc:`/components/switch/safe_mode`
- :ghedit:`Edit`