MikeFaith/xblink
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Remove application-layer CRC from SRAM mailbox protocol

Browse Source 
ISO15693 already provides CRC-16 at the transport layer, making
the application-layer CRC redundant. Simplifies header from 6 to
4 bytes, removes crc16_continue/verify_crc, and drops STATUS_BAD_CRC.
Also updates design doc and fixes markdown table formatting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
michael
2026-03-05 17:40:56 -08:00
parent 43cda8ac3d
commit f437e4e281
4 changed files with 45 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/plans/2026-03-05-sram-mailbox-protocol.md
View File

@@ -35,20 +35,20 @@ Byte Field
0 Command ID (0x01-0x7F)
1 Sequence number (0-255, incremented per packet)
2-3 Payload length (u16 LE)
4-5 CRC-16 over bytes 0-3 + payload
6-255 Payload (up to 250 bytes)
4-255 Payload (up to 252 bytes)
```
No application-layer CRC — ISO15693 already provides CRC-16 at the transport layer.
**MCU → Phone (written back to SRAM):**
```
Byte Field
0 0xFF (response marker — distinguishes from commands)
1 Echo sequence number
2 Status (0x00=OK, 0x01=BAD_CRC, 0x02=BAD_CMD, 0x03=EEPROM_FAIL, 0x04=INVALID_INDEX)
2 Status (0x00=OK, 0x02=BAD_CMD, 0x03=EEPROM_FAIL, 0x04=INVALID_INDEX)
3 Payload length
4-5 CRC-16 over bytes 0-3 + payload
6-255 Response payload
4-255 Response payload
```
The 0xFF response marker lets the phone distinguish "MCU hasn't responded yet" (byte 0 still holds old command ID) from "response ready" (byte 0 = 0xFF).
@@ -143,13 +143,12 @@ loop {
### Command Processing
1. Read SRAM bytes 0-5 (header)
1. Read SRAM bytes 0-3 (header)
2. Validate command ID (0x01-0x08)
3. CRC-16 check over header + payload — if bad, write `BAD_CRC` response
4. Read remaining payload bytes based on length field
5. Execute command (see per-command logic below)
6. Write response to SRAM
7. Return to polling
3. Read remaining payload bytes based on length field
4. Execute command (see per-command logic below)
5. Write response to SRAM
6. Return to polling
### Per-Command Logic
@@ -196,12 +195,12 @@ No special handling required. LP5562 engines run autonomously on the chip's inte
## Error Handling
- **Bad CRC**: Respond with `BAD_CRC` (0x01), discard command
- **Unknown command**: Respond with `BAD_CMD` (0x02)
- **EEPROM write failure**: Respond with `EEPROM_FAIL` (0x03), library may be in partial state
- **Invalid pattern index**: Respond with `INVALID_INDEX` (0x04)
- **Phone timeout**: If phone stops sending during SYNC, library is partial. Next SYNC_START will erase and restart. No persistent corruption — header CRC won't match partial data, so boot falls back to hardcoded patterns.
- **Garbage in SRAM**: Bad command ID or CRC → error response, resume polling. Each command is self-contained, no state to corrupt.
- **Garbage in SRAM**: Bad command ID → error response, resume polling. Each command is self-contained, no state to corrupt.
- **Transport integrity**: ISO15693 provides CRC-16 at the link layer — no application-layer CRC needed.
## Phone-Side Polling
@@ -215,7 +214,7 @@ After writing a command to SRAM, the phone polls byte 0 via ISO15693 READ SINGLE
1. **NTAG5 SRAM driver** — `src/ntag5/sram.rs`: block read/write at 0xF8-0xFF
2. **FD pin setup** — Session register config at boot, GPIO input on A1
3. **Command parser** — Read SRAM, validate header/CRC, dispatch
3. **Command parser** — Read SRAM, validate header, dispatch
4. **Command handlers** — WRITE_PATTERN, GET_STATUS, SET_ACTIVE first
5. **Streaming sync** — SYNC_START/END, READ_LIBRARY/NEXT
6. **Testing** — PCSC reader with Python test script, then VivoKey RawNFC app