Feat/esp boards part 1 env naming - #37
Merged
Merged
Conversation
Part 1, Step 1 of ESP-BOARDS-PART-1-PLAN.md - renames the three board envs (and their _ota transports) off the module/chip-family mix (esp32_wroom/esp32_c3/esp32_s3) onto one consistent axis: chip family + flash/PSRAM. No firmware behaviour change. - Rename esp32_wroom -> esp32_n4, esp32_c3 -> esp32c3_n4, esp32_s3 -> esp32s3_n4r2 (plus their _ota variants) in platformio.ini - Update default_envs to esp32_n4 - Update the CI build matrix in ci-build.yml to the new names - Document the naming rule (esp32[<chip-suffix>]_n<flashMB>[r<psramMB>][_ota]) in a comment block above the env sections - Update the manual build/upload commands in plans/info/TCA9548A_SCANNER.md - Verified: all three envs build clean; the only difference between pre- and post-rename firmware.bin is the embedded FIRMWARE_VERSION string (git-describe dirty flag) - no build flag was perturbed by the rename; old env names now fail with "Unknown environment" Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Part 1, Step 2 of ESP-BOARDS-PART-1-PLAN.md - collapses the board metadata previously duplicated across generate_manifest.py, render_release_notes.py, and release.yml (three separately-maintained lists that had already drifted once) into a single build/boards.json, and adds a CI guard against future drift. - Add build/boards.json: one entry per board (env, label, flash, psram, chipFamily, chip, bootloaderOffset, littlefsOffset, released) - generate_manifest.py and render_release_notes.py now load boards.json and filter on released instead of carrying their own hardcoded board lists; render_release_notes.py's "Boards supported" section is now generated from the same data instead of separately hardcoded prose - Rename the three release.yml matrix entries to match platformio.ini - Add build/scripts/check_boards_sync.py: fails CI if platformio.ini's env sections, ci-build.yml's matrix, release.yml's matrix, and boards.json ever disagree, and asserts every env name matches the esp32[<chip>]_n<MB>[r<MB>][_ota] naming rule; wired into ci-build.yml as a fast pre-build job - Verified generate_manifest.py/render_release_notes.py output against the new metadata, and check_boards_sync.py catches a deliberately misspelled entry in both ci-build.yml and release.yml Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Part 1, Step 3 of ESP-BOARDS-PART-1-PLAN.md - carries the renamed envs and their display labels through every user-facing page on the docs site (docs/, deployed to GitHub Pages). - docs/firmware/index.md: rebuild the supported-boards table with the new env names/labels, and correct the dual-display claim - the S3 has the same dual-I2C hardware, that build just hasn't been made yet - docs/firmware/install-manual.md: state that `npm run build` targets whatever `default_envs` names instead of hardcoding an env name (the previous wording had already gone stale once); update -e examples and the OTA env example to the new names - docs/faq.md: update the OTA env example - docs/firmware/install-web-flasher.md: replace "(WROOM, C3, or S3)" and the "WROOM / C3" tab label with the new board labels - docs/firmware/install-troubleshooting.md: drop the banned "ESP32-S3 minis" phrasing for the real label (SuperMini / S3-Zero) - docs/build/dual-display/bom.md: relabel the ESP32 DevKit line item and swap its a.co short link for a stable Amazon ASIN URL - docs/build/dual-display/power.md, docs/module-boards/custom-pcb/index.md: fix a content bug where a USB-current warning was keyed to chip family (ESP32-C3, ESP32-S3) instead of being stated unconditionally - the 44-pin S3 isn't a small board, so the old wording would have wrongly exempted it once Part 2 lands Verified: `mkdocs build --strict` passes clean; no old env name or banned "S3 mini"/"C3 mini" phrasing remains anywhere under docs/. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Part 1, Step 4 (final step) of ESP-BOARDS-PART-1-PLAN.md - gives the README a self-contained answer to "which chip, which board, which env", and brings the sibling plan docs onto the renamed tree. - README: add the hardware bar, the 15-part Espressif SoC lineup table (sourced live from espressif.com/en/products/socs), and the boards-this-project-has-been-built-on table with its two companion explainers (chip/module/board layers; flash vs PSRAM). Also fixes the "(WROOM, C3, or S3)" board-detection line to the new labels. - Fixed one factual error found while spot-checking the SoC table against Espressif's own site: ESP32-E22's max clock was listed as unknown but is actually 500 MHz (confirmed as a dual-core RISC-V radio co-processor with no native USB, needing a host MCU) - docs/firmware/index.md: cross-link the new README tables instead of duplicating them - plans/ESP-INFO.md: rename all env references to the Part 1 scheme; board #6's env cell now reads "none - see Part 2" instead of a removed env name; mark boards #3/#4 as never purchased and flag the #4 pin-count figure as unverifiable rather than merely suspect; correct the now-fixed dual-display doc quote - plans/DISTRIBUTED-PLAN.md, plans/RELEASE-AUTOMATION-PLAN.md: add a one-line note pointing at the rename, since both are pre-rename narrative (one not-yet-started, one already-shipped history) rather than live specs worth rewriting inline - ESP-BOARDS-PART-2-PLAN.md needed no changes - confirmed it was already authored entirely against the post-rename env names and the boards.json littlefsOffset/released mechanism Verified: all Amazon ASIN links resolve; mkdocs build --strict passes; the plan's own grep gate now matches only inside plans/ narrative across the whole repo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Keeps the root README focused on introducing the project instead of carrying a full ESP32 chip/board reference. The content moves to a new Supported Hardware page under the Firmware tab, since it's board- selection material that firmware/index.md's existing Supported boards table already points readers toward. - Add docs/firmware/hardware.md: the SoC lineup table, boards-built-on table, and both explainer callouts, moved verbatim from README's Hardware section (drops the dead plans/ link, which pointed at a gitignored file never published to GitHub) - mkdocs.yml: add the new page to the Firmware nav, right after the overview and before the install pages - docs/firmware/index.md: cross-link to the new in-site page instead of a GitHub README anchor; list it under Sections - README.md: drop the Hardware section, add one Features bullet pointing at the new page - docs/build/index.md: add a "Supported ESP32 boards" row to the build-comparison table — Original runs on all three chips, Dual is ESP32-only today since it's the only env with ENABLE_DUAL_I2C set Verified: mkdocs build --strict passes (aside from the expected git-history warning on the new, not-yet-committed page); no stray references to the old README anchor remain. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- docs/build/dual-display/power.md, docs/module-boards/custom-pcb/index.md: the "don't power through USB" warning was overstated — a few modules at a time over USB is fine on any board. Reworded to scope the real risk (a full chain) and call out that the smaller ESP32-C3/S3 boards have less current headroom and are more likely to actually be damaged - docs/firmware/hardware.md: shrank the SoC table from all 15 Espressif parts down to the three chip families this project actually uses; dropped "Meets the bar?", added I²C buses / Original support / Dual support columns. Added a "Naming convention" section explaining the esp32[<chip>]_n<MB>[r<MB>][_ota] pattern and why it's chip+memory instead of a brand name - Corrected the S3 dual-mode footnote (here and in docs/build/index.md): the earlier claim that the S3 SuperMini/Zero lack enough GPIOs for a second I²C bus was never actually verified — the real reason dual mode isn't planned for those boards is that they've tested less reliable and slower than the ESP32. The upcoming 44-pin S3 board is a different design and will get dual support instead - plans/ESP-INFO.md: corrected the same unverified pin-count guess at its source, so it doesn't reseed the wrong claim later - platformio.ini: the naming-rule comment pointed at plans/ESP-BOARDS-PART-1-PLAN.md, which is gitignored and was never published — repointed it at the new hardware page's Naming convention section on the GH Pages site instead Verified: mkdocs build clean (aside from the expected git-history warning on pages committed for the first time). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
DrewFerg11
marked this pull request as ready for review
August 8, 2026 16:14
![drewferg11-hermes-bot[bot]](https://avatars.githubusercontent.com/in/4490462?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review: Feat/esp boards part 1 — env naming
This is a clean refactor: it replaces opaque board-brand env names (esp32_wroom, esp32_c3, esp32_s3) with chip + memory names (esp32_n4, esp32c3_n4, esp32s3_n4r2), introduces build/boards.json as a single metadata source, adds a CI guard (check_boards_sync.py) to keep the four sources of truth in sync, and threads the new names through every doc, workflow, and script. I checked every file the PR touches plus the ones it doesn't (check_app_size.py, inject_version.py, gzip_littlefs.py, package.json) and a repo-wide code search for the old names — no stale references survive. The naming convention doc (hardware.md) is well-written and accurately describes the build model.
The env names are the source of truth in platformio.ini, and the four-way sync (platformio.ini ↔ ci-build.yml ↔ release.yml ↔ boards.json) is correctly wired in check_boards_sync.py — build envs vs CI, build envs vs all boards, release vs released boards, naming rule on all PIO envs. No correctness or security issues found.
I left three inline comments, none of them merge-blocking in my view:
-
README auto-detect wording — the new copy says the flasher detects specific carrier boards ("ESP32 DevKit", "ESP32-C3 SuperMini / C3-Zero"). The manifest it consumes keys off
chipFamily, and I don't see board-level detection changing in this PR, so this may be claiming more than the code delivers. Worth confirming the flasher actually detects by carrier, or softening to chip-family level. -
check_boards_sync.pysubset gap — the script never assertsboards_released ⊆ boards_all. A typo'denvname in areleased: truerow could matchrelease.yml(same typo) and pass the sync check while referencing a non-existent env — exactly the drift class this guard exists to prevent. One extraissubsetassertion closes it. -
littlefsOffsetis dead metadata — every board carries0x310000but nothing reads it;release.ymlhardcodes the offset instead. Either wire it up (make it authoritative) or drop the field so it can't silently drift.
I'm leaving this as Comment rather than requesting changes: all three are improvements to a change that's already correct and safe to merge, and #1 is a question rather than a definite bug. I'd happily merge this after the comments are addressed, and I'd also happily merge it as-is if you decide to handle them in a follow-up.
How to respond to my comments — react on any comment above:
| React | What I do |
|---|---|
| 👍 | Implement it and push to this PR |
| 👎 | Drop the suggestion permanently |
| 😕 | Explain it in more detail (no code change) |
| 👀 | Investigate whether it is really a problem (no code change) |
Reply in the thread before reacting and I will follow my reply over my original suggestion.
DrewFerg11
added a commit
that referenced
this pull request
Aug 8, 2026
fix: scope flasher copy to chip detection, catch matrix chip/offset drift Addresses review feedback on #37. The web flasher (ESP Web Tools) matches on chipFamily read off the silicon, not on board name - there is no carrier-board detection anywhere. The install copy in both README.md and install-web-flasher.md claimed board-level detection, which overstated it and left owners of other C3/S3 carriers unsure whether they were supported. Both now say "which chip you have (ESP32, ESP32-C3, or ESP32-S3)"; the flasher page adds that any carrier on those chips works. The specific board names stay in the supported-hardware table, where they are accurate. check_boards_sync.py now also compares the chip and bootloader_offset that release.yml duplicates from boards.json. Unlike the env names these differ per chip (0x1000 on ESP32, 0x0 on C3/S3) and nothing else caught a mismatch - the merged factory image would carry the bootloader at the wrong offset and the board would not boot. The release matrix is now parsed into full entries rather than grepped for env names, so the check does not depend on key ordering, and offsets compare numerically so 0x0 vs 0x00 is not a false failure. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> @
…rift Addresses review feedback on #37. The web flasher (ESP Web Tools) matches on chipFamily read off the silicon, not on board name - there is no carrier-board detection anywhere. The install copy in both README.md and install-web-flasher.md claimed board-level detection, which overstated it and left owners of other C3/S3 carriers unsure whether they were supported. Both now say "which chip you have (ESP32, ESP32-C3, or ESP32-S3)"; the flasher page adds that any carrier on those chips works. The specific board names stay in the supported-hardware table, where they are accurate. check_boards_sync.py now also compares the chip and bootloader_offset that release.yml duplicates from boards.json. Unlike the env names these differ per chip (0x1000 on ESP32, 0x0 on C3/S3) and nothing else caught a mismatch - the merged factory image would carry the bootloader at the wrong offset and the board would not boot. The release matrix is now parsed into full entries rather than grepped for env names, so the check does not depend on key ordering, and offsets compare numerically so 0x0 vs 0x00 is not a false failure. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
DrewFerg11
force-pushed
the
feat/esp-boards-part-1-env-naming
branch
from
August 8, 2026 16:53
f34de1e to
4b36520
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.