Compiling and firmware
You don't have to install a compiler, and you don't have to understand the code it generates. But a few things are worth knowing: when compiling happens, who handles a failure, and why "the code changed" is not the same as "the board changed".
At a glance
| What you have to do | Nothing. Compiling triggers itself |
|---|---|
| How long one round takes | A few minutes. The first one also has to prepare the toolchain. One build is capped: thirty minutes on ESP-IDF, twenty on PlatformIO / Arduino, after which it is recorded as Build timed out |
| What comes out of it | One firmware file you can flash as it is |
| When you can download / flash | After a build succeeds. Until then those three buttons in the top bar are greyed out |
| Is there a progress bar | No. It shows only which step is running — a percentage here could only be made up |
| What to do when it fails | Most of the time it repairs and retries on its own. Only one class needs you; see below |
Compiling happens by itself — you don't click for it
You say "start writing the firmware", and it writes the code and compiles it in one continuous run. You press nothing in between.
While that runs, the top bar and the conversation show which step it is on: Analyzing the request → Preparing tool → Building firmware → Build finished. Percentages are deliberately not shown — writing code has no reliable progress to report, and a number here would only make you misjudge how much longer you have to wait.
Once the build succeeds, Download / Flash / Publish on the right of the top bar light up. That is the fastest way to tell whether usable firmware exists.
What success looks like: the progress markers in the conversation reach 📦 Build passed; Build output in the Main pane grows four rows — Compile (Succeeded), Framework, Build target, Size; and Download / Flash / Publish in the top bar all become clickable at the same moment.
A build that passes ≠ firmware that runs on your board. Compiling only checks whether the code is right as code. A pin wired to the wrong place, a module that isn't the part in the plan, not enough power — the compiler catches none of those three. The real acceptance test is those few lines in the Console after you flash it.
When a build fails, first work out which class it is
Failures are sorted into seven classes. The class is written on the "Failed stage" row of Build output in the Main pane, in English regardless of your interface language, followed by an action (for example · User action required). Of the seven, only Hardware selection needs attention needs you — it means no build target can be picked for this hardware, so go back to the conversation and switch to a supported board or fill in the missing part numbers. The other six are handled by the platform or want a later retry.
For what all seven are and whose side each one sits on, see Troubleshoot by symptom: the build keeps failing.
The English line under "Failed stage" is not addressed to you. A failure also prints a sentence below that row, for example Install PlatformIO, install the required PlatformIO platforms, or configure WB_PLATFORMIO_BIN. or Inspect backend/worker logs and fix the compile infrastructure or workflow bug. That is the backend's note to whoever operates the platform, not a step for you to follow — you have neither that machine nor any reason to touch it.
Besides Succeeded and Failed, the "Compile" row has four more outcomes that also leave you without firmware: Queue timed out, Build timed out, Cancelled, System error. For the first two, send Build it again and that is all — a timeout of either kind has nothing to do with what you typed.
One more line reads like a fifth outcome and is not one: ⚠️ Hardware incomplete; not built. It is not a value of the "Compile" row but a progress marker in the conversation — the hardware plan is not yet enough to carry the features this round was meant to implement, so the platform never started compiling and nothing about it appears in Build output. This one needs you to fill in hardware information; see Hardware plan and wiring.
Three rounds in a row with the same error? Stop waiting. Copy the failure explanation it gave you, then send: The same error three rounds in a row — try a different approach. Or fall back to the smallest version: Set all of that aside and do the smallest thing: make the on-board LED blink once a second — this one move tells you immediately whether the problem is the toolchain or that one specific feature.
The Code pane
Switch to "Code" and you see the whole project tree. You don't need to understand it — the entire flow works without reading code. But it is here, and you can open it any time. The tree itself carries no badges: Editable or Read-only appears next to the file name only once you open a file.
When you can edit, and when you can't
| While a run is in progress | Saving is blocked. The badge turns to Read-only, Save goes dead, and it tells you: A run is in progress, so saving is blocked. Save again once it finishes — your edits stay in the editor. |
|---|---|
| It has just changed this file | It tells you the file changed and that you have to click Reload for the latest content before editing further. Saving straight over it wipes out what it just wrote. |
| Files that will not open | Only binary files and files larger than 1 MB cannot be read or written here; clicking one gets you an error instead of the file. Build configuration is not in that group — platformio.ini, sdkconfig and CMakeLists.txt are small text files, so they open and they save. Generated directories such as build/ and .pio/ never show up in the tree at all |
The shorter route: don't hand-edit, say it. Change the read interval from 5 seconds to 30 seconds gets there faster than hunting for that number in the code yourself, and it rebuilds once the change is in. Hand-editing suits the case where you already know exactly which line you want to touch.
"The source has changed; the current firmware still comes from the last successful build"
The Code pane shows one of these three lines:
| No firmware has been built yet. | This project has no firmware artifact to compare the source against. Until the first successful build, this is the line you see |
|---|---|
| The source matches the latest build. | The code you are looking at is the code that latest firmware was built from |
| The source has changed; the current firmware still comes from the last successful build. | The code changed, but the firmware is still the old one. It takes another build to line them up |
This is the idea beginners get wrong most often. Between "the source changed" and "what runs on the board changed" there are two steps:
Code ──compile──▶ firmware file ──flash──▶ the program on the board
↑ ↑
skip this skip this
and the firmware and the board
stays old stays oldMiss either step and everything downstream of it is old. And note this: the platform knows the state of the first two steps, but has no idea which version is running on your board — only you know that.
If you come from software development
There is no hot reload here, and no docker restart. Four stages each carry their own state: source → build → firmware artifact → device. The first three can be queried in the cloud; the fourth is on your desk and cannot.
The "source matches the latest build / the source has changed" indicator covers only the consistency of the first two stages — the equivalent of git status. Stage three to stage four has no indicator at all — there is no kubectl rollout status to tell you which version the device is running. If you want one, build it yourself: have it print a version string in the boot log, and that line is your image tag.
Getting the firmware file
"Download" in the top bar hands you the built firmware. When that is what you need:
- Your browser has no WebSerial (Firefox, Safari) and you have to flash with another tool
- You want to flash with esptool or Espressif's official tool
- You want to keep a copy of the firmware, or send it to someone
Download links expire. If yours has, come back and click it again.
Common questions
How long is a normal build?
A few minutes. The first build of a new project also has to prepare the toolchain. If more than thirty minutes pass with nothing moving, see nothing comes back after you send a message.
Can I have it compile without changing the code?
Yes — send Build it again without changing the code.
Where does the "Firmware features" table come from?
From the code, not from the plan. If it says a feature is there, that feature really was written in. So you can use that table as an acceptance checklist — check whether what you asked for is on it.