Flashing and reading logs
The firmware is built. Now you push it into the board, then connect the serial port and watch what the device says. These two things are one continuous action, so they share a page — "disconnect the Console before flashing" sits right across both.
At a glance
| Browser requirement | Chrome or Edge. Firefox and Safari have no WebSerial, so flashing from the browser is out |
|---|---|
| How long it takes | Depends on the firmware size. ESP boards are written at 460800 baud, so a firmware of about 1MB usually takes 10–30 seconds. The flash dialog shows the firmware's byte count and a live percentage |
| What it overwrites | The program that was on the board |
| What it won't do | It won't damage the board. Flash it as many times as you like; you can put a different firmware on whenever you want |
| Default serial rate | 115200 |
| Where the logs live | Only in your browser, never uploaded to the backend. The buffer holds 20,000 lines or 8MB, whichever comes first |
| No Chrome? | Download the firmware and flash it with your usual tool. See below |
⚠️ Before you start: disconnect the Console.
One serial port can be held by one program at a time. While the Console on this page is connected, "Flash" in the top bar is greyed out and won't respond, and the panel carries this note: Disconnect the local Console before flashing so the serial port is free.
The bigger nuisance is a holder outside this page — the Arduino IDE serial monitor, another browser tab with this project open. The platform cannot see those, the button stays lit, and the error gives away nothing about the real cause: you get Failed to open serial port., which reads like a permissions problem and is not one. (If you are flashing from the command line with esptool.py instead of the browser, the same situation reads Access is denied. on Windows.) Close them before you flash.
Flashing
To flash:
- Check the board is plugged in, on a cable that carries data (if you aren't sure, see what you need to have ready).
- Disconnect the Console (the warning above).
- Click Flash in the top bar.
- In the dialog, wait for the firmware to download into the browser — it shows
Firmware readyplus the byte count. Then click Start flashing. - The browser opens a port picker — that window is Chrome's own, not our interface. Select your board and click Connect.
- Wait for the progress bar to finish.
What success looks like: the progress bar reaches 100% and the last line of the log reads "Flash complete". A light on the board usually blinks once — that is it restarting.
What flashing overwrites, and what it doesn't
It does: the program that was on the board is gone. It doesn't: the board itself takes no damage from this; you can flash something else in at any point, as many times as you want.
What if it gets cut off part way? Pulling the cable, closing the tab, clicking cancel — none of them damage the board. The board is left in a half-written state; flash it once more. If the reflash won't connect, hold BOOT, tap RESET, release RESET first and then BOOT, then retry straight away.
Browser not supported? Download it and flash it yourself
Firefox and Safari have no WebSerial. That is a decision by the browser vendors, not a limit of ours. The interface says so outright: This browser does not support serial flashing. Use Chrome or Edge.
Two routes:
- Move to Chrome or Edge and open this page there. That is the shortest route.
- Click "Download" in the top bar for the firmware file, then flash it with your usual tool — esptool, Espressif's official flash tool and the Arduino IDE all work.
Download links expire. If yours has, come back and click it again.
Connect the Console and see what the board is saying
Once flashing finishes the firmware is already running, but you can't see what it is doing. Connect the serial port and you can. The Console is the most useful thing on this platform — every piece of debugging starts here.
- Switch to the Console pane.
- Click Connect device at the left end of the toolbar. A Connect serial port dialog opens — the baud rate is set inside that dialog, not on the toolbar.
- In the dialog, set the baud rate to
115200— that is the agreed default; pick the wrong one and what you read is garbage — then click Connect. - Only now does the browser open the port picker; pick the same port.
- Press RESET on the board so it starts from the top — that way you see the whole boot sequence.
The Console toolbar runs, left to right: Connect device (which turns into Disconnect device once you are connected), the connection state, Pause scroll, Clear, and a local buffer indicator reading 0.0MB / 8.0MB — the only place in the interface where that 8MB appears.
What success looks like: after you press RESET, the Console prints a few lines of boot information, and then the output your firmware writes.
sta ip: 192.168.0.15), and a couple of lines below it the readings continue — Distance: 45 cm, still one a second. Every line is words and figures, not unreadable characters, which is how you know the rate is right. Long lines wrap, so you also get half-lines — a g:0x0, or a lone D sitting above istance: 57 cm. That is the wrapping, not the rate.First few lines are garbage, the rest fine? That is not a fault. On power-up the ESP32 bootloader prints a few lines at a different rate, so those lines coming out garbled is normal — keep reading past them. Garbled the whole way through is what a wrong baud rate looks like: click Disconnect device, click Connect device again, set the rate back to 115200 in the dialog, click Connect, then tap RESET on the board. If it is still garbled after that, see the serial output is all garbage.
Console connected at 74880 baud. — while the board is sending at 115200. The timestamps on the left keep ticking one line a second, but not one line of content can be made out: below that opening line there is not a readable word left. Hold it next to the shot above and the two are one glance apart.The logs stay on your machine
Serial logs are not uploaded to the backend; they stay in your browser. The buffer holds 20,000 lines or 8MB, and whichever it reaches first, the oldest lines start dropping. At the length of a typical serial line the 20,000 arrives first — so the oldest lines are already going while the toolbar figure is still nowhere near 8.0MB. They do not survive a page refresh — copy out anything you want to keep first.
Paste the log back into the conversation: this is the debugging loop
When the device behaves wrongly, the fastest move is not to read the code yourself, it is to hand back exactly what the device printed.
- Select the stretch you want in the Console (from the reset to the point where it goes wrong is usually enough).
- Copy it.
- Paste it into the project chat box.
- Add a sentence saying what you want it to look at. A log with no words leaves it guessing what you are asking.
Why this works: the log holds things it could not know while it was writing the code — the real chip on your board, the real boot parameters, the real point where it fell over. With those in hand, its next edit lands far more often.
Log too long to paste? One project chat message is capped at 8000 characters, but you can paste past that anyway: when the paste goes over the limit, the input box turns it into a .log attachment on its own. Saving the log as a .log file and dragging it into the box does the same thing. Either way, you still have to write that one sentence saying what you want it to look at.
Give the firmware a dashboard of its own
A small habit that pays well: have it print the basics at boot.
Why that sentence works: for any problem later, the first thing anyone asks is "paste your boot log". Building that into the firmware is fitting yourself a dashboard. And the build tag answers one more question directly — whether the board is running the version you just flashed, which is the only way to confirm it.
If you come from software development
Flashing is docker run, except this machine holds one program at a time and there is no docker stop — new firmware overwrites old firmware, there is no second container and no rollback. So "the code changed" and "what the device runs changed" are two different things, with a build and a flash in between.
The Console is docker logs -f, with one difference: it exists only while it is connected, and there is nothing once you disconnect — no history. Nobody keeps the log for you; if you want it kept, copy it. Which is exactly why that self-printed build tag is worth so much — it is your only image tag.
Common questions
Can I leave the Console open while flashing?
No. One serial port, one program at a time. Connect the Console after the flash finishes.
Can I flash other firmware onto it?
Yes — the board is yours. With a tool like esptool you can put the factory firmware, or anything else, back on it whenever you want. Firmware flashed from here carries no lock of any kind.
Why is there a progress bar for flashing but not for compiling?
Because the flashing progress is real — bytes written against bytes in total, a definite number. Compiling has no such quantity, and a percentage there could only be made up.
Do the logs get uploaded?
No. Serial logs stay local to your browser, and the interface says so on screen. The only way to hand one to the platform is to copy and paste it into the chat box yourself.
The board has no screen — how do I know what it is doing?
The Console, and nothing else. Which is why it is worth adding a line when you describe what you want: "print a line when a read fails too". The serial port is your only eye.