DSC-BRAIN USER GUIDE · MAINTENANCE & UPDATES
Updating the brain, the toolchain and the fleet firmware
The routine order: brain first, then the ESPHome toolchain if offered, then firmware with a canary. Ethernet gates, refusals, rollback and the SSH fallbacks.
● verified for 9.0.0 · corrected for 9.8.0 on 2026-09-30
● first mirrored 2026-09-15
On this page
Safe order: download a backup first (Settings › System › Download backup; see Backup, restore, setup profiles and factory reset), then update the brain, then the ESPHome toolchain if it is offered, then firmware: the canary probe first, the rest once it reports OK, the hub last.
Stop if: the Firmware card says No firmware secrets; free disk is under 1.5 GiB (the toolchain update refuses); a build job is already running; the canary does not report the new version; or any job fails. Fix that before you release the rest. Never run ESPHome as root on the Pi (see the end of this page).
Nothing flashes without a confirm click. Live and Overview keep serving last-known values while a device reboots. Expect a short fleet-offline window whenever the brain restarts. If the brain is away longer than a plug's wait (heater 60 s, heat mat and humidifier 90 s, dehumidifier 240 s), that plug switches itself off, and a plug you reflash starts OFF. The hub keeps running its wired fans and dimmed lamps from its own sensors and its own clock, except while it is being reflashed. When an update finishes, check Overview and Kit › Inventory: every device online and every appliance doing what you expect.
1. Brain and dashboard
Settings › Devices › Firmware › Updates → Check for updates. Needs Ethernet: the brain reads the latest published release from plausible-deniability.net (a small public manifest — the source repository is private, so kits no longer ask GitHub) and compares it with the running brain and each device's firmware. Offline kits keep the baked version and say so. Update DSC-Brain runs the self-update command configured on the Pi. If the card shows a manual instruction instead, this image has no self-update command: update by hand over SSH (table below). The brain restarts and the page reloads on the new bundle; confirm the version under Settings › System › About.
Product libraries. DSC-KitLib (lights, equipment) and DSC-NuteLib (nutrients, feed charts, growing media) update separately from the brain, under Settings › Integrations › Libraries. The brain reads the library manifest daily; Check for updates reads it now. Install vX downloads the file, checks its size and checksum and swaps it in without a restart; Back to vX returns to the version it replaced. Install updates automatically is off by default. A release that needs a newer brain says so and is not offered.
2. ESPHome toolchain (only when offered)
Settings › Devices › Firmware shows installed vs latest vs pinned min. Update ESPHome → x.y.z hands the job to the host helper, which installs the version and restarts the ESPHome dashboard; the card streams the log. It is refused when offline, when the target is below the pin, when the target is already installed, under 1.5 GiB free, or while a build job is running. Roll back to X reinstalls the version the last successful change came from. A newer ESPHome the firmware cannot yet build on shows Newer ESPHome held back.
3. Device firmware
Same card. Canary Probe 2 first compiles and flashes one probe over the air. Wait for Canary OK (the probe reports the new version). Then Release the rest (N, hub last); each device is compiled and flashed in turn by the build worker. Reflash whole fleet is the one-click path. A failed job stops the queue at that seat (Probe update failed); fix it from the job log or Logs ↗ in the ESPHome dashboard and re-queue just that seat.
4. Verify
Settings › Devices › Firmware: every row on the expected stamp and online. If a row is behind or offline, re-queue just that seat; if it still fails, see Updates and firmware jobs fail. Overview fleet chip ok. Kit › Inventory all in-service devices online.
Rollback
- Toolchain: Roll back to X, or the pip command below.
- Firmware: re-queue the seats after rolling the toolchain back; the same YAML on the previous ESPHome reproduces the previous binary. Hub and panel must keep a matching ESP-NOW command tag.
- Brain: every brain deploy leaves a rollback point under /opt/dsc-hub-rollback/<time>/ — the previous image tagged dsc-hub-brain:rollback-<time>, its source, its dashboard entry and a ROLLBACK.txt with the two commands that bring it back (the five newest are kept). Or Settings › System › Backup › Import the last export.
SSH fallbacks (as user dsc)
| Situation | Command |
|---|---|
| Dashboard rollout unavailable | sudo bash /opt/dsc-hub/pi/flash-fleet-remote.sh - [seats…] (canary first, hub last) |
| Hub stuck on its fallback hotspot | flash-hub-fallback-remote.sh |
| Sonoffs on the AP island / their fallback AP | flash-sonoff-lan-remote.sh / flash-sonoff-fallback-remote.sh |
| Toolchain by hand | sudo -u dsc /opt/dsc-esphome-venv/bin/pip install esphome==<ver> then sudo systemctl restart dsc-esphome-dashboard |
| Brain by hand | docker compose -f /opt/dsc-hub/docker-compose.yml pull brain then up -d brain. Prefer docker stop -t 20 then start over restart. |
The - after the script name makes it read the sudo password from standard input, so the password never sits on the command line, in your shell history or in the process list. Do not type the password as an argument. The two fallback flash scripts take the same first argument: use - there too. The scripts named without a folder are in /opt/dsc-hub/pi/, next to the first one. All of these need the kit's firmware secrets file on the Pi (/opt/dsc-hub/firmware/v4/secrets.yaml, mode 0600). The Firmware card shows No firmware secrets when it is missing.
Never run ESPHome as root on the Pi
The toolchain lives in the dsc user's venv. Running it as root creates root-owned build caches that later break the dashboard's builds.
DSC-Brain user guide · Updating the brain, the toolchain and the fleet firmware · this page is edited on the site; the Notion original was retired after the mirror