Flashing devices over USB

How the USB flash step works, the kit roles it offers, boot-mode tips, and the fallback paths.

USB flash writes the baked binaries that shipped on the SD image to a device using the host's esptool. It does not compile anything. Later firmware updates go over the air from Settings › Devices › Firmware.

Before you start: the dashboard is open at #/setup, and you have a USB data cable and the device to hand.

Probes 3 and 4 are not kit defaults and are not offered.

1. Setup › USB flash (#/setup). On a kit that is already commissioned, or whose hub or probes have reported, the wizard stays parked; use the ESPHome dashboard below instead.
2. Pick the role. A role greyed out with a reason (for example missing or zero-byte file) has no usable binary on this brain; nothing can be flashed for it until a bake includes it.
3. Connect the device with a data cable (charge-only cables show no port).
4. Pick the port. Press Flash and wait for the log to end with OK. If it ends with FAILED, read the reason and see Boot mode below.

Most kit boards enter flash mode on their own. If the log says the chip did not respond: hold BOOT, tap RESET (or re-plug), release BOOT, and press Flash again. Mains safety: unplug a Sonoff plug from the wall and from the appliance before you open its case, and never connect a USB-serial adapter to a plug that is connected to mains. The Sonoff plugs need their case open and a USB-serial adapter on the header; hold the button while applying power.

The shipped Pi image runs the brain in a container that has no USB passthrough, so the wizard may see no serial ports at all. Options, in order of ease:

1. ESPHome dashboard at the ESPHome dashboard address on the kit card (port 6052) → the device → Install → Plug into this computer. This uses your browser's serial support (Chrome or Edge).
2. A workstation with the ESPHome CLI: esphome run dsc-hub-kit.yaml from firmware/v4 with the kit's secrets.yaml.
3. Record the debt with Skip, commission, and flash later.

A hub built for the Pi kit joins the Pi's own Wi-Fi network, DSC-Brain-XXXX (XXXX is unique to your card; setup shows the full name. Cards made before 9.9.0 use DSC-Brain), by itself. If yours opens a DSC-Setup-XXXX hotspot instead (the factory build, which is parked), continue with Fleet Wi-Fi join. Sonoff plugs join the Pi's DSC-Brain-XXXX network and appear in Kit › Inventory when the brain finds them by the host name or IP recorded in Settings › Devices.

Next: every device flashed? Go to Fleet Wi-Fi join (wizard step 3).

Guide contents  ·  Setup  ·  Troubleshooting  ·  Digital Stealth Care

DSC-Brain user guide · Flashing devices over USB · this page is edited on the site; the Notion original was retired after the mirror