Safe mode documentation and updates (#3841)

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 <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

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</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)

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</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`

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 <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

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