firmware: zero-copy StoredMap/CountingPattern envelopes + RAM tooling (lifted from #45)

[fughilli]

Lifts the still-useful, not-yet-on-main pieces of #45 (FUG-71 device heap pressure) into a clean PR off current main, reconciled with the code as it has since moved. #45 is being closed as partially superseded.

Lifted from #45

Zero-copy protocol envelopes

The by-value micropb decode + reply build in lm_player_handle puts these structs on the heap-allocated loop/httpd task stacks, so shrinking them is heap FUG-71 wants back.

• handle_get_stored_map — encodes the StoredMapChunk reply zero-copy straight into the output buffer instead of materializing a by-value pb::StoredMapChunk (a 1 KiB inline Vec); the request is hand-decoded too. The firmware profile stubs StoredMapChunk.data to 8 B (gen_main.rs); host keeps the full 1 KiB for the generated encoder / conformance.
• handle_set_counting_pattern — walks the repeated ColorBlock array (32 × f64-rgb — the fat arm of ClientMessage) zero-copy into pre-reduced 8-bit blocks and installs them via a new shared Player::set_counting_blocks path. The firmware profile stubs SetCountingPattern.blocks to 1; host keeps 32. Reconciliation: main grew a color_order field on this message since FUG-71: solve device heap pressure (release BLE + zero-copy envelopes + RAM tooling) #45, so the walker also parses/forwards it and the by-value host path was refactored (not just replaced) to keep behavior identical.
• envelope_size_test — a size-regression guard on the shrunk structs.

RAM tooling

• tools/ram_chart.bzl — a .ram_chart bazel run sibling for firmware_binary that charts static SRAM per symbol/component (backed by fw_memaudit.py, wired onto esp32c6_netstack).
• fw_memaudit.py --compare — diff a --json snapshot to track a reclaim per-symbol (the fw_memaudit core, --json, and addr2line were already on main; only --compare is new here).
• docs/design/ram-budget.md — the RAM-budget + tooling writeup.

Deliberately NOT lifted (superseded)

The BLE-release / Bluedroid-lifecycle half of #45 (improv_ble.cpp/.h, main.cpp) is obsolete: main has since replaced Bluedroid entirely with the heapless BLE host (//firmware/blehost:ble_ffi), which removes that permanent BLE heap draw structurally rather than tearing a stack down at runtime.

Reconciliation notes vs #45's original assumptions

• On current main the ServerMessage oneof is dominated by the newer HardwareConfigState arm (~4 KiB board-capabilities catalog — 31 GPIO pins × 64-B note strings + LED modes, full-size in both profiles), not by StoredMapChunk. So the size guard asserts on the StoredMapChunk / SetCountingPattern structs directly rather than on the whole envelope (which a StoredMapChunk regression could no longer move).
• The loop/httpd_ssl task-stack-size retune that FUG-71: solve device heap pressure (release BLE + zero-copy envelopes + RAM tooling) #45 did in main.cpp is not included here — main.cpp is on the abandoned (heapless-host) path; the stack retune is a clean follow-up once these frames are small.

Verification

• envelope_size_test, ffi_test, counting_preempt_test, and firmware/player session_test / arena_upload_test / phone_client_frames_test all pass.
• fw_memaudit.py --compare exercised on synthetic snapshots; black / buildifier clean.
• bazel query resolves the new ram_chart target and its ELF filegroup.
• Heavy firmware-profile link (esp32c6_netstack) is left to CI, per repo convention. The zero-copy code hand-walks bytes so it is profile-agnostic; the host ffi_test compiles the same ffi.rs.

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-04 18:27 UTC