[factory_reset] Document power cycle reset (#5148)

Author: clydebarrow

components/button/factory_reset.rst

@@ -40,6 +40,7 @@ Configuration variables:
 See Also
 --------
 
+- :doc:`/components/factory_reset`
 - :doc:`shutdown`
 - :doc:`restart`
 - :doc:`safe_mode`

components/factory_reset.rst

@@ -0,0 +1,79 @@
+Factory Reset
+=============
+
+.. seo::
+    :description: Instructions for setting up conditions that can remotely invalidate all ESPHome preferences stored in flash and reboot ESP.
+
+The ``factory_reset`` component allows you to invalidate (reset) all ESPHome :ref:`preferences <preferences-flash_write_interval>` stored in flash memory and reboot your node.
+After reboot all states, parameters and variables will be reinitialized with their default values. This is useful:
+
+- for devices preflashed with ESPHome to reset behavior back to factory state
+- in case of moving a device to a new environment or starting a new use-case (e.g. reset counters or state)
+- for privacy concerns when giving away a device
+
+.. note::
+
+    **USE WITH GREAT CAUTION!** All credentials, global variables, counters and saved states stored in non-volatile memory will be lost with no chance of recovering them.
+    Even raw reading of flash memory with ``esptool`` will not help, since data is physically erased from flash memory.
+
+    For devices configured using :doc:`captive portal </components/captive_portal>`, this will reset WiFi settings as well, thus making such devices offline.
+    You'll need to be in close proximity to your device to configure it again using a built-in WiFi access point and captive portal.
+
+Reset by Fast Power Cycling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``factory_reset`` component can be configured to clear stored preferences by repeatedly pressing the reset button or power cycling,
+which can be useful to clear the data stored in non-volatile memory on devices that can't be
+connected with a serial cable. The required number of power cycles and the maximum delay between them can be configured in the
+``factory_reset`` component configuration. Points to note:
+
+- The maximum delay affects only the time when the device is powered on,
+  not the time when it is powered off (this can't be measured).
+- The reset count will be cleared to zero when any other kind of reset occurs,
+  or if the device remains powered on and running for longer than the maximum delay.
+- Not available on RP2040 and RP2350 as the reset cause is not able to be determined.
+- On ESP8266 this feature requires the ``restore_from_flash`` feature to be enabled in the :doc:`ESP8266 platform </components/esp8266>`.
+
+.. code-block:: yaml
+
+    factory_reset:
+      resets_required: 5
+      max_delay: 10s
+
+Configuration variables:
+------------------------
+
+- **resets_required** (*Optional*, integer): The number of power cycles after which the device will be reset.
+  No default, if not configured the power cycle reset feature will be disabled
+- **max_delay** (*Optional*, :ref:`Time <config-time>`): The maximum delay between power cycles. Default: 10s
+
+``on_increment`` Trigger
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A trigger is available that will be triggered whenever the current reset cycle count changes. This happens when the
+``factory_reset`` component detects a power cycle, or when the
+cycle count is cleared to zero by timeout or a different type of reset. Arguments passed to the trigger are:
+
+- ``x``: The current cycle count
+- ``target``: The target cycle count
+
+.. code-block:: yaml
+
+    factory_reset:
+      resets_required: 5
+      max_delay: 10s
+      on_increment:
+        - logger.log:
+            format: "Fast power cycle count now %u, target %u"
+            args: [x, target]
+
+See Also
+--------
+
+- :doc:`/components/switch/factory_reset`
+- :doc:`/components/button/factory_reset`
+- :doc:`/components/button/shutdown`
+- :doc:`/components/button/restart`
+- :doc:`/components/button/safe_mode`
+- :apiref:`factory_reset/factory_reset.h`
+- :ghedit:`Edit`

components/index.rst

@@ -83,6 +83,7 @@ ESPHome-specific components or components supporting ESPHome device provisioning
     Mapping, components/mapping, mapping.svg, dark-invert
     XXTEA, components/xxtea, xxtea.svg
     Script, components/script, description.svg, dark-invert
+    Factory Reset, components/factory_reset, restart-alert.svg, dark-invert
 
 Network Hardware
 ----------------

components/switch/factory_reset.rst

@@ -40,6 +40,7 @@ Configuration variables:
 See Also
 --------
 
+- :doc:`/components/factory_reset`
 - :doc:`shutdown`
 - :doc:`restart`
 - :doc:`safe_mode`

cookbook/lambda_magic.rst

@@ -278,74 +278,6 @@ will return ``NaN``, which corresponds to ``unknown`` sensor state.
         name: "Number from text"
 
 
-Factory reset after 5 quick reboots
------------------------------------
-
-One may want to restore factory settings (like Wi-Fi credentials set at runtime, or clear restore states) without having to
-disassemble or dismount the devices from their deployed location, whilst there's no network access either. The example below
-shows how to achieve that using lambdas in a script by triggering the factory reset switch after the system rebooted 5 times
-with 10-second timeframes.
-
-.. code-block:: yaml
-
-    # Example config.yaml
-    esphome:
-      name: "esphome_ld2410"
-      on_boot:
-        priority: 600.0
-        then:
-          - script.execute: fast_boot_factory_reset_script
-    esp32:
-      board: esp32-c3-devkitm-1
-
-    substitutions:
-      factory_reset_boot_count_trigger: 5 
-
-    globals:
-      - id: fast_boot
-        type: int
-        restore_value: yes
-        initial_value: '0'
-    
-    script:
-      - id: fast_boot_factory_reset_script
-        then:
-          - if:
-              condition:
-                lambda: return ( id(fast_boot) >= ${factory_reset_boot_count_trigger});
-              then:
-                - lambda: |-
-                    ESP_LOGD("Fast Boot Factory Reset", "Performing factotry reset");
-                    id(fast_boot) = 0;
-                    fast_boot->loop();
-                    global_preferences->sync();
-                - button.press: factory_reset_button
-          - lambda: |-
-              if(id(fast_boot) > 0)
-                ESP_LOGD("Fast Boot Factory Reset", "Quick reboot %d/%d, do it %d more times to factory reset", id(fast_boot), ${factory_reset_boot_count_trigger}, ${factory_reset_boot_count_trigger} - id(fast_boot));
-              id(fast_boot) += 1;
-              fast_boot->loop();
-              global_preferences->sync();
-          - delay: 10s
-          - lambda: |-
-              id(fast_boot) = 0;
-              fast_boot->loop();
-              global_preferences->sync();
-    
-    wifi:
-      id: wifi_component
-      ap:
-        ap_timeout: 0s
-      reboot_timeout: 0s
-    
-    captive_portal:
-    
-    button:
-      - platform: factory_reset
-        id: factory_reset_button
-        name: "ESPHome: Factory reset"
-
-
 See Also
 --------