Developer docs

Debug Builds and the Debug Console

A firmware you can drive from your desk: its console over Wi-Fi, its screen as a PNG, its SD card, its crash dumps, and a way back when an update goes wrong.

A Debug Build is the same firmware plus a Debug Console: the serial console, over Wi-Fi, behind a token. It is the most useful thing in the project. With it you can:

  • see everything the device prints, boot messages included, without a cable;
  • run every serial command from your desk;
  • press keys and take screenshots, so a UI change can be tested and looked at remotely;
  • copy files to and from the SD card;
  • read crash reports and fetch core dumps, decoded against the exact build that crashed;
  • update the firmware over the same Wi-Fi, and know that a bad update rolls back to a build that still has the console.

Start with Debug Builds to put one on a device, then the Debug Console. The rest are what you can do with it.

Start here01

Debug Builds

What a Debug Build is, how to build and flash one, how its token works, and why you should keep one in the fallback slot.

Console02

The Debug Console

Connect to a Debug Build over Wi-Fi: the protocol, what you get when you connect, how commands run, and what the console can and cannot do.

Console03

Files, screenshots and the SD card

Copy files to and from the card, take a screenshot, fetch a core dump and restart the device, all over Wi-Fi, with checksums.

Console04

Drive the UI from your desk

Press keys, take screenshots, fake inputs and test the awkward paths (updates, crashes, fixed IPs, crowded folders) without touching the device.

Console05

Crashes, core dumps and Safe Mode

What happens when the firmware crashes: the report, the core dump, the build it is decoded against, the main-loop watchdog and Safe Mode.

Reference06

Command reference

Every command the firmware understands, over USB serial or the Debug Console: what `help` prints, then what each one does.