Devices end up in walls, ceilings and fuse boxes. Plan now how you'll recover them when the Wi-Fi password changes or a bad config makes them crash.
Fallback hotspot and captive portal
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
password: !secret ap_password
captive_portal:
- When the device can't reach the router (default
ap_timeout: 90 s), it opens its own access point. Otherwise the access point stays off. - Join that hotspot and the captive portal at
http://192.168.4.1/lets you enter new Wi-Fi credentials or upload a firmware file. - The portal is plain HTTP: always set an AP password.
- Credentials entered in the portal are overwritten by the next serial upload. Update
secrets.yamltoo, so the next build doesn't bring back the old credentials.
Safe mode: automatic protection against boot loops
ESPHome's safe mode (safe_mode component) protects against boot loops:
| Setting | Default | Meaning |
|---|---|---|
failed boots before safe mode (num_attempts) |
10 | a boot "fails" if the device resets before it counts as good |
boot_is_good_after |
1 min | uptime after which a boot counts as successful |
reboot_timeout in safe mode |
5 min | the device reboots and tries again |
In safe mode, only serial logging, the network and OTA run. Every other component is disabled, so a crashing sensor driver or a bad lambda can't stop you from flashing a fixed firmware over the air.
What to do when a device keeps rebooting
- Wait: after about ten fast crash-reboots, safe mode starts and the device becomes reachable for OTA.
- Flash a corrected (or minimal) config over the air.
- If it never comes back, fall back to serial flashing, so keep the physical access in mind when you install it.