esp32/CLAUDE.md

Project notes for Claude

Project layout

src/main.rs                 firmware entrypoint, Wi-Fi + boot orchestration
src/ota.rs                  OTA poll loop, manifest fetch, blob streaming
src/sig.rs                  cosign Sigstore Bundle verification
src/trust.rs                NVS-loaded trust config (signer identities + Sigstore CAs)
src/cloud_log.rs            tracing → Cloud Logging (queue + sender thread)
src/metrics.rs              chip-health snapshots → Cloud Monitoring time series
src/gcp_auth.rs             multi-scope JWT mint, shared TokenProvider, ShortHttpsLock,
                            OtaDownloadGuard, HTTPS helpers
trust/                      Sigstore Fulcio root + intermediate certs (provisioned via NVS)
tools/publisher/            host-side tool that pushes signed OCI artifacts to GHCR
tools/provision/            host-side tool that builds + flashes NVS partition
.github/workflows/          ci.yml (PRs) + publish.yml (push to main)
Cargo.toml                  firmware deps
partitions.csv              OTA-capable partition table (1.94 MB app slots)
sdkconfig.defaults.in       ESP-IDF kconfig template (Makefile substitutes paths)
Makefile                    build / flash / monitor / provision / publish entrypoints
provisioning.toml.example   template for per-device NVS values
docs/setup.md               first-flash + day-to-day workflow + GCP setup
docs/ota.md                 full OTA + provisioning + signing system documentation
docs/observability.md       Cloud Logging + Monitoring design (current state)
docs/eink-plan.md           planned e-ink display work
README.md                   short top-level overview, links into docs/

Conventions established in this repo

• docs/ for descriptive docs and per-feature plans. Forward- looking work uses <feature>-plan.md; once shipped, the plan is rewritten in present tense and lives next to the other reference docs (e.g. logs-plan.md + monitoring-plan.md collapsed into docs/observability.md).
• Cargo.lock IS tracked for all three crates here — they're all binaries.
• Don't use "and" in Make target names — chain existing targets instead (make publish monitor, not make publish-and-monitor).
• Env-setup scripts (e.g. espup's export-esp.sh) live in the project dir, not ~.
• GHCR auth uses classic PATs with write:packages (fine-grained PATs don't expose a Packages permission for user-owned packages).
• Use make targets, not raw espflash/cargo commands. The Makefile sets toolchain env, the Python 3.12 shim, and (critically) always passes --partition-table partitions.csv to espflash flash — without that, espflash 4.x silently writes a default factory-only partition table over our OTA layout.

Architectural decisions worth knowing

• std Rust on top of ESP-IDF, not no_std with esp-hal. We need easy Wi-Fi + HTTP + TLS via esp-idf-svc, plus standard threading/heap. The cost is ESP-IDF's C SDK + CMake/Ninja/Python toolchain; the lighter no_std path is worth knowing for future projects.
• Pure-Rust rsa crate for JWT signing, not mbedtls FFI. Adds ~50 KB but keeps the code in safe Rust.
• mbedtls heap is tight. With cloud_log + metrics + OTA each potentially holding a TLS session, three concurrent handshakes (~25–35 KB each) blow our heap. Mitigations stacked in sdkconfig.defaults.in (MBEDTLS_DYNAMIC_BUFFER, free config/CA-cert, KEEP_PEER_CERTIFICATE=n) plus runtime serialization via gcp_auth::ShortHttpsLock and an OTA_DOWNLOAD_IN_PROGRESS gate. See docs/observability.md for the full chain.
• OTA download is not serialized. Multi-second blob downloads must not block per-5 s log flushes. cloud_log + metrics check OTA_DOWNLOAD_IN_PROGRESS and skip-but-don't-drain while a download is in flight; the queue absorbs and flushes after.

Gotchas to remember

• Custom partition table path resolution. ESP-IDF resolves CONFIG_PARTITION_TABLE_CUSTOM_FILENAME relative to its top-level CMake project, which for embuild is target/.../esp-idf-sys-<hash>/out/, not the repo root. Workaround: sdkconfig.defaults.in is the template (committed), with the placeholder @PROJECT_DIR@/partitions.csv; the Makefile substitutes the absolute path at build time and writes the resolved sdkconfig.defaults (gitignored). Don't "fix" the placeholder.
• Python 3.12 shim. embuild grabs whatever python3 is first on PATH. macOS's default is 3.9.6, which silently breaks ESP-IDF dependency resolution. The Makefile creates .embuild/python-shim/python3 → uv-managed 3.12 and prepends it to PATH. If a dep-check error appears after a fresh clone: rm -rf .embuild && make build.
• No user LED on this board. Inland ESP-WROOM-32 has only a power LED; the DOIT/DEVKITC blue LED on GPIO 2 is not populated. Don't suggest GPIO blink demos — use serial logging via make monitor instead.
• NVS key names cap at 15 characters. When adding new keys to tools/provision/, abbreviate (metric_intvl, not metrics_interval). The .toml field can be long and readable; the NVS key is the constrained one.
• make flash after a fresh make bootstrap can boot the wrong partition: bootstrap clears otadata so the bootloader picks ota_0, but a subsequent OTA download installs to ota_1 and otadata starts pointing there. A bare make flash writes to ota_0 (the first app partition in the table) but the device will keep booting ota_1 until you make bootstrap again or wait for OTA promotion.