ESPHome: flash once over USB, then update over the air with an encrypted OTA

1. First install: over USB/serial, once per device

• Connect the board by USB (or a USB-serial adapter for bare modules).
• If upload fails to connect, put the chip into bootloader mode: hold the BOOT button (GPIO0 to GND) while powering up or pressing reset.
• Flash from the ESPHome dashboard, the CLI (esphome run device.yaml), or the browser installer at web.esphome.io.

After this first install, every update can go over the air.

2. Configure OTA with encryption, not a password

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    encryption:          # reuses the API key above

• ESPHome's docs recommend encryption over password:. It keeps the firmware image confidential in transit, while a password only authenticates the upload.
• encryption: and password: can't be combined. Remove password: when you switch.
• A device flashed over serial can use encryption right away. A device updated over the air gets it once it runs ESPHome 2026.9.0 or newer with an encryption key it can offer.
• Older configs that use password: still work, but use a strong, unique one per device.

3. Pitfalls

• ESP8266: after a serial upload, reset the module (power-cycle or reset button) before the first OTA. Otherwise OTA fails.
• OTA fails after "Connecting…": check that the device name/IP resolves (mDNS), and that the firewall allows the upload. Use esphome upload device.yaml --device <IP> to bypass name resolution.
• Deep-sleep devices are asleep most of the time. See the deep sleep item for keeping them awake during an update.
• Keep the YAML and secrets.yaml backed up: without the key, you can only recover a device by flashing it over serial again.