DSC-BRAIN USER GUIDE · TROUBLESHOOTING
Updates and firmware jobs fail
Check refused (no Ethernet), toolchain refusals (pin, disk, running job, helper missing, secrets), canary failed or unconfirmed, a seat stuck in the queue, and rolling back.
● verified for 9.0.0 · firmware train 8.2.0.0
● last verified 2026-09-17 · mirrored 2026-09-15
Updates › Check for updates does nothing
It needs Ethernet and internet (Settings › Network › Internet & LAN shows the reach check). Offline kits keep the baked version by design. It reads the latest DSC release from the release manifest on plausible-deniability.net, not GitHub; if the lookup fails or nothing is published yet, the card prints the reason under the version line.
Update DSC-Brain shows a manual instruction
This image has no self-update command configured. Deploy from a workstation, or over SSH: pull and up -d brain (see Updating). Prefer docker stop -t 20 + start over restart.
Update ESPHome is refused
The card says why:
| Chip | Fix |
|---|---|
| BELOW PINNED MIN | The target is older than the firmware's minimum. Pick a newer one. |
| Newer ESPHome held back | The firmware cannot build on that ESPHome yet. Wait for a release that lifts the cap. |
| Low disk | Under 1.5 GB free. Prune journals and frames, clear old build caches over SSH. |
| Helper missing | The host update unit is not enabled; the card shows the enable command. |
| Dashboard down | If it followed an ESPHome update, Roll back; otherwise read journalctl -u dsc-esphome-dashboard on the Pi. |
| No firmware secrets | Copy the kit's secrets.yaml to /opt/dsc-hub/firmware/v4/ (mode 0600, owner dsc). |
| Deprecated backend | The legacy dsc-hub-esphome container backend; re-run the deploy or bake to switch to the host ESPHome venv. |
A queued or running build job also blocks a toolchain update; wait for it.
Canary failed / unconfirmed
- Canary failed: read the job log (card) or Logs ↗ in the ESPHome dashboard. Common: the probe was offline (OTA needs it reachable), a compile error on a new toolchain (roll back), or Wi-Fi drop mid-OTA (re-queue).
- Canary unconfirmed: flashed, but the probe has not reported the new version yet. Give it a few minutes; if it never reports, it may be on its fallback hotspot.
A seat stuck in the queue
A failed job stops the queue at that device. Fix that device, then re-queue just that seat; the rest resume in order, hub last.
Hub and panel disagree after a flash
Both must carry the same ESP-NOW command tag. Flash them from the same toolchain version; use the co-flash checklist in the engineering docs if the panel goes blank.
Rolling back
Toolchain: Roll back to X. Firmware: re-queue the seats after the rollback. Brain: previous image over SSH, or import the last backup.
DSC-Brain user guide · Updates and firmware jobs fail · this page is edited on the site; the Notion original was retired after the mirror