maintain-badge-protocol

Files (1)

• SKILL.md

SKILL.md (first lines)

# Maintain badge protocol

1. Read `notes/protocol.md`, `notes/acceptance.md`, and the affected `FEATURES.md` entry.
2. Inspect the current implementation and tests before proposing a change:
   - transport and line parser: `src/lib/badge-connection.js`
   - command grammar and framing: `src/lib/protocol.js`
   - retry and transaction policy: `src/lib/transfers.js`
   - image conversion and packing: `src/lib/image-pipeline.js`
   - executable evidence: `test/*.test.mjs`
3. Check the pinned upstream implementation, not only README, docstring, or help text. Use the full-SHA links in `notes/protocol.md`:
   - image: `dc34-image/dc34_image/send_image.py` and `dc34-console/src/cmds/image.rs`
   - BIO: `dc34-bio/dc34_bio/dc34_bio.py` and `dc34-console/src/cmds/bio.rs`
   - USB identity/composition: Xous `services/usb-bao1x/src/hw.rs`
4. Preserve runtime VID:PID `1d50:6198` and one queued command at a time. Desktop prefers native Web Serial; Android prefers WebUSB CDC even when native Serial is present. The experimental WebUSB chooser uses exact VID/PID only, then `web-serial-polyfill` 1.0.15 requires and claims CDC control class `0x02` and data class `0x0a`, sets 1,000,000-baud 8-N-1 line coding, asserts DTR, and uses the CDC data endpoints. Do not claim HID interfaces.
5. Keep the command surface exactly as narrow as the grammar table in `notes/protocol.md`: version query; image clear/chunks; BIO ready, clear, reload, pin, clock, chunks, one-word FIFO3 TX, and one-sample FIFO3 RX. Reject `bio pad`, `test`, UF2/firmware, FIDO vendor, malformed chunk arguments, and arbitrary console input.
6. Parse exact, state-specific acknowledgements. The exact `[console] <command>` echo arms the response matcher; ignore blank lines, mismatched echoes, and acknowledgements that arrive before that echo. Retain unrelated Xous lines only as telemetry. `ERR` and `ERR ...` reject the pending command.
7. Preserve the timeout and retry matrix in `notes/protocol.md`. The short echo deadline ends when the exact shell echo arrives; response timing starts fresh from that echo. Retrying a non-final indexed chunk is safe because firmware overwrites duplicate indices. Do not blindly retry a final chunk or treat `OK` as proof of persistence. On a connected final timeout or final `OK`, replay chunks zero through final without clearing, accept `OK` or `SUCCESS`, and stop immediately on `SUCCESS`. Use commit-length echo/response deadlines and zero same-command retries for recovery frames. A remaining connected, non-aborted, non-deterministic failure may make one full clear-and-restart attempt; validation, allowlist, explicit firmware rejection, cancellation, and disconnect failures must not restart.
8. For images, keep the user preview logical and unmirrored. Test payload orientation and pinned CRC/Base64 vectors. Inputs are MIME-gated, capped at 30 MiB, rejected above 80 megapixels, and retained at a 4,096-pixel longest edge. The initial decode still happens before the dimension check; do not describe the compressed-file cap as a decoded-memory bound.
9. Clear before image transfer and send exactly 32 chunks. Require `OK` for chunks 0–30 and `SUCCESS` for chunk 31.
10. For BIO, disclose replacement, clear first, validate pins and clock locally, zero-pad to `0xF00` (3,840) bytes, send all 60 chunks, and reload. Firmware's `BIO_MEM_BYTES` and `NUM_CHUNKS` supersede the uploader's stale 4,096-byte/64-chunk prose. Never send `bio pad`.
11. Run `npm run check`. Record automated output, source-inspection anchors, browser results, and production-badge runs in `notes/acceptance.md`; leave claims unchecked when that evidence does not exist.

From pierce403/34b.ninja, MIT.

More from pierce403/34b.ninja