example(lamp): add blink intent — non-idempotent + duration param coverage

The lamp manifest so far showed two intent shapes: idempotent write
with float/duration params (set_brightness, set_color) and read
(read_brightness). blink adds the third interesting shape:
non-idempotent write with a duration param that has to round-trip
through CBOR as a float. This makes the canonical example exercise
every code path in the bridge x firmware boundary worth testing.

Changes:
- examples/lamp_manifest.yaml: blink(times: int, period: duration ms)
  with idempotent: false and dry_run: true; ranges [1,20] and
  [50,2000]ms cap total real-time at 80s worst case
- firmware/esp32/examples/lamp/lamp.ino: handle_blink + binding,
  ~33 LOC. Saves/restores PWM duty so prior brightness survives the
  blink. Blocking implementation; the comment notes a real product
  would use a millis() state machine
- tools/test_uart_roundtrip.py: 3 blink cases folded into the
  existing suite — now 13/13 round-trips pass against ESP32-WROOM-32
- README.md, docs/paper/main.tex: 10/10 → 13/13
- docs/ADDING_FEATURES.md: trap report + sync example ranges with
  the shipped manifest. The trap: CBOR is type-strict, so a
  `duration` param (encoded as CBOR float on the wire) must be
  decoded with read_float() not read_int(); a mismatched read wedges
  the parser and the handler returns STATUS_DENIED for both dry-run
  and real calls. Worth documenting because the same symptom hits
  anyone porting a third-party handler that assumed numeric flexibility.

The Python Bridge, MCP server wrapper, and GenericSimulator all
required zero changes — the manifest is the single source of truth.
That's the load-bearing claim of the protocol, and it held up under
the add-an-intent test.

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

Author: WaylandYang

README.md

@@ -75,7 +75,7 @@ device boundary.
 As of v0.3 the reference firmware is **measured-validated on an
 ESP32-WROOM-32 dev board** over CH340 USB-Serial at 115 200 baud:
 
-- 10/10 round-trip tests pass (`tools/test_uart_roundtrip.py`)
+- 13/13 round-trip tests pass (`tools/test_uart_roundtrip.py`)
 - 88/88 Python unit & conformance tests pass
 - Compiled firmware: 294 KB flash, 22.7 KB globals (Arduino-ESP32 core 3.3.8)
 - The pure DCP layer is approximately 14 KB over a baseline empty
@@ -264,7 +264,7 @@ MIT.
 - [x] Conformance test suite (golden frames, language-neutral YAML)
 - [x] Codegen `--stubs`: emits handler signatures + binding table
 - [x] Quickstart video script ([docs/QUICKSTART_VIDEO.md](docs/QUICKSTART_VIDEO.md))
-- [x] Real-hardware UART validation (ESP32-WROOM-32, 10/10 round-trips)
+- [x] Real-hardware UART validation (ESP32-WROOM-32, 13/13 round-trips)
 - [x] Public repo at `device-context-protocol/dcp` (v0.3.0 released)
 - [x] PyPI release (`pip install pydcp`)
 - [ ] T-Panel S3 + CAN bus demo (firmware ready, awaiting hardware)

docs/ADDING_FEATURES.md

@@ -22,9 +22,9 @@ Edit `examples/lamp_manifest.yaml`. Append to `intents:`:
 ```yaml
 - name: blink
   params:
-    times:  { type: int,      range: [1, 100],   default: 3 }
+    times:  { type: int,      range: [1, 20],     default: 3 }
     period: { type: duration, unit: ms,
-              range: [50, 5000], default: 200 }
+              range: [50, 2000], default: 200 }
   capability: lamp.write
   idempotent: false       # calling twice blinks twice
   dry_run:    true        # the LLM can ask "what would this do?"
@@ -73,8 +73,8 @@ static dcp::Status handle_blink(uint8_t kind,
     // Belt-and-suspenders: re-check ranges. The Bridge already did this,
     // but defending here means a misbehaving Bridge can't drive the LED
     // outside the safe envelope.
-    if (times < 1   || times  > 100)  return dcp::STATUS_RANGE;
-    if (period < 50 || period > 5000) return dcp::STATUS_RANGE;
+    if (times < 1   || times  > 20)   return dcp::STATUS_RANGE;
+    if (period < 50 || period > 2000) return dcp::STATUS_RANGE;
 
     // Dry-run: report what we would do, no side effects.
     if (kind == dcp::KIND_DRY_RUN) {
@@ -233,12 +233,39 @@ The Bridge fans this out to any LLM session subscribed to `lamp.read`.
 | Symptom | Cause | Fix |
 |---|---|---|
 | `denied` with empty data from device | error reply buffer too small in firmware | bump the `uint8_t buf[N]` in your handler |
+| `denied` after Bridge says `ok` for the same call shape on dry-run | **CBOR type mismatch** — handler used `read_int` on a `duration`/`float` param; the reader wedges, next `next_key` returns false | use `read_float` for any param whose manifest type is `float` or `duration`; `read_int` only for `int`. See "CBOR is type-strict" note below |
 | `unknown_intent` for an intent you swore is in the manifest | spelling mismatch — `DCP_ID("foo")` vs manifest `name: Foo` | strings are byte-exact; rename one to match |
 | LLM keeps sending out-of-range values | you forgot `range:` in the manifest | add it; the Bridge picks it up after restart |
 | Long handler causes `busy` from the Bridge | `delay()` exceeded the Bridge timeout (default 2s) | shorten, or run async via FreeRTOS task and ack-then-event |
 | `set_color` works but no light changes | you don't have an RGB LED wired up | that's by design — the example saves state and flashes the brightness LED to acknowledge |
 | Capability check fails with `capability_required` | the LLM session's token doesn't include that capability | re-issue a token: `dcp token mint --caps lamp.write,lamp.read,...` |
 
+### CBOR is type-strict (the duration-as-float trap)
+
+CBOR distinguishes integer and float at the major-type level. A `42`
+and a `42.0` are **not** the same item. The Bridge encodes manifest
+parameter values like this:
+
+| manifest `type` | wire encoding |
+|---|---|
+| `int`, `bool` | CBOR int |
+| `string` | CBOR text string |
+| `float`, **`duration`** | **CBOR float (double)** |
+
+So a `duration` param like `period: { type: duration, unit: ms }`
+arrives on the device as a CBOR float, even if the caller wrote `200`
+(no decimal). Your firmware handler **must** decode it with
+`params.read_float(&period)`, not `params.read_int(&period)`. A
+mismatched read returns false and leaves the parser positioned wrong
+for the next field — the next `next_key()` call will then also fail,
+and the handler returns `STATUS_DENIED`.
+
+If you see "Bridge accepts the call (status is not `range` or
+`unknown_intent`) but the device returns `denied` for both dry-run
+and real calls, while a sibling intent with only `int`/`bool` params
+works fine," check this first. The fix is one word per affected
+param (`read_int` → `read_float`).
+
 ---
 
 ## What the loop doesn't ask you to touch

docs/paper/main.tex

@@ -462,9 +462,11 @@ \subsection{ESP32 reference firmware}
 expected to shed the bulk of the residual baseline.
 
 The Bridge $\leftrightarrow$ device path was end-to-end validated against
-ten round-trip cases (\texttt{tools/test\_uart\_roundtrip.py}) covering
-calls, reads, dry-run, range rejection, and unknown-intent error frames.
-All ten cases pass against real hardware.
+thirteen round-trip cases (\texttt{tools/test\_uart\_roundtrip.py}) covering
+calls, reads, dry-run, range rejection, unknown-intent error frames, and a
+non-idempotent intent with a \texttt{duration} parameter that exercises
+the firmware-side CBOR float decode path. All thirteen cases pass against
+real hardware.
 
 \subsection{Conformance suite}
 

examples/lamp_manifest.yaml

@@ -26,6 +26,14 @@ intents:
     returns: { type: float, unit: percent }
     capability: lamp.read
 
+  - name: blink
+    params:
+      times:  { type: int,      range: [1, 20],     default: 3 }
+      period: { type: duration, unit: ms, range: [50, 2000], default: 200 }
+    capability: lamp.write
+    idempotent: false     # blink(3) twice = 6 blinks, not 3
+    dry_run: true
+
 events:
   - name: motion_detected
     payload:

firmware/esp32/examples/lamp/lamp.ino

@@ -92,12 +92,51 @@ static dcp::Status handle_set_color(uint8_t kind,
     return dcp::STATUS_OK;
 }
 
+// Blink the built-in LED `times` times, each cycle = `period`ms on + `period`ms off.
+// Note: blocking implementation — the main loop can't service DCP frames during
+// the blink. Manifest range caps total time at 20 * 2000 * 2 = 80s worst case;
+// a real product would use a millis()-based state machine instead.
+static dcp::Status handle_blink(uint8_t kind,
+                                dcp::CborReader& params,
+                                dcp::CborMap& reply,
+                                void* /*user*/) {
+    int64_t times = 3;
+    double  period_ms = 200.0;     // duration is encoded as CBOR float on the wire
+    while (params.remaining() > 0) {
+        const char* key = nullptr;
+        size_t key_len = 0;
+        if (!params.next_key(&key, &key_len)) return dcp::STATUS_DENIED;
+        if      (key_len == 5 && memcmp(key, "times",  5) == 0) { if (!params.read_int(&times))       return dcp::STATUS_RANGE; }
+        else if (key_len == 6 && memcmp(key, "period", 6) == 0) { if (!params.read_float(&period_ms)) return dcp::STATUS_RANGE; }
+        else                                                    { params.skip(); }
+    }
+    if (times < 1 || times > 20)              return dcp::STATUS_RANGE;
+    if (period_ms < 50.0 || period_ms > 2000.0) return dcp::STATUS_RANGE;
+
+    uint32_t period = (uint32_t)period_ms;
+    if (kind == dcp::KIND_DRY_RUN) {
+        reply.add_int("would_blink_times",  times);
+        reply.add_int("would_blink_period", (int64_t)period);
+        return dcp::STATUS_OK;
+    }
+
+    // Save current brightness so we can restore it after the blink.
+    uint32_t saved = (uint32_t)(g_brightness * 2.55f);
+    for (int64_t i = 0; i < times; ++i) {
+        ledcWrite(LED_PIN, 255);        delay(period);
+        ledcWrite(LED_PIN, 0);          delay(period);
+    }
+    ledcWrite(LED_PIN, saved);
+    return dcp::STATUS_OK;
+}
+
 // Intent IDs are resolved at compile time via DCP_ID().
 // Keep these strings in sync with examples/lamp_manifest.yaml.
 static dcp::IntentBinding bindings[] = {
     { DCP_ID("set_brightness"),  handle_set_brightness,  nullptr },
     { DCP_ID("set_color"),       handle_set_color,       nullptr },
     { DCP_ID("read_brightness"), handle_read_brightness, nullptr },
+    { DCP_ID("blink"),           handle_blink,           nullptr },
 };
 
 static dcp::DCP* dcp_instance = nullptr;

tools/test_uart_roundtrip.py

@@ -9,6 +9,8 @@
 - dry-run (predicted, no side effect)
 - out-of-range (Bridge-rejected)
 - unknown intent (device-rejected with error frame)
+- non-idempotent intent with duration param (blink) — exercises
+  the firmware-side CBOR float decode path
 """
 from __future__ import annotations
 
@@ -60,6 +62,9 @@ async def main(port: str) -> int:
         ("dry-run set_color cyan",      "set_color",      {"r": 0, "g": 255, "b": 255}, True,  "ok"),
         ("set_color out-of-range",      "set_color",      {"r": 999, "g": 0, "b": 0},   False, "range"),
         ("turn_into_pumpkin (unknown)", "turn_into_pumpkin", None,                    False, "unknown_intent"),
+        ("dry-run blink(5, 150)",       "blink",          {"times": 5, "period": 150},  True,  "ok"),
+        ("blink(3, 150) real",          "blink",          {"times": 3, "period": 150},  False, "ok"),
+        ("blink(999, 100) bad times",   "blink",          {"times": 999, "period": 100}, False, "range"),
     ]
 
     passed = failed = 0