Maintenance

Firmware updates

Updates are local by design. No cloud, no auto-download, no server. A signed .heronpkg bundle - a single file - is applied to a plugged-in device.

1. Drop the .heronpkg file into ~/.heron/updates/
2. Plug the Heron into your computer
3. Run heron update

The CLI verifies the bundle signature against a public key burned into the device at manufacturing, stages the files to .new paths, verifies them on the device, then renames them atomically. A power cut during the apply leaves the old firmware intact - the live file is never overwritten until the new one is in place.

The device refuses to apply a bundle whose version number is not higher than the current one. To revert, use heron update --rollback (one level) or re-apply an older bundle with --force.

Troubleshooting

Heron will not show up on Wi-Fi

• Check the Wi-Fi password - type it again during setup
• Move Heron closer to your router
• Plug Heron back into your computer, open the setup page, and run setup again

Dashboard can't find Heron

• Your computer and Heron need the same Wi-Fi - check that first
• Try the manual IP: open your router's connected-devices list, find heron, open http://<IP>:8080
• If you cleared your browser data, the dashboard forgot the last IP - use manual entry

Router will not accept the DNS change

• The setup page has instructions for your router brand
• Some routers call it "Static DNS" or "DNS Server," not just "DNS"
• Still stuck - email with your router model

Setup page can't find the device

• Use Chrome or Edge - Safari and Firefox do not support WebSerial
• Close any other program that might be using the USB port - if you used Thonny to flash the device, close it completely
• Unplug Heron, plug it back in, refresh the setup page

Setup page says "Device verification failed"

• Use Chrome or Edge
• Unplug Heron, plug it back in, try again
• Still stuck - email

Diagnostics

The CLI exposes raw device state for debugging empty-log and connectivity issues:

heron debug

Returns the raw /debug dump: DNS request count and last five entries, device tracker state, last DNS error, and whether the DNS socket is bound. Useful for diagnosing why the log is empty.

For DNS-specific issues, the firmware includes a diagnostic tool that runs four tests (T1–T4) covering socket bind, upstream reachability, forwarding, and logging. Access it via the firmware REPL over USB.

Resetting the device

• Clear the DNS log: from the dashboard, or by resetting the device. No remote wipe exists - there is no remote connection.
• Change Wi-Fi: plug into a computer, run the setup page again with the new SSID and password.
• Full wipe and re-manufacture: dev only. Hold BOOTSEL while plugging in to flash flash_nuke.uf2, then re-run flash_known.py.

What never to do

• Never create a boot.py file. os.dupterm(None, 1) can permanently disable USB serial. Recovery requires flash_nuke.uf2. All init logic belongs in main.py.
• Do not close Thonny silently before setup. Only one app can own the USB serial port - if Thonny is open, the setup page cannot connect.