How esp-atlas works

There is more ESP32 information than any of us can read. New boards, new firmware, new recipes appear every week across a hundred repos, forums, and vendor pages — and most guides are one person's blog, frozen the day it was published. esp-atlas is an attempt to keep up, honestly. A small agent watches those sources every day and proposes what changed as a pull request with a cited source; automated checks must pass, and the riskier changes wait for a human maintainer; nothing lands without a source. The result is a public map of the ESP32 family — which chip or board to buy and why, and firmware recipes that show their source and trust level — that you can query, and that anyone can correct with a pull request. We won't have everything. We'd rather say ‘not verified’ than guess.

Why

The ESP32 family is enormous and moving fast: dozens of chips, hundreds of boards, thousands of firmware projects and forum threads. In the AI age there is no shortage of information — the shortage is trust. Specs get copy-pasted wrong, recipes rot when firmware updates, and every guide freezes at its publish date.

What esp-atlas is

A shared, public knowledge base that answers ‘which ESP should I buy for X, and why?’ and hands you a firmware or wiring recipe with its source and trust level shown. Every hard spec cites an official source. The data is plain markdown in a git repo, so a wrong number is a bug and a missing board is one PR away.

How it stays alive — meet EspAtlas Jr. 🤖

Nobody can curate this by hand, so we don't pretend to. EspAtlas Jr., our autonomous data-maintainer, runs every day: it checks that sources are still alive, watches firmware releases, notices when a recipe has drifted, and discovers new boards and projects from official catalogs and community signal. It never writes to main, and every change is a pull request with a cited source. The checks happen in three separate places. Jr checks a project's ESP-target evidence before it proposes a new firmware; a project that fails is never proposed. On every pull request, CI validates the schema and the data, runs the tests, and re-checks that each newly added firmware repository is still eligible (public, not a fork, not archived, above the popularity floor) — it does not rerun Jr's evidence check. Higher-risk proposals — new firmware entries, board–firmware compatibility recipes, and flashing, download-mode or USB claims — are held for a human maintainer to review before they publish; low-risk updates (stars, dates, source signals) publish automatically once CI passes. A recipe marked known good carries a cited source for that exact board — usually the firmware project listing it — not proof that someone flashed it, unless its notes record a hardware test. Auto-harvested recipes land marked declared or unverified, and some unverified recipes are only discovery leads — a third-party listing with no upstream board target or artifact behind it — whose notes say so. Staleness is shown, not hidden.

Adding a firmware

Paste the repository at /submit (or open a submission issue on GitHub). EspAtlas Jr scores it with the catalog's fixed rules — 25 stars or 25 forks, a real public repo, not a fork, not already listed, a catalogued board named, and build files showing it targets an ESP chip — comments the verdict on the issue, and, if it passes, opens a cited pull request. No login, no account, nothing decided by a model.

What we promise, and what we don't

We promise every stated spec has a source, every recipe shows its trust level, and every mistake can be fixed by anyone. We don't promise completeness or perfection — the atlas is only as good as its last daily run and its last reviewer. If the data can't support an answer, it says so.

Fix it, extend it, argue with it. It's yours as much as ours.