Clone an existing project
Someone has already finished a project. You buy the same set of hardware from its parts list, copy the project, change the Wi-Fi to yours, flash it, and it runs. This is the fastest first success on this platform.
At a glance
| What you get out of a clone | A project that is entirely yours: the source, the hardware plan, the dependency list, the files — all of it |
|---|---|
| Your relationship to the original author | Neither side affects the other. You change yours, they change theirs |
| Do you have to sign in to look | Public projects are readable without signing in, and the firmware is downloadable too. Signing in is what cloning needs |
| How long it takes | About 10 minutes in front of the screen |
| What you need | The same board and parts as the original project — the release page lists them |
Why this is worth starting from
Building a project from nothing means handling four new things at once: how to describe what you want, whether the plan is right, whether you bought the right hardware, whether the flashing setup works. Cloning takes the first two off the table — the plan has been verified, the firmware has been compiled. All you have to confirm is the hardware and the flashing setup.
Once you have been through that whole run and there is genuinely a program running on the board, going back to build your own will be much clearer.
Step 1: Pick one
Open whispbuild.com and scroll down — that is the Project gallery. You do not have to sign in to look, and the "See all →" link to the right of the Project gallery heading opens the full list.
ESP32-S3 · esp-idf). A project that has been cloned also shows the count at the right of that row: the card on the left, "ESP32-S3 HC-SR04 Real-Time Distance Monitoring Webpage", reads "Cloned 2×"; the one on the right has never been cloned, so that spot is empty. The card on the left is the project this documentation uses from start to finish.Clicking into a card opens its release page — a complete guide to cloning it.
Once you sign in, the app home page gains two tabs below: My projects and Public shares. Public shares holds the same set of projects, so you can pick from there instead.
Step 2: Read the release page and confirm you can build it
A release page is made of a fixed set of sections, with a table of contents on the left you can jump from. The default order is:
| Finished build | What it looks like when it is built. A photo or video says it most directly |
|---|---|
| Project overview | What the project is for |
| Where to buy | This section only exists if the author filled it in |
| Flashing | Firmware download, flashing parameters, and the settings already baked into that firmware |
| Clone this project | The "Clone" button lives in this section, and below it are the settings you have to change after cloning |
| How it works | Block diagram, timing. Read this if you want to understand it |
| Build steps | The part to read closely — two routes: "Reproduce it on WhispBuild" (marked "Recommended") and "Build it by hand". The wiring and assembly images are in this section too |
| Verification | What the author verified, and what problems they ran into |
| Bill of materials (BOM) | Which components to buy, and what they look like |
| Reference | Pin mapping, dependency list, firmware details, schematics and datasheets |
The first five sections are fixed in place; the author can reorder the ones after them, so the order you see will not necessarily match the table above. "Where to buy" and "Reference" disappear entirely when they have no content; the rest stay even when empty.
The example project this documentation keeps using has a release page like that: bill of materials, pin mapping and flashing parameters are all on it, and you do not have to sign in to read it. Open that release page ↗
Read the "Bill of materials (BOM)" first and confirm you can get the parts, or already have them. If the hardware does not match, the clone will not run — the firmware was compiled against that exact set of hardware. Get whatever you are missing first.
Step 3: Click "Clone"
The button sits beside the heading of the release page's "Clone this project" section. Clicking it makes the platform copy the whole project and create it as a project of your own.
- Click "Clone".
- A "New project from template" dialog opens.
Project namedefaults to the original title, and you can rename it to whatever you call it. - Click "Create project" in that dialog. The button changes to "Creating…"; wait for it to finish.
If creating it fails: the dialog stays open and a red error line appears above the "Create project" button. Deal with whatever it says, then click "Create project" again — a retry creates the project from scratch rather than resuming the half-finished one.
What tells you it worked: once the clone finishes, the interface opens the new project directly, so you do not have to go looking for it in your project list. The Main pane already holds the complete hardware plan, the Code pane already holds code, and the top of the Main pane reads "Cloned from XXX v1".
Step 4: Change it into yours
A cloned project usually still carries the original author's settings — their home Wi-Fi name and password. The release page covers this in two places: the "Flashing" section carries a table of the settings already baked into that firmware, and "Project settings", inside the "Clone this project" section, is a written list of what you have to change after cloning. For the distance-measuring project used throughout this documentation, the "Flashing" section lists:
| Field | Value |
|---|---|
MEASUREMENT_INTERVAL_MS | 1000 |
WIFI_SSID | "whispbuild" |
WIFI_PASSWORD | "whispbuild" |
You do not have to find the right line yourself — say it in the chat:
It edits the matching settings, rebuilds, and produces a firmware that is yours.
Why can you not use the firmware downloaded from the release page directly? That firmware is already-compiled bytes with the original author's settings baked in, and they cannot be edited. The release page says as much. To put your own settings in, you have to clone and get the source.
Step 5: Wire it up and flash it
From here it is exactly like a project of your own: wire it per the pin connections table, then flash it.
Check it against the physical board before wiring anyway. The board the original author used and the one you bought may be different revisions of the same model, and the pins do not have to line up. What you check against is the silkscreen printed on the board.
You can also build it from scratch without the platform
Besides "Reproduce it on WhispBuild", the "Build steps" section carries a second route, "Build it by hand": clone it to get the source, then install the toolchain and compile it yourself, off the platform. The release page gives the full dependency list and build parameters.
That route takes more work, but if you already have a development environment you know well, it may suit you better.
If you come from software development
Cloning is close to git clone plus a full fork: the source, the hardware plan, the dependency list and the uploaded files are all copied under your account, and the two sides evolve independently afterwards — there is no upstream, and no way to pull the original author's later changes.
"Cloned from XXX v1" is only a lineage record, not a reference you can sync against. If the original author withdraws the whole template, your copy carries on existing — the record turns into unclickable grey text marked "(withdrawn)".
Common questions
Does cloning affect the original author?
No. What you get is an independent copy. Nothing you change has anything to do with them, and they cannot see what you changed.
If the original author deletes their project, is mine still there?
Yes. Your copy is completely independent — and deleting a project does not take down what they published. As long as that template is still public, the release page still opens and the "Cloned from XXX" line at the top of the Main pane is still a link you can click. If the author switches it to private first and then deletes the project (which is the take-down order these docs recommend), that record turns into unclickable grey text; only "Withdraw the whole template" additionally marks it "(withdrawn)".
Can I publish it again after cloning it?
Yes. What you publish is your own copy. How to publish →
What can I do with a public project without signing in?
You can read the whole release page and download the firmware. Cloning requires signing in, because a clone creates a project under your account.