Skip to content

Spec: TextLink wire protocol (board-to-host text over a UART)

Field Value
ID spec-textlink-wire-protocol
Status Draft. Unverified on hardware: no board has ever sent a frame; everything below is exercised only by a software simulator on a PC
Date 2026-11-13
Module none in src/yazses/. Reference code: examples/maixcam2-text-link/textlink.py (codec), simulated_board.py, host_reader.py, board/maixpy_send.py
Related ADR-030 (new capabilities are frozen, which is why this is an example and not a feature), ADR-011 (offline by default)

Purpose and scope

A research question: can a Sipeed MaixCAM2 board, running Whisper-base on-device, send the text it recognised to a desktop over a wired UART? This document fixes the byte format of that link so a sender and a receiver written independently agree.

It specifies the wire format and the receiver's validation rules. It does not specify what a consumer does with the text, and the reference reader only prints it. It adds nothing to YazSes: no config key, no CLI command, no daemon wiring.

Key words MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.

Physical layer

Asynchronous serial, 115200 baud, 8 data bits, no parity, 1 stop bit (8N1), no flow control, one direction (board to host). Logic levels: check the logic level of your board revision. Sipeed documents 3.3 V for MaixCAM and does not state it for MaixCAM2. The adapter must match it. A conforming sender MUST NOT use the board's system console UART for this link.

Frame layout

All multi-byte integers are big-endian. A frame is the concatenation:

Offset Size Field Value
0 2 SYNC 0x59 0x53 (ASCII YS)
2 1 VER 0x01
3 1 TYPE 0x01 TEXT, 0x02 TRIGGER, 0x03 PING
4 1 SEQ 0..255, +1 per frame sent, wraps 255 to 0
5 2 LEN payload length in bytes, u16
7 LEN PAYLOAD see below
7+LEN 2 CRC16 u16, over bytes 2 .. 6+LEN (VER through PAYLOAD)

Header is 7 bytes, trailer 2, so a frame is 9 + LEN bytes and the largest is 521 bytes.

TYPE Name LEN Payload
0x01 TEXT 1..512 UTF-8 text
0x02 TRIGGER 0 none: "start now" marker, no text
0x03 PING 0 none: heartbeat

No frame of any type, known or not, may have LEN greater than 512.

CRC

CRC-16/CCITT-FALSE: polynomial 0x1021, initial value 0xFFFF, no input or output reflection, final XOR 0x0000. Check value: the CRC of the ASCII bytes 123456789 is 0x29B1. The CRC covers VER, TYPE, SEQ, LEN and PAYLOAD; it does not cover SYNC or itself. It is sent high byte first.

Worked example for hello, SEQ 0: the covered bytes are 01 01 00 00 05 68 65 6c 6c 6f, the CRC is 0xE53C, sent as e5 3c.

A CRC detects accidental corruption. It is not authentication: anyone who can write to the wire can forge a valid frame.

TEXT validation (receiver)

A receiver MUST apply these steps to a CRC-valid TEXT payload, in order, and on any failure MUST drop the whole frame (never repair or truncate) and count it:

  1. Decode as strict UTF-8 (no replacement characters, no overlong forms, no surrogates, no code points above U+10FFFF).
  2. NFC-normalise.
  3. Refuse if the text contains any control character: C0 (U+0000-U+001F, including NUL, TAB, LF, CR and ESC), DEL (U+007F) or C1 (U+0080-U+009F). Multi-line text is therefore not representable.
  4. Refuse U+2028 and U+2029 and every character of Unicode general category Cf (format). That covers the bidirectional controls U+202A-U+202E, U+2066-U+2069, U+200E, U+200F and U+061C, and the invisible characters U+200B (zero-width space), U+2060 (word joiner), U+FEFF (BOM), U+206A-U+206F, U+FFF9-U+FFFB, the tag characters U+E0000-U+E007F and U+00AD (soft hyphen). Exception: U+200C and U+200D (ZWNJ, ZWJ) are allowed, because Persian, Arabic and Indic scripts need them, but only when the text also contains at least one letter (category L). A ZWNJ or ZWJ in text with no letter (for example an emoji ZWJ sequence, or 1 ZWNJ 2) is refused.
  5. Refuse the noncharacters U+FFFE and U+FFFF, the replacement character U+FFFD, and the invisible fillers U+2800 (braille blank), U+3164, U+FFA0, U+115F and U+1160 (Hangul fillers).
  6. Strip surrounding whitespace; refuse if the text has no visible content, meaning no character whose category starts with L, N, P or S. Text of spaces only, a lone combining mark, or a lone ZWNJ is therefore empty.
  7. Refuse if the normalised, stripped text is longer than 512 bytes of UTF-8.

The 512-byte limit applies twice: to the wire payload, and again to the text after normalisation. NFC can expand text: U+0344 becomes two characters and doubles in size, so a payload of 501 bytes can normalise to 1001 bytes. A receiver therefore MUST measure the limit after step 2, and a frame whose normalised text is longer is dropped and counted like any other refused text. A sender SHOULD apply the same rules before sending, so that nothing it sends is dropped, and MUST remove forbidden characters before it normalises, not after. A sender whose recogniser output is too long SHOULD cut at a character boundary at or below 512 bytes after normalisation, or send several frames.

Not handled. Mixed-script and homoglyph text, for example a Cyrillic letter inside a Latin word, passes every rule above, because each character is an ordinary letter. A consumer that types the text MUST apply its own confusable check; this protocol offers none. Likewise no rule here judges whether the text is a command, a name or a URL.

Receiver state machine and resynchronisation

The receiver keeps a buffer. Its result MUST depend only on the concatenation of the bytes received, never on how they were split across reads. Loop:

  1. Find the first SYNC in the buffer. Bytes before it are discarded and counted as resync_bytes. If none is found, discard everything except a trailing 0x59 (it may begin a SYNC split across reads) and wait.
  2. If fewer than 7 bytes are present, wait.
  3. If VER is not 0x01: count bad_version, discard one byte (the first SYNC byte), go to 1.
  4. If LEN is above 512: count oversize, discard one byte, go to 1. The receiver MUST NOT wait for LEN bytes.
  5. If TYPE is TRIGGER or PING and LEN is not 0: count bad_length, discard one byte, go to 1.
  6. If fewer than 9 + LEN bytes are present, wait. At most 521 bytes are ever held.
  7. If the CRC does not match: count bad_crc, discard one byte, go to 1.
  8. The frame is authentic. Consume 9 + LEN bytes, track SEQ (below), then: an unknown TYPE is counted (unknown_type) and ignored; a TEXT payload is validated; a TRIGGER or PING is reported as such.

Discarding a single byte on every error, and never trusting a corrupt LEN to skip ahead, is what lets a truncated frame be followed by good frames without losing them. Every iteration consumes at least one byte, so the loop terminates.

A receiver MAY give up on an incomplete frame after an idle period (the reference reader uses 1 s): it then discards the head byte and rescans, which recovers complete frames queued behind a dead one. A receiver MUST do the same when its input ends (device EOF, the end of a recorded capture), because no more bytes are coming to complete the head, and a valid frame behind a truncated or corrupt head must not be lost. These are the only timing- or end-dependent behaviours.

For bytes-like input the reference parser never raises, whatever the bytes are; handing it a str or another non-bytes-like object is a caller error and raises TypeError.

SEQ

SEQ lets a receiver measure loss and repetition. It never causes an authentic frame to be dropped: nothing is dropped because of its SEQ. For each authentic frame:

  • if (SEQ, TYPE, PAYLOAD) equals the previous authentic frame's, it is an exact repeat: seq_repeats is incremented, and the frame is delivered like any other;
  • otherwise the number of skipped frames is (SEQ - previous_SEQ - 1) mod 256, and a non-zero value counts one seq_gap.

The receiver counts gaps and exact repeats and drops nothing. It cannot tell a retransmission from a repeated utterance: the protocol has no retransmit and no ACK, so a speaker who says "yes" twice produces two identical TEXT payloads, and dropping the second would lose a real sentence. Replay protection is therefore out of scope: a replayed frame, immediate or not, is delivered and, if it is an immediate repeat, counted. A sender that increments SEQ per frame (the reference board script does, modulo 256) makes a repeated utterance differ in SEQ, so seq_repeats then points at a real duplicate rather than at a second utterance.

A board reboot restarts SEQ at 0 and therefore appears as one gap.

Rate limit

The reference reader accepts text through a token bucket of 5 frames per second (burst 5) and drops excess frames; it never queues them. Spoken text is far slower, so a burst is a fault or an attack, and delayed text is the wrong thing to release later. The default is a reader setting, not part of the wire format.

Versioning

  • VER identifies the frame layout. A receiver MUST treat a VER it does not implement as noise (step 3: it cannot know the layout, so it rescans).
  • A new VER is required for any change to SYNC, the header layout, the CRC, the endianness or the meaning of an existing TYPE.
  • A new TYPE value MAY be added within VER 0x01; receivers ignore unknown TYPEs whose CRC is valid. A new TYPE MUST NOT exceed LEN 512.
  • This document is a draft. Until it is accepted, VER 0x01 may still change; nothing should be built on it that cannot be changed.

Golden vectors

Produced by running textlink.encode and textlink.encode_text from the reference code, and cross-checked against binascii.crc_hqx(data, 0xFFFF) (the same CRC) and an independent bit-by-bit implementation in the tests.

Frame Bytes (hex) Length CRC
TEXT hello, SEQ 0 59 53 01 01 00 00 05 68 65 6c 6c 6f e5 3c 14 0xE53C
TEXT 你好,世界, SEQ 7 59 53 01 01 07 00 0f e4 bd a0 e5 a5 bd ef bc 8c e4 b8 96 e7 95 8c 37 61 24 0x3761
TEXT Café, SEQ 255 59 53 01 01 ff 00 05 43 61 66 c3 a9 2c c2 14 0x2CC2
TRIGGER, SEQ 1 59 53 01 02 01 00 00 61 05 9 0x6105
PING, SEQ 255 59 53 01 03 ff 00 00 ef e2 9 0xEFE2
PING, SEQ 0 (after the wrap) 59 53 01 03 00 00 00 20 81 9 0x2081

The Chinese text is 15 bytes of UTF-8 (0x0f); Café is 5 bytes (c3 a9 is the precomposed é).

What is not verified

  • No MaixCAM2 board has sent a frame; the MaixPy sender is untested on hardware.
  • Whether a real UART, a real USB-to-UART adapter and the board's driver deliver the byte stream as the simulator does (FIFO sizes, framing errors, loss under load).
  • Whether 115200 baud is adequate (a 521-byte frame takes about 45 ms; text is far shorter) and whether a higher rate is reliable.
  • Whisper's real output on the board and how a recording is triggered.
  • Security beyond accident detection: there is no authentication, encryption or replay protection, and none is claimed.
  • Mixed-script and homoglyph text (see "Not handled" above) is not detected.