diff --git a/components/button/factory_reset.rst b/components/button/factory_reset.rst new file mode 100644 index 000000000..03e1bfe09 --- /dev/null +++ b/components/button/factory_reset.rst @@ -0,0 +1,51 @@ +Factory Reset Button +==================== + +.. seo:: + :description: Instructions for setting up buttons that can remotely invalidate all ESPHome preferences stored in flash and reboot ESP. + :image: restart.svg + +The ``factory_reset`` button allows you to remotely invalidate (reset) all ESPHome :ref:`preferences ` 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 `, 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. + + +.. figure:: images/factory-rst-ui.png + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration entry + button: + - platform: factory_reset + name: Restart with Factory Default Settings + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the button. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Button `. + +See Also +-------- + +- :doc:`shutdown` +- :doc:`restart` +- :doc:`safe_mode` +- :doc:`/components/switch/factory_reset` +- :doc:`template` +- :apiref:`factory_reset/factory_reset_button.h` +- :ghedit:`Edit` diff --git a/components/button/images/factory-rst-ui.png b/components/button/images/factory-rst-ui.png new file mode 100644 index 000000000..0dcb0c13f Binary files /dev/null and b/components/button/images/factory-rst-ui.png differ diff --git a/components/button/restart.rst b/components/button/restart.rst index 9f7f1ce2f..03be784b7 100644 --- a/components/button/restart.rst +++ b/components/button/restart.rst @@ -25,6 +25,9 @@ Configuration variables: See Also -------- +- :doc:`shutdown` +- :doc:`safe_mode` +- :doc:`factory_reset` - :doc:`/components/switch/restart` - :doc:`template` - :apiref:`restart/button/restart_button.h` diff --git a/components/button/safe_mode.rst b/components/button/safe_mode.rst index 0bd4a4a0b..ccf41371f 100644 --- a/components/button/safe_mode.rst +++ b/components/button/safe_mode.rst @@ -33,6 +33,8 @@ See Also - :doc:`shutdown` - :doc:`restart` +- :doc:`factory_reset` +- :doc:`/components/switch/safe_mode` - :doc:`template` - :apiref:`safe_mode/safe_mode_button.h` - :ghedit:`Edit` diff --git a/components/button/shutdown.rst b/components/button/shutdown.rst index 93c6e393c..68dadc518 100644 --- a/components/button/shutdown.rst +++ b/components/button/shutdown.rst @@ -32,6 +32,9 @@ See Also -------- - :doc:`restart` +- :doc:`safe_mode` +- :doc:`factory_reset` +- :doc:`/components/switch/shutdown` - :doc:`template` - :apiref:`shutdown/shutdown_button.h` - :ghedit:`Edit` diff --git a/components/switch/factory_reset.rst b/components/switch/factory_reset.rst new file mode 100644 index 000000000..8c9eb5b00 --- /dev/null +++ b/components/switch/factory_reset.rst @@ -0,0 +1,51 @@ +Factory Reset Switch +==================== + +.. seo:: + :description: Instructions for setting up switches that can remotely invalidate all ESPHome preferences stored in flash and reboot ESP. + :image: restart.svg + +The ``factory_reset`` switch allows you to remotely invalidate (reset) all ESPHome :ref:`preferences ` 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 `, 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. + + +.. figure:: images/factory-rst-ui.png + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration entry + switch: + - platform: factory_reset + name: Restart with Factory Default Settings + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the switch. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Switch `. + +See Also +-------- + +- :doc:`shutdown` +- :doc:`restart` +- :doc:`safe_mode` +- :doc:`/components/button/factory_reset` +- :doc:`template` +- :apiref:`factory_reset/factory_reset_switch.h` +- :ghedit:`Edit` diff --git a/components/switch/images/factory-rst-ui.png b/components/switch/images/factory-rst-ui.png new file mode 100644 index 000000000..5f75eac0c Binary files /dev/null and b/components/switch/images/factory-rst-ui.png differ diff --git a/components/switch/restart.rst b/components/switch/restart.rst index 49aef556c..e66be7c1e 100644 --- a/components/switch/restart.rst +++ b/components/switch/restart.rst @@ -29,9 +29,10 @@ Configuration variables: See Also -------- -- :doc:`/components/button/restart` - :doc:`shutdown` - :doc:`safe_mode` +- :doc:`factory_reset` +- :doc:`/components/button/restart` - :doc:`template` - :apiref:`restart/switch/restart_switch.h` - :ghedit:`Edit` diff --git a/components/switch/safe_mode.rst b/components/switch/safe_mode.rst index 17ad39c44..73ae6384a 100644 --- a/components/switch/safe_mode.rst +++ b/components/switch/safe_mode.rst @@ -33,6 +33,8 @@ See Also - :doc:`shutdown` - :doc:`restart` +- :doc:`factory_reset` +- :doc:`/components/button/safe_mode` - :doc:`template` - :apiref:`safe_mode/safe_mode_switch.h` - :ghedit:`Edit` diff --git a/components/switch/shutdown.rst b/components/switch/shutdown.rst index 814ba446e..f2d331a86 100644 --- a/components/switch/shutdown.rst +++ b/components/switch/shutdown.rst @@ -32,6 +32,9 @@ See Also -------- - :doc:`restart` +- :doc:`safe_mode` +- :doc:`factory_reset` +- :doc:`/components/button/shutdown` - :doc:`template` - :apiref:`shutdown/shutdown_switch.h` - :ghedit:`Edit` diff --git a/index.rst b/index.rst index 6c089a4ea..ece8120ef 100644 --- a/index.rst +++ b/index.rst @@ -495,6 +495,7 @@ Switch Components Restart Switch, components/switch/restart, restart.svg Safe Mode Switch, components/switch/safe_mode, restart-alert.svg Shutdown Switch, components/switch/shutdown, power_settings.svg + Factory Reset Switch, components/switch/factory_reset, restart-alert.svg Generic Output Switch, components/switch/output, upload.svg Template Switch, components/switch/template, description.svg UART Switch, components/switch/uart, uart.svg @@ -515,6 +516,7 @@ Button Components Restart Button, components/button/restart, restart.svg Safe Mode Button, components/button/safe_mode, restart-alert.svg Shutdown Button, components/button/shutdown, power_settings.svg + Factory Reset Button, components/button/factory_reset, restart-alert.svg Wake-on-LAN, components/button/wake_on_lan, power_settings.svg Fan Components