musicmouse/docs/agent-tasks/05-firmware-serial-frames.md

Task: stop the firmware garbling its own messages to the host

Why

sendMessageToHost (esp-firmware/src/Messages.h) writes one frame as four separate Serial.write calls: magic, type, size, payload. It runs on two FreeRTOS tasks at once:

• the Arduino loop() task, for touch, rotary encoder and button events (esp-firmware/src/main.cpp);
• the RC522 reader's own task (rc522_task in esp-firmware/lib/nfc/rc522.c, priority 4), which calls tagHandler → sendMessageToHost(MsgRfidTokenRead{...}) directly.

When a tag read coincides with a button or touch event, the two frames interleave on the wire. The host's decoder (python-backend/musicmouse/devices/wire.py, FrameDecoder) resynchronises on the magic token and drops what it cannot parse. So the symptom is an occasionally lost figure placement/removal or button press, with a "Discarding bad frame from firmware" warning in the backend log.

What the owner decided

Fix it in whatever way keeps the firmware simplest. A mutex was the first idea. Use the queue below instead, unless it turns out not to work, because it is simpler:

• With a queue, every frame and every log line is written from loop() alone, so no lock is needed anywhere, including around the Serial.println log lines that could otherwise land in the middle of a frame.
• It is exactly the pattern main.cpp already uses for the rotary encoder (eventQueueRotaryEncoder, drained in handleRotaryEncoder() with xQueueReceive(..., 0)).

A mutex would need wrapping every Serial.write / Serial.print in the firmware to be complete. That is more code and easier to get wrong later.

Design

In esp-firmware/src/main.cpp:

1. Create a FreeRTOS queue for tag reads in setupRfidReader(), before rc522_start, so the callback can never run without it. Item type: the 5-byte tag id (MsgRfidTokenRead itself is fine, it is a packed 5-byte struct). Depth: a handful (4) is plenty; the reader polls every 125 ms.
2. tagHandler (runs on the RC522 task) only fills a MsgRfidTokenRead, all zeros for "removed" exactly as now, and xQueueSend(queue, &msg, 0). If the queue is full, drop the read; the reader reports the state again on the next change. Nothing in tagHandler touches Serial any more.
3. Add handleRfid(), called from loop() next to handleRotaryEncoder(). It drains the queue with xQueueReceive(..., 0) and calls sendMessageToHost for each item.
4. Leave Messages.h alone. With a single writer, the four Serial.write calls are fine as they are.

Do not change the wire format, message ids or the host. python-backend/tests/test_wire.py parses Messages.h and pins the ids, and it must keep passing.

Out of scope: the touch thresholds, debouncing, anything in lib/.

Checking it

There are no firmware unit tests that reach main.cpp (the native env only builds the LED effects), and this machine may not have PlatformIO. So:

• It must build: pio run -e esp32 in esp-firmware/. If PlatformIO is not available, say so in the hand-off instead of claiming it builds.
• pio run -e native still builds src/host_test.cpp. That env excludes main.cpp, so this only guards against accidental changes to shared headers.
• scripts/check.sh backend still passes (test_wire.py).
• Manual test on the device, with the backend running at --log-level DEBUG. Hold a hand on an ear touch area while repeatedly placing and removing a figure for a minute, and turn the knob while doing it. Expect every placement and removal to show up as RfidTokenRead, and no "Discarding bad frame from firmware" warnings. Before the fix, the same exercise should produce some.

Done when

The firmware builds, the host tests pass, tagHandler contains no Serial call, and the manual test shows no discarded frames.