trikkeSensors/docs/binary-record-v1.md

TRK1 Binary Telemetry — Version 1

The binary stream is the shared transport and storage representation for USB, BLE, and any later nonvolatile buffer. All multibyte integers and IEEE-754 float32 values are little-endian. Frames are self-identifying and may be split or combined by an underlying byte transport.

Frame header (36 bytes)

Offset	Size	Field
0	4	ASCII magic TRK1
4	1	Wire version (1)
5	1	Packet type: metadata 1, samples 2
6	1	Header size (36)
7	1	Record size (0 or 20)
8	1	Record count (0 or 1–8)
9	1	Packet flags
10	2	Payload size
12	4	Monotonic packet sequence
16	8	Base ESP timer timestamp in microseconds
24	4	Cumulative samples lost to sensor read failure or queue overflow
28	4	Cumulative acquisition-loop overruns
32	4	IEEE CRC-32

CRC uses polynomial 0xEDB88320, initial value 0xFFFFFFFF, and final XOR 0xFFFFFFFF. It covers header bytes 4–31 followed by the complete payload. The magic and stored CRC field are excluded.

Packet flag bit 0 means at least one sample timestamp delta saturated. Both host tools report any frame carrying this flag instead of silently treating its reconstructed timestamps as exact.

Sample record (20 bytes)

Offset	Size	Field
0	4	Sample sequence
4	2	Timestamp delta from the preceding record, in 10 us units
6	2	Enclosure accel X raw (int16)
8	2	Enclosure accel Y raw (int16)
10	2	Enclosure accel Z raw (int16)
12	2	Enclosure gyro X raw (int16)
14	2	Enclosure gyro Y raw (int16)
16	2	Enclosure gyro Z raw (int16)
18	1	Raw ADXL345 INT_SOURCE
19	1	Raw L3G4200D STATUS_REG

The first record has delta zero and uses the frame's base timestamp. Each later timestamp is reconstructed by cumulatively adding its delta. Firmware ends the current packet before a delta exceeds the representable 655.35 ms range, making the next sample the exact base timestamp of a new packet. As a defensive encoder fallback, an unrepresentable delta is stored as 0xFFFF and sets packet flag bit 0. Sample sequence gaps remain detectable independently.

Mapped raw counts are authoritative. The original sensor-native axes can be reconstructed because the mappings are lossless:

accel native = (-enclosure_y, enclosure_x, enclosure_z)
gyro native  = ( enclosure_x, enclosure_y, enclosure_z)

Metadata payload (48 bytes)

Metadata frames repeat approximately every five seconds so a receiver may attach midstream. The payload contains:

• Sample rate, accelerometer range, gyroscope range, and mapping/calibration flags
• Three accel offset float32 values
• Three accel counts/g float32 values
• Three gyro bias float32 values
• Nominal gyro mdps/LSB float32 value

A byte-stream receiver may begin inside an incomplete frame. It discards bytes until a magic/header/CRC combination validates. Host tools report any rejection before that first valid frame separately from CRC failures after synchronization.

Buffering

Acquisition runs in a dedicated higher-priority task and writes complete samples to a 512-entry RAM queue. The lower-priority output task batches up to eight records per frame. At 100 Hz this queue represents about 5.12 seconds of decoupling when the transport reports backpressure or failure accurately. A failed write retains and retries the same encoded packet rather than dequeuing more samples, so the queue accumulates the outage backlog. After reconnection, the oldest retained data is sent first. If the queue fills, acquisition drops new samples rather than overwriting older ones; sequence gaps and the cumulative lost-sample counter expose that permanent loss.

That retry guarantee requires the transport's success result to mean that the complete frame was accepted for eventual delivery. The current USB Serial/JTAG VFS/stdio path does not fully satisfy that contract: if the host remains connected but stops draining, its internal timeout can discard bytes while the stdio write appears successful. CRC and sequence checks make that loss visible to a receiver, but it does not increment the device's drop counter. A direct driver path with bounded transmit-drain waits can report this condition; an application acknowledgement and replay window is required for end-to-end delivery confirmation.

Receivers report bytes left in an incomplete trailing frame when capture ends. Those bytes cannot pass CRC validation and are not silently admitted as samples.