From a sentence to a running board
We are going to finish a real project: an ultrasonic rangefinder — it measures the distance to the obstacle in front once a second and prints the reading to the serial port. By the end of this page you will have a board in your hands running firmware of your own. This project has a complete published version under “Public shares”, and every step here is built around it.
At a glance
| Time at the screen | About 30–60 minutes |
|---|---|
| Money | About ¥10 |
| Software needed | Chrome or Edge. No IDE to install, no compiler to install |
| What you end up with | A board running firmware of your own, and a project you can keep working on |
Already have a board? Jump straight to Step 1 and start describing — name your board model in the description and that is enough.
Step 0 | Get these together first
Get the things below together first; every step after this one needs them.
What you must have
| A dev board | This page uses the ESP32-S3-DevKitC-1. An ESP32-C3 board works too; only the pin numbers change with it. Do not buy an STM32 or a Raspberry Pi Pico — no firmware can be built for them |
|---|---|
| A USB cable that carries data | The easiest thing to get wrong. With a charge-only cable the power LED on the board comes on, the computer does not recognize the board at all, and nothing reports an error. Use a cable you know has transferred files to a phone |
| Chrome or Edge | Firefox and Safari cannot flash from the browser |
| A sensor | This page uses the HC-SR04 ultrasonic ranging module. If you want to prove the whole flow first, this one can be ordered later |
| Jumper wires and a breadboard | Four wires run between the HC-SR04 and the board (VCC, GND, TRIG, ECHO). The photo on this page uses a breadboard and jumper wires |
What you do not need
No Arduino IDE to install, no ESP-IDF to install, no cross-compile environment to configure, no C++ to write. The build happens in the cloud; the flashing happens in the browser.
Step 1 | Say what you want to build
Open WhispBuild. The middle of the home page is a single input box.
Copy this into it (if you already bought a different board, swap the model name):
Why this message works: it names the board and the module (nothing has to be guessed for you), it gives two pins (one round trip saved), it states how the module is powered and grounded, and it says what this round is not doing. To learn how to write a description like this, read How to describe the device you want.
After you send it, it talks with you first and checks whether a project should be created. Creating a project takes your own confirmation — the name may already be filled in for you, so read it before you click.
What success looks like: the browser moves to the project page — chat on the left, and on the right an empty Main pane reading “Describe the device you want in the chat on the left…”.
Step 2 | Read the hardware plan it gives you
Once you are inside the project, state your requirement again (or it has already carried it over) and it starts on the hardware plan. That round usually takes a minute or two.
When the plan is ready, the chat lists the parts it picked, where each pin goes and what the constraints are. Read the note among them — the pins it gives are derived from documentation, so check them against the physical parts before you wire anything.
The Main pane on the right fills in two blocks at the same time: Modules (what it picked for you — a list) and Pin connections (wire it this way — a table). Those two are what you wire from later. How to read them →
If it reads fine, reply with a confirmation; if it does not, say what is wrong, for example switch to the ESP32-C3 I already have or I plan to add a voltage divider on ECHO — write that into the plan.
What success looks like: the chat has given you a full parts list and pin assignment, and the Main pane now shows Modules and Pin connections. The “Hardware plan confirmed” badge in the top bar only lights up after the plan is frozen — what freezing means →
Step 3 | Order the parts
With the plan settled, order from the Modules list.
Things you can do first:
- Have it write the firmware and get a build to pass. Building needs no board in hand, see Step 5; once the board is in your hands you flash it straight away.
- Install Chrome or Edge.
- Skim the Troubleshoot by symptom page. Nothing to memorize — knowing the page exists and roughly what is on it is enough. When the board is in your hands and you are genuinely stuck, you will know where to look.
- Read How to describe the device you want. It is the half hour with the highest return.
Once the board is in your hands, do one thing first: compare the model printed on the board against the one you named in the plan. Two boards in the same family can have completely different pinouts; when the model does not match, the wiring, the flashing and the serial output can all fail, and no error message points at the model.
Step 4 | Plug it in and let the computer see it
Do not connect the sensor yet. The first time round, plug in only the board and the cable, and prove the most basic link works.
- Plug the board straight into the computer with that data-capable cable (not through a hub).
- The power LED on the board should come on.
- Confirm the computer recognized it: on Windows open Device Manager and look under “Ports (COM & LPT)”; on macOS run
ls /dev/cu.*in a terminal; on Linux runls /dev/ttyUSB* /dev/ttyACM*.
What success looks like: one new entry appears in the system's port list, with something like USB, CH340, CP210 or usbserial in its name.
Nothing new appeared? Do not suspect a dead board yet. Swap the cable first — a charge-only cable is the most common cause at this step. If that changes nothing, go to The board is plugged in, but the port list does not show it, which has a test that tells you which side the fault is on.
Step 5 | Have it write the firmware and build it
Back in the chat, type:
It then writes the code and builds. That round takes a few minutes. There is no percentage progress bar in the interface — such a number would be made up. What you get instead is the step it is on: analyzing the requirement, preparing the toolchain, generating the firmware and building it.
When the build succeeds, it spells out in the chat what it did and what the build configuration is. The three buttons on the right of the top bar — Download / Flash / Publish — light up only at that point; until a firmware file exists they are gray.
What success looks like: the progress marker in the chat reaches 📦 Build passed, and the “Flash” button in the top bar turns from gray to clickable.
A failed build is not a dead end — it reads the compiler error, changes the code and builds another round. If several rounds in a row fail, see The build never passes, which has a table of which categories need you to step in and which do not.
Step 6 | Flash it
⚠️ One thing first: if you have Console open, click “Disconnect device”. A serial port can be held by only one program at a time. While this page's Console is connected, “Flash” is gray and does nothing; while Arduino IDE or another browser tab holds the port, the button stays lit but flashing fails, and the error gives no hint that this is the reason.
- Confirm the board is plugged in.
- Click Flash in the top bar.
- In the dialog that opens, wait while the firmware downloads into the browser (it shows
Firmware readyand a byte count), then click Start flashing. - The browser opens a port picker — that window belongs to Chrome, not to 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 status beside it turns to “Flash complete”; the last line of the log is the English sentence Flash completed with … for …. (it is English in both interface languages). The LED on the board usually blinks once — that is it rebooting.
Port picker empty? Then the computer never recognized this board at all. The problem is not in this flashing step, it is in Step 4. Go to The board is plugged in, but the port list does not show it.
Flashing overwrites the program that was on the board, and it does not damage the board.
Step 7 | Read what the device is saying
The firmware is already running, but you cannot see what it is doing yet. Connect the serial port and you can.
- Switch to the Console pane.
- Click “Connect device” and set Baud rate to
115200— that is the agreed default; pick the wrong one and what you read is garbage. When that happens, click “Disconnect device” and connect again with the rate set to115200; if it is still garbage, see The serial port connects, but everything it prints is garbage. - The browser opens the port picker once more; choose the same port.
- Press the RST button on the board — the reset button, silkscreened RST — so it boots from the start once.
What success looks like: one line a second, reading Distance: 45 cm. Hold your palm in front of the module and take it away, and the number follows.
When it will not work, send the log back to it
This is the most useful loop on the whole platform: select the log in Console → copy → paste it into the chat box → say what you want it to look at. It changes the code against that log and rebuilds, and you flash once more.
A tour of the interface
By now you have used the whole interface. Here is the map, after the fact: the left is always the chat, and everything starts from there; the right is four switchable panes, each answering one question.
| Main | “What did it decide for me?” Modules, pin connections, the firmware features already implemented, build output. In detail → |
|---|---|
| Files | “What did I give it?” Schematics, datasheets and other long-lived project material. In detail → |
| Code | “What did it write?” The full project directory tree. Reading it is optional — the whole flow works without it. In detail → |
| Console | “What is the board saying?” Live serial log. The log stays local to your browser and is never uploaded. The Console screenshot on the detail page comes from the networked version of this project, which is why it carries a few extra Wi-Fi and IP lines; this page’s first round has no networking, and the reading lines are the same. In detail → |
Those three buttons on the right of the top bar — Download gets you the firmware file, Flash writes it straight to the board, Publish shares the whole project. They light up only once a firmware build exists. To their left sits Advanced, which is gray and cannot be clicked.
If you come from software development
The mental model for all of this is chat → project change → build → firmware artifact → flash → device. The first four links are in the cloud, stateful and inspectable; the last link is on your desk, and the platform cannot see it at all.
So “Build passed” proves the code side is sound, not that it runs on your board — a pin wired to the wrong hole, a module that is not the model in the plan, a supply that cannot hold the current: the compiler catches none of them. The real acceptance test is always those few lines of output in Console.
Next
You have been through the entire flow. From here you can: