fix: correct firmware footprint to measured 27.6 KB flash / 0.6 KB RAM

The "~14 KB" DCP-layer footprint claimed across the README, paper,
firmware docs, and figures was never backed by a reproducible
measurement — the README even referenced a measurement script that
did not exist. This commit measures it properly and corrects every
public claim.

New: docs/paper/figures/measure_footprint.py compiles a baseline
empty Arduino sketch and the lamp example with the same FQBN and
differences them. Result, written to footprint_data.json:

  baseline empty sketch : 266,740 B flash / 22,068 B globals
  lamp example (w/ DCP) : 295,007 B flash / 22,712 B globals
  DCP layer delta       :  28,267 B flash /    644 B globals
                        =  27.6 KB flash  /   0.6 KB RAM

So the DCP layer is 27.6 KB of flash, not ~14 KB. The "~14 KB" was an
optimistic pre-measurement estimate, most likely from before the
on-device HMAC-SHA256 path (DCPCrypto) was added. The flash figure is
above the original <16 KB design target; the target predates on-device
crypto and is not met. Reported honestly as such.

The RAM figure is the good news: 0.6 KB. That is the number worth
leading with — RAM is the scarce resource on an MCU, and for context
IoT-MCP reports 74 KB peak memory.

Corrected across:
- README.md: intro tagline, "Validated on real hardware" section,
  footprint figure caption
- docs/paper/main.tex: abstract, footprint paragraph, fig:footprint
  text + caption, and the IoT-MCP comparison (was "roughly 1/5 the
  memory" — now the measured 0.6 KB vs 74 KB)
- docs/RATIONALE.md, firmware/esp32/README.md, firmware/esp32/src/DCP.cpp
  comment, docs/QUICKSTART_VIDEO.md, .github/RELEASE_NOTES_v0.3.0.md
- CHANGELOG.md: new Fixed entry; dropped an unverified "~1 KB of code"
  claim for DCPCrypto
- figures/README.md: footprint marked measured

fig_footprint() rewritten: was a 4-protocol synthetic flash+RAM matrix
with the DCP bar hatched as "target". Now an honest 2-bar static-RAM
comparison — DCP's measured 0.6 KB vs IoT-MCP's reported 74 KB peak
memory, the one RAM-vs-RAM axis the two projects can be compared on.
Flash is stated in text, not plotted: IoT-MCP reports no flash figure.

arch diagram device label "< 16 KB MCU" -> "commodity MCU".
social_preview hero stat "<16 KB firmware" -> "<1 KB of RAM".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: WaylandYang

.github/RELEASE_NOTES_v0.3.0.md

@@ -14,7 +14,8 @@ future work (see `docs/RATIONALE.md §7` and `docs/paper/main.tex §7`).
 - **10 / 10** round-trip tests pass against ESP32-WROOM-32 (CH340, 115 200 baud)
 - **Frame size:** 19 bytes for a typical `set_brightness(50)` call;
   35 bytes with the optional HMAC tail
-- **Firmware footprint:** ~14 KB of pure DCP over an empty Arduino sketch
+- **Firmware footprint:** the DCP layer measures 27.6 KB flash and
+  0.6 KB RAM over an empty Arduino sketch (measured)
 - **Five transports** ship: loopback, UART (COBS + CRC-16), MQTT,
   BLE GATT, in-process simulator. Plus the MCP server wrapper that
   surfaces every intent to any MCP host

CHANGELOG.md

@@ -14,7 +14,7 @@ it reaches 1.0. Pre-1.0 releases may break compatibility.
   optional 16-byte truncated signature appended to every frame. Both Bridge
   and device must agree; no in-band downgrade marker by design.
 - **Self-contained SHA-256 + HMAC-SHA256** in the ESP32 firmware
-  (`DCPCrypto.h`/`.cpp`) — no mbedtls/ESP-IDF dependency, ~1 KB of code.
+  (`DCPCrypto.h`/`.cpp`) — no mbedtls/ESP-IDF dependency.
 - **DCPBle**: ESP32 BLE peripheral via NimBLE-Arduino. Same intent table as
   `DCP`; one service, c2d/d2c characteristics derived from service UUID by
   convention (`0xC1` / `0xD1` last byte).
@@ -28,6 +28,21 @@ it reaches 1.0. Pre-1.0 releases may break compatibility.
 
 - `Bridge` constructor takes `wire_secret=` for per-frame signing.
 
+### Fixed
+
+- **Footprint numbers corrected to measured values.** Earlier docs
+  claimed the DCP layer was "~14 KB" of flash and cited a `<16 KB`
+  design target. A reproducible measurement
+  (`docs/paper/figures/measure_footprint.py`, differencing the lamp
+  example against an empty Arduino sketch) shows the DCP layer is
+  **27.6 KB of flash and 0.6 KB of RAM** on ESP32. The flash figure is
+  above the original `<16 KB` target — the target predated the
+  on-device HMAC-SHA256 path — and is now reported as measured across
+  the README, paper, and firmware docs. The RAM figure (0.6 KB) came in
+  well under target.
+- **Latency figure is now measured**, not illustrative
+  (`tools/bench_latency.py`, 1000 round-trips per transport).
+
 ## [0.2.0] - 2026-05-12
 
 ### Added

README.md

@@ -10,7 +10,8 @@
 > down to dollar-class microcontrollers.
 >
 > Intent-level, transport-agnostic, capability-scoped. Compact wire format
-> (sub-50-byte frames). Self-contained firmware under 16 KB.
+> (sub-50-byte frames). Self-contained firmware: under 1 KB of RAM,
+> ~28 KB of flash.
 >
 > Complementary to [MCP](https://modelcontextprotocol.io) — a reference
 > Bridge translates DCP ↔ MCP so any MCP host (Claude Desktop, Claude Code,
@@ -80,19 +81,23 @@ and an ESP32-S3 (LILYGO T-Panel S3) over the S3's native USB-Serial/JTAG
 
 - 13/13 round-trip tests pass on each board (`tools/test_uart_roundtrip.py`)
 - 88/88 Python unit & conformance tests pass
-- Compiled firmware: 294 KB flash, 22.7 KB globals on WROOM-32;
-  322 KB / 22.7 KB on the S3 (Arduino-ESP32 core 3.3.8)
-- The pure DCP layer is approximately 14 KB over a baseline empty
-  sketch (measurement script in `docs/paper/figures/`)
+- Full lamp firmware: 295 KB flash, 22.7 KB globals on WROOM-32 — most
+  of which is the Arduino-ESP32 runtime + FreeRTOS, not DCP
+- **The DCP layer itself measures 27.6 KB of flash and 0.6 KB of RAM**
+  over a baseline empty sketch — reproduce with
+  `docs/paper/figures/measure_footprint.py`. The flash figure is over
+  the original `<16 KB` design target (set before on-device HMAC was
+  added); the RAM figure is well under it.
 - The S3 run also exercises DCP over a native-USB CDC link rather
   than a USB-UART bridge chip — same firmware, no transport-specific
   code
 
-![Memory footprint: DCP target vs IoT-MCP measured vs Direct MCP vs Matter](docs/paper/figures/footprint.png)
+![Static RAM footprint: measured DCP layer vs IoT-MCP reported peak memory](docs/paper/figures/footprint.png)
 
-*DCP design target sits roughly 5× under IoT-MCP and 20× under Matter on
-the same class of MCU. Hatched bars are design targets, plain bars are
-measured / typical of the cited sources.*
+*Static RAM is the scarce resource on an MCU. The DCP layer's measured
+0.6 KB of RAM sits two orders of magnitude under IoT-MCP's reported
+74 KB peak memory. DCP's flash cost (27.6 KB, measured) is not plotted
+— IoT-MCP does not report a comparable flash figure.*
 
 See [docs/RATIONALE.md §7](docs/RATIONALE.md) for what the hardware
 validation does and does not prove.

docs/QUICKSTART_VIDEO.md

@@ -100,8 +100,8 @@ dcp::Status handle_set_brightness(uint8_t kind, dcp::CborReader& p, ...) {
 }
 ```
 
-> "And the device side is plain C++. CBOR map in, action out. Under 16 KB
-> of flash on a $5 ESP32."
+> "And the device side is plain C++. CBOR map in, action out. The DCP
+> layer is 27.6 KB of flash and under 1 KB of RAM on a $5 ESP32."
 
 ## Live demo (2:10 – 3:30)
 

docs/RATIONALE.md

@@ -36,9 +36,12 @@ out of the box.
 
 The decisive numbers are RAM and code size. A minimal MCP-over-WebSocket
 implementation on ESP32 lands around 80–120 KB of code and tens of KB of
-working RAM. DCP's reference firmware targets <16 KB of flash and <2 KB of
-RAM. **That difference is the difference between every IoT device and only
-the expensive ones.**
+working RAM. DCP's reference firmware measures 27.6 KB of flash and
+0.6 KB of RAM (the DCP layer over a baseline empty sketch — the flash
+came in above the original <16 KB target once on-device HMAC was added;
+the RAM came in well under). **That RAM difference — under 1 KB versus
+tens of KB — is the difference between every IoT device and only the
+expensive ones.**
 
 ## Why not W3C Web of Things (WoT)?
 

docs/paper/figures/README.md

@@ -32,11 +32,13 @@ README / web preview) into this directory.
   `latency_data.json`, produced by `tools/bench_latency.py`: 1000 timed
   round-trips per transport, median + IQR. Currently covers loopback,
   ESP32-WROOM-32 (CH340), and ESP32-S3 (native USB).
-- **Fig. 3 (footprint)** — partially synthetic. The DCP bar is a design
-  target; the IoT-MCP / Direct-MCP / Matter bars are cited or typical.
-  Needs a rework: the DCP layer is now measured (~14 KB over an empty
-  sketch) and the figure should distinguish measured-DCP from cited
-  baselines cleanly, including the flash-vs-RAM axis.
+- **Fig. 3 (footprint)** — **measured.** `fig_footprint()` reads
+  `footprint_data.json`, produced by `measure_footprint.py`: the DCP
+  layer is 27.6 KB flash / 0.6 KB RAM over a baseline empty sketch. The
+  figure plots DCP's measured static RAM against IoT-MCP's reported
+  74 KB peak memory — the one apples-to-apples (RAM-vs-RAM) comparison
+  available. IoT-MCP does not report a flash figure, so flash is given
+  in text, not plotted.
 - **Fig. 4 (hallucination)** — synthetic, and labelled as such in the
   figure footnote. Making it real needs an LLM adversarial-call
   benchmark (≈1000 generated calls per baseline, with a defined