ESP32_ZACUS/docs/scenario-mesh-receiver-patch.md

ESP-NOW scenario receiver — patch to report onto PLIP + puzzles

Status: box3_voice done; puzzle nodes done (defensive demux in the shared espnow_slave.c, see "Resolution" below); PLIP done (brought back into scope on 2026-06-10 — dedicated receiver src/scenario_now.{h,cpp} in PLIP_FIRMWARE, see "PLIP" below).

Spec: docs/specs/2026-05-24-firmware-scenario-hotload.md, task 6 ("Receiver side on each peer").

Resolution (2026-06-09)

Investigation of the real firmware changed the plan from "vendor a reassembler into each node" to "demux defensively, treat as no-op consumer", because:

• No puzzle node runs a Runtime 3 scenario. p7_coffre (the final lock) receives its 8-digit code via MSG_PUZZLE_CONFIG (8 bytes), not an IR; the others are driven entirely by MSG_* commands. None has a LittleFS/SPIFFS scenario store. Pushing a full scenario to them is genuinely a no-op.
• The real risk is stream corruption, not a missing feature: a multi-frame scenario relay misrouted to a puzzle MAC would inject frames whose data[0] equals the frame seq low byte — e.g. seq==1 → 0x01 == MSG_PUZZLE_SOLVED.

So the receiver was added once to the shared lib/espnow_common/espnow_slave.c (compiled into all four puzzles): frames are demultiplexed in espnow_slave_process() (task context, not the ISR), reassembled per source MAC, and handed to an optional espnow_scenario_callback_t. Puzzle nodes register no callback, so a reassembled scenario is logged and dropped — and, critically, never reaches the MSG_* path. A future node that does consume scenarios opts in via espnow_slave_register_scenario_callback(). No per-puzzle code changed; no new component; bounded heap reassembly (≤64 KiB), 5 s sender-silence timeout.

The original per-node inline-reassembler sketch below is kept for historical context; the shared-file approach above supersedes it.

What box3_voice got (the reference implementation)

box3_voice is a standalone IDF project that does not use the legacy ESP-NOW slave. It received:

1. components/scenario_mesh/ — a vendored copy of the master's component (frame protocol + reassembly + alias→MAC table). Identical bytes to idf_zacus/components/scenario_mesh/.
2. scenario_server.c refactored so the validate+write path is a reusable scenario_apply_buffer(const char *data, size_t len) (declared in scenario_server.h). Both the HTTP POST /game/scenario handler and the ESP-NOW receiver call it — the single _scenario_apply the spec mandates.
3. main.c calls scenario_mesh_init(scenario_apply_buffer) after Wi-Fi / scenario_server_start().

box3 could take the component wholesale because it owns its ESP-NOW stack — it does not register any other esp_now_register_recv_cb.

Why PLIP + puzzles can't just drop the component in

The puzzle nodes already own the single ESP-NOW receive callback via lib/espnow_common/espnow_slave.c (esp_now_register_recv_cb(on_recv)). ESP-IDF allows one recv callback per process. scenario_mesh_init() calls esp_now_register_recv_cb() too, so calling it after espnow_slave_init() would silently steal the puzzle command stream (or vice-versa). The two protocols must be demultiplexed inside the one existing callback.

Frame discriminator (no wire-format change needed):

• Legacy puzzle frames: data[0] is a MSG_* type in 0x01..0x08 (see espnow_slave.h).
• scenario_mesh frames: data[0..1] = seq (u16 LE), data[2..3] = total (u16 LE), then payload. For the first frame seq==0 so data[0]==0x00, which never collides with a MSG_* type. A scenario frame is also always >= 4 bytes with total >= 1 and seq < total.

So: data[0] == 0x00 (and len >= 4) ⇒ scenario frame; otherwise legacy.

Patch for each puzzle node (p1, p5, p6, p7_coffre)

These share lib/espnow_common/espnow_slave.c, so patch it once there (it is compiled into each puzzle via the ../../../lib/espnow_common/espnow_slave.c SRC entry already present in every puzzle main/CMakeLists.txt).

1. Add the reassembler. Either:

   • vendor scenario_mesh as a component but do not let it register the recv cb (add a scenario_mesh_feed_frame(const uint8_t *src, const uint8_t *data, int len) entry point and a scenario_mesh_init_passive() that skips esp_now_register_recv_cb), or
   • inline a ~60-LOC reassembler keyed by (src_mac, total) straight into espnow_slave.c (simplest; no new component).

2. In espnow_slave.c::on_recv, branch before the queue push:

   static void on_recv(const esp_now_recv_info_t *info,
                       const uint8_t *data, int len) {
       if (len >= 4 && data[0] == 0x00) {           // scenario frame
           scenario_mesh_feed_frame(info->src_addr, data, len);
           return;
       }
       /* …existing puzzle-command path (queue push)… */
   }
   

   On full reassembly the reassembler writes the JSON to the node's local filesystem and calls scenario_engine_reload() (or, until that symbol lands, the puzzle's equivalent of scenario_apply_buffer() + deferred esp_restart(), mirroring box3).

3. Each puzzle needs a scenario_apply_buffer() equivalent. The puzzle nodes currently have no LittleFS/SPIFFS scenario store — if a node is purely driven by ESP-NOW puzzle commands and has no IR of its own, task 6 may be a no-op for it. Confirm per node before adding storage: p7_coffre (the final-code lock) is the most likely to actually consume a scenario.

PLIP (PLIP_FIRMWARE) — done (re-scoped 2026-06-10)

Originally resolved out of scope on 2026-06-09 (Wi-Fi/HTTP-only client, no ESP-NOW stack). Re-scoped in on 2026-06-10 by explicit request: PLIP now has a dedicated receiver, PLIP_FIRMWARE/src/scenario_now.{h,cpp} (Arduino C++, matching the zacus_hook_client worker-task pattern).

• Same wire format as scenario_mesh / the shared espnow_slave.c: 4-byte header { seq:u16 LE, total:u16 LE }, <=236 payload bytes, bounded heap reassembly (<=64 KiB), 5 s sender-silence timeout.
• PLIP registers no other esp_now_register_recv_cb, so the module owns the single callback — no MSG_* demux needed (unlike the puzzle nodes).
• A completed scenario is persisted to LittleFS at /scenario.json (temp-then-rename); an optional scenario_now_register_callback() hook lets a future Runtime 3 engine consume it. With no consumer registered the scenario is stored and logged.
• network_task.cpp calls scenario_now_init() once the station is up (ESP-NOW rides the AP's channel); the call is idempotent and repeated on reconnect.

The HTTP path (POST /game/scenario on PLIP's future REST server) remains the recommended push channel once that server lands; the ESP-NOW receiver covers the relay/fallback case in the meantime.

Shared-protocol drift risk — resolved 2026-06-10

scenario_mesh was vendored byte-identical in two places (idf_zacus/components/ and box3_voice/components/). It now lives once at lib/scenario_mesh, referenced by both projects via EXTRA_COMPONENT_DIRS in their root CMakeLists — the follow-up suggested below is done; both firmwares rebuilt green after the hoist.

Two independent reimplementations of the frame format remain by design (different runtimes, not copies): the puzzle nodes' demux inside the shared lib/espnow_common/espnow_slave.c, and PLIP's Arduino-side PLIP_FIRMWARE/src/scenario_now.cpp. If the 4-byte header { seq:u16 LE, total:u16 LE } or the 236-byte payload cap ever changes, update those two alongside lib/scenario_mesh.