Publish your project
Once a project is finished, you can package it into a release page — one click and someone else can clone exactly the same thing. This page covers how to publish, what actually goes out, and the few things you have to go through yourself before making it public.
At a glance
| Prerequisite | You must have built working firmware first. A project that has never been built cannot be published; the button is greyed out |
|---|---|
| Where you publish from | "Publish" in the top bar only opens the release page editor. The buttons that actually publish are inside that editor: Publish privately and Publish publicly |
| How long packaging takes | 2–3 minutes (it recompiles) |
| How long the page copy takes | About 7 minutes; the page refreshes itself when it is done |
| What goes into the package | The full source, the hardware plan, the dependency list, the files you uploaded, and the built firmware |
| Who can see it once public | Anyone, including signed-out visitors. They can read the whole page, download the firmware, and download the individual files you annotated under "Key files"; the full source takes signing in and cloning |
| Can it be taken back | You can withdraw it, but copies that have already been downloaded cannot be taken back |
Two publish buttons
Publish at the far right of the top bar is not a publish action. Clicking it only opens the release page editor; nothing has been packaged yet. Publishing happens inside that editor, which has a "Publish privately" action and a "Publish publicly" action; which one you press decides whether the version ends up private or public.
| Publish privately | Packages the whole project into a version. The result is private — only you can see it. If you want it public later, use "Make public" in the same row |
|---|---|
| Publish publicly | Runs the same pipeline and then turns the version public at the end of it, with no second click from you. That version is visible to everyone and appears under "Public shares" |
Both buttons recompile the firmware from source, so the firmware and the source that go out are a matched pair. On a project that has never built successfully both buttons are greyed out, and hovering over one tells you why.
Publishing a version
- Confirm the project has built firmware ("Publish" in the top bar is lit).
- Click Publish to open the release page editor.
- Fill in the right-hand column first — images, attachment notes, purchase links and the publisher note. The public page shows the snapshot taken at publish time, so anything you change afterwards waits for the next version.
- Click Publish privately or Publish publicly.
- Wait 2–3 minutes. The pipeline runs four stages: Reserving and freezing → Rebuilding from source → Packaging and committing → Writing the bilingual page. If you chose Publish publicly, a fifth line follows: "Making it public".
Another 7 minutes or so for the page copy. Packaging itself is done in 2–3 minutes; the bilingual copy for the page takes about another 7. During that time the page says "The guide for this version is being generated", and it refreshes itself once that is finished. This step can fail: the line then changes to "The guide for this version has not been generated yet" and a Retry generation button appears next to it. Generation that has produced nothing 25 minutes after it started is treated as failed too.
What "Publish publicly" does
There is no second confirmation after you press "Publish publicly". The five notices the platform insists on — who can see it, checking for secrets yourself, the limits of withdrawing, the change of address, and attribution — stay pinned in the editor's publish row for as long as that version is public; when you instead turn an already-published private version public with the "Make public" button, they are also written out one by one in the publish activity, at the stage called "Before it goes public". They do not block publishing; you are the author, so the call is yours. Read them one by one anyway.
Once it is public:
- Anyone (including signed-out visitors) can see this version's hardware plan and feature notes, and download the firmware and the individual files you annotated; the full source takes signing in and cloning.
- It goes out under your name — the release page shows your name and your avatar.
- The address becomes a public link. Going private again invalidates the link other people already hold.
⚠️ Hard-coded configuration is printed on the public page, values and all.
Every setting the source scan finds is written into a "Field / Value / Location" table on the public page, together with its current literal value. That is deliberate — someone rebuilding the project has to see which line to change to their own. The price is this: a Wi-Fi password written in a #define appears in clear text on the public page itself — a visitor reads it without signing in and without downloading anything.
The scan also has blind spots, so it cannot prove your source is free of things that should not be public:
- It looks only at
main/andsrc/. Nothing incomponents/orlib/is visible to it. - Root config files such as
platformio.iniandsdkconfig.defaultsare parsed for dependencies only, never for secrets. - A source file larger than 512KB is skipped entirely — not one line of it is scanned.
Read through the source yourself before going public, especially for these: Wi-Fi names and passwords, tokens and API keys of any kind, internal network addresses, and your own account details.
The nine content slots in the editor
The release page editor splits the content into a fixed set of nine slots. The copy is generated by the platform, but every one of the nine sections has its own Add button and takes images, video or PDFs, and whatever you supply is used exactly as given. The numbers in the table below are the editor's numbers — the public page has different sections in a different order, and the order of its later sections can be rearranged.
| Slot | Content | What you do |
|---|---|---|
| 1 · Finished build / demo | What it looks like when it is built | Upload an image or a video |
| 2 · Overview | What the project is for | Copy is generated; you can add images |
| 3 · Flashing | Firmware download and flashing parameters | Copy is generated; you can add images |
| 4 · Clone this project | How someone else builds the same thing | Copy is generated; you can add images |
| 5 · Component photos | Which components to buy | Upload images |
| 6 · Diagram / sequence | How it works | Upload images |
| 7 · Wiring and assembly | How to wire it | Upload images |
| 8 · Verification / troubleshooting | What you verified, and what problems you ran into | Upload images |
| 9 · Reference & attachments | Schematics, datasheets | Upload PDFs, or pick project files and annotate them |
If slot 1 has no image, that section is empty once it goes public. And that is the first place someone's eye lands when they open the page. Put at least one photo of the finished build there — a picture of it actually running does more than any amount of text.
Adding images and video
You add them in the right-hand column of the release page editor. A few rules:
- It accepts png / jpg images, mp4 video and PDF. Images and PDFs are capped at 25MB each, video at 300MB; one release holds at most 20 items, of which at most 3 are video.
- Once uploaded they stay, and you do not lose them by not publishing.
- Changes to the media take effect at the next publish — the public page shows the snapshot taken when it was published.
- Pressing delete deletes the file immediately (an already-published version keeps showing it until a newer version replaces that one).
Video shot on an iPhone is rejected outright. An iPhone records HEVC by default, and the platform turns it away at the upload confirmation step, on the grounds that some visitors' browsers cannot play it. Go to Settings → Camera → Formats, choose "Most Compatible" and shoot it again — or share/export it once from Photos (exporting converts it to H.264) — then upload it.
The parts you write are used exactly as written
| Key files | Pick a few project files and add a note to each. Only files with a note are shown, and the note is displayed exactly as written |
|---|---|
| Purchase links | Add a buying address for the complete device or for one component. HTTPS links only. The platform is not part of the transaction and does not guarantee a link keeps working |
| Publisher note | Write what this version does, its limits, and what to watch out for. This is a first-hand statement, and it is written into the release guide as authoritative fact. Up to 2,000 characters |
The publisher note is worth writing properly. The generated copy only knows what is in the code. It does not know what you actually tested, under what conditions the readings go wrong, or which features are half-finished. Only you know that — and it is exactly what someone cloning the project needs most.
Change the page by saying it
Once the first version is published, the release page editor has a chat box. If you need the wording or the look adjusted, describe it:
Edits have a revision history, so if you do not like a change you can roll back to an earlier version.
Withdrawing
Be sure before you withdraw — this cannot be undone.
- Withdraw one version: visitors can no longer see that version, its heavy payload is cleared and its showcase media is reclaimed.
- Withdraw the whole template: none of its versions stay visible to anyone, and there is no way at all to bring it back.
- Both kinds of withdrawal only block access from that point on. Firmware already downloaded, and source already cloned, cannot be taken back.
And one people overlook: deleting a project is not the same as taking it down. Deleting a project does not withdraw its public release page, and once it is deleted you can never withdraw it again. To take it down, the order is: go back into the project and make it private first, then delete the project.
Three visibility states
| 🔒 Private | Only you can see it. What "Publish privately" produces |
|---|---|
| 🌐 Public | Visible to everyone; appears under "Public shares" |
| 🔗 Unlisted | Anyone holding the link can view it. Not available yet |
If you come from software development
Both publish buttons are close to cutting a release tag: they recompile from source rather than reusing the output of your most recent build — that way the firmware and the source package that go out are guaranteed to be a matched pair, and you never get a three-day-old binary next to today's source. The only difference between them is whether a visibility change follows the run.
"Make public" on its own is purely a visibility change; it does not rebuild. So you can package a version with "Publish privately", leave it, and decide days later whether to make it public.
There is source scanning, but it is a hint, not a gate. A deterministic scanner reads the frozen project and lists the constants in #defines whose names contain things like WIFI / SSID / PASS / KEY / TOKEN / SECRET / URL, together with the file name, the line number and the current literal value; the interface writes that up as "Source scanning found hard-coded configuration that may be exposed in the public bundle". It looks only at .c .cc .cpp .h .hpp .ino files under main/ and src/; the four root config files (CMakeLists.txt, idf_component.yml, platformio.ini, sdkconfig.defaults) are parsed for dependencies and never for secrets; any single file over 512KB is skipped whole; and nothing it finds will stop you from publishing. It also recognizes three runtime calls (WiFi.begin(), setenv("TZ", …), esp_sntp_setservername()), but anything more roundabout — credentials assembled from fragments, a key hidden in a resource file — it does not see at all.
One more thing worth knowing: "raises a warning" and "goes on the public page" are two different filters. The warnings listed when a version goes public cover only the credential, network and URL kinds, while every setting the scan found — TZ, LAT, LON, INTERVAL included — is rendered with its value into the configuration table on the public page. No warning does not mean not published.
Common questions
Why does publishing recompile?
To guarantee that the firmware and the source package that go out are a matched pair. Using the output of your most recent build directly could leave it out of step with the current source.
Can I keep working on the project after publishing?
Yes. What went out is a snapshot of one version; your project carries on as normal. To get new changes onto the release page, publish another version.
Can I see it when other people clone my project?
You can see how many times it has been cloned — the count is on the card and on the release page. You cannot see who.
Can other people use the published source commercially?
The release page has a "License" entry. That is between you and whoever clones it; the platform does not get involved.
What if I do not want it public and only want a backup for myself?
Use Publish privately. The version it produces is visible only to you; if you change your mind later, use "Make public" in the publish row.