From bcb6b5a844d443742c88a890d391432b94b53d99 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Tue, 21 May 2024 20:08:59 -0500 Subject: [PATCH] Safe mode documentation and updates (#3841) --- components/button/safe_mode.rst | 4 ++-- components/ota.rst | 14 +++-------- components/safe_mode.rst | 42 +++++++++++++++++++++++++++++++++ components/switch/safe_mode.rst | 4 ++-- index.rst | 1 + 5 files changed, 50 insertions(+), 15 deletions(-) create mode 100644 components/safe_mode.rst diff --git a/components/button/safe_mode.rst b/components/button/safe_mode.rst index ccf41371f..45fe8534a 100644 --- a/components/button/safe_mode.rst +++ b/components/button/safe_mode.rst @@ -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 `. 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 ` to be configured. +This component requires :doc:`/components/safe_mode` to be configured. .. figure:: images/safemode-ui.png :align: center diff --git a/components/ota.rst b/components/ota.rst index 446a6d1f9..effa25c6e 100644 --- a/components/ota.rst +++ b/components/ota.rst @@ -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` or :doc:`switch` 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`): An action to be performed when an OTA update is started. See :ref:`ota-on_begin`. - **on_progress** (*Optional*, :ref:`Automation`): An action to be performed (approximately each second) diff --git a/components/safe_mode.rst b/components/safe_mode.rst new file mode 100644 index 000000000..8abfb62b5 --- /dev/null +++ b/components/safe_mode.rst @@ -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` +or :doc:`switch` 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` diff --git a/components/switch/safe_mode.rst b/components/switch/safe_mode.rst index 24c4e6a5d..9274eeb0e 100644 --- a/components/switch/safe_mode.rst +++ b/components/switch/safe_mode.rst @@ -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 `. 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 ` to be configured. +This component requires :doc:`/components/safe_mode` to be configured. .. figure:: images/safemode-ui.png :align: center diff --git a/index.rst b/index.rst index c3ea1e152..2456490b3 100644 --- a/index.rst +++ b/index.rst @@ -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