Wire Frame Specification

Wire Frame Specification

Version: 0.1.0-draft
Status: Draft Standard — Production Ready

---

1. Sync Magic Sequence

Every Pyintel Lux binary frame begins with a fixed 2-byte sync magic sequence:

0x4C  0x58   →   ASCII characters 'L' 'X'

Receivers parse incoming byte streams by scanning for this sync sequence, enabling instantaneous packet re-synchronization following noise, packet drops, or mid-stream connections.

---

2. Fixed Frame Header Layout (14 Bytes)

Offset  Size   Field              Description
------  ----   -----------------  -------------------------------------------
0       2B     Sync               0x4C 0x58 magic ('LX')
2       2B     Sequence Num       Monotonic sequence counter (little-endian uint16)
4       2B     Symbol ID          Compile-time symbol ID token (little-endian uint16)
6       4B     Timestamp (µs)     Monotonic microsecond clock (little-endian uint32)
10      1B     Payload Type       Enum byte (0x00=none, 0x01=u8, 0x02=u16, 0x03=u32, 0x04=i32, 0x05=f32, 0x06=bytes, 0x07=str_ref)
11      1B     Payload Length     Number of payload bytes that follow (0–255)
12      2B     CRC-16/CCITT       CRC over header bytes [0..11] (little-endian uint16)
--- Header End (14 Bytes Minimum) ---
14+     N B    Payload            Raw packed payload bytes (N = Payload Length)

Minimum frame size: 14 bytes (for zero-payload event emissions).

---

3. Symbol ID Tokenization

Symbol IDs are 16-bit unsigned integers assigned at compile time by tools/lux-dict-gen. They replace raw log strings on the wire and map to entries in the host-side symbols.json dictionary.

Reserved Symbol ID Ranges

Range	Category	Description
0x0000	Invalid	Null / Unassigned
0x0001–0x00FF	System Events	Internal Lux events (heartbeats, resets, overflows, mesh join/leave)
0x0100–0xFFFE	User Symbols	User-defined application metrics, logs, and telemetry channels
0xFFFF	Reserved	System Broadcast / Reserved

---

4. Payload Type Enumeration

Code	Name	Payload Size	Native C Type
0x00	LUX_TYPE_NONE	0 bytes	—
0x01	LUX_TYPE_U8	1 byte	uint8_t
0x02	LUX_TYPE_U16	2 bytes	uint16_t
0x03	LUX_TYPE_U32	4 bytes	uint32_t
0x04	LUX_TYPE_I32	4 bytes	int32_t
0x05	LUX_TYPE_F32	4 bytes	float
0x06	LUX_TYPE_BYTES	N bytes	uint8_t[]
0x07	LUX_TYPE_STR_REF	2 bytes	Symbol ID of a string token

---

5. Built-in System Symbols

Symbol ID	Name	Payload	Description
0x0001	LUX_SYM_HEARTBEAT	u32	Periodic device node uptime (ms)
0x0002	LUX_SYM_RESET	u8	Hardware reset event and reset cause code
0x0003	LUX_SYM_OVERFLOW	u16	Internal transmit/receive buffer overflow count
0x0004	LUX_SYM_TRANSPORT_SWITCH	u8	Dynamic transport fallback event (e.g. Wi-Fi lost -> ESP-NOW)
0x0005	LUX_SYM_DEVICE_INFO	bytes	Hardware capabilities and board metadata
0x0006	LUX_SYM_PIN_REPORT	bytes	Hardware pin state report
0x0007	LUX_SYM_BORDER_LOCK	u8	Freeze mesh topology & power down unused radios
0x0008	LUX_SYM_BORDER_UNLOCK	u8	Resume promiscuous multi-bearer discovery
0x0009	LUX_SYM_BORDER_KNOCK	u8	Join knock for straggler nodes

---

6. Error Detection (CRC-16/CCITT)

Lux uses CRC-16/CCITT-FALSE (Polynomial 0x1021, Initial value 0xFFFF, no reflection).

• Computed over header bytes 0 to 11 inclusive.
• Evaluated using a 256-entry software/hardware lookup table (LUT) for sub-microsecond computation.
• Receivers detecting a CRC mismatch immediately discard the frame and scan forward for the next 0x4C 0x58 sync magic.