Skip to content
ESPHome - Smart Home Made Simple

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 button or switch component and/or by repeatedly pressing the reset button on the board for num_attempts times (see below).

# Example configuration entry
safe_mode:

Configuration variables

Section titled “Configuration variables”

  • disabled (Optional, boolean): Set to true to disable safe_mode. Ota automatically sets up safe mode; this allows disabling it if/when it is not wanted.

  • boot_is_good_after (Optional, 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, Time): The amount of time to wait before rebooting when in safe mode. Defaults to 5min.

  • on_safe_mode (Optional, Automation): An action to be performed once when safe mode is invoked.

WARNING

The on_safe_mode 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.

safe_mode.mark_successful Action

Section titled “safe_mode.mark_successful Action”

This action marks the boot as successful, preventing safe mode from being invoked. This is useful for devices that take a sensor reading and then enter deep sleep, rather than waiting for the boot_is_good_after time to elapse.

on_...:
  then:
    - safe_mode.mark_successful

See Also

Section titled “See Also”