daelon-docs/docs/LiquidCore15/telemetry-interface.md

Telemetry Interface

The LiquidCore15 firmware streams a continuous binary telemetry frame over UART and UDP at 100 Hz, giving a host controller or operator GUI a real-time view of all monitored control variables.

---

Frame Format

Every frame is exactly 63 bytes:

Byte(s)	Field	Value
[0]	Sync low	0x55
[1]	Sync high	0xAA
[2]	Length	0x3A (58 decimal = payload size)
[3..60]	Payload	TelemetryPayload_t — 58 bytes, packed
[61]	CRC low	CRC16-CCITT low byte
[62]	CRC high	CRC16-CCITT high byte

Sync bytes form the little-endian word 0xA55A — check both bytes before decoding.

CRC: CRC16-CCITT (polynomial 0x1021, init 0xFFFF) computed over bytes [2..60] (59 bytes: length byte + full payload). No output inversion.

---

Payload Fields

TelemetryPayload_t is __attribute__((packed)), 58 bytes. Field order is stable — the host decoder assumes this exact layout.

Offset	Type	Field	Description
0	float	Vdc	DC bus voltage (V)
4	float	Ia	Phase A current (A)
8	float	Ib	Phase B current (A)
12	float	Ic	Phase C current (A)
16	float	Va	Phase A grid voltage (V)
20	float	Vb	Phase B grid voltage (V)
24	float	Vc	Phase C grid voltage (V)
28	float	Id	d-axis current feedback (A)
32	float	Iq	q-axis current feedback (A)
36	float	Id_ref	d-axis current reference (A)
40	float	Iq_ref	q-axis current reference (A)
44	float	theta	PLL grid angle (rad, 0 .. 2π)
48	float	omega	PLL angular frequency (rad/s)
52	uint8_t	pll_locked	1 = locked, 0 = searching
53	uint8_t	mode	FSM state (see below)
54	uint32_t	fault_flags	Active fault bitmask (see below)

All floats are IEEE 754 single-precision, little-endian (Cortex-M native byte order).

mode — FSM State

Value	State
0x00	FSM_INIT
0x01	READY
0x02	RUNNING
0x03	FAULT

fault_flags — Fault Bitmask

Bit	Fault
0	Over-voltage (OV)
1	Under-voltage (UV)
2	Over-current (OC)
3	Frequency high
4	Frequency low

---

Transmission

UART: USART3 (hcom_uart[COM1]), 115200 baud, GPDMA1 Channel 0 (DMA mode).

• Cadence: every 160th control tick → 100 Hz.
• If UART DMA is busy when a frame is ready, the frame is dropped silently. At 100 Hz × 63 bytes = 6 300 bytes/s versus 11 520 bytes/s line capacity, collision probability is low.
• Double-buffering: two 63-byte buffers swap between fill and DMA-in-flight roles.

UDP: The same 63-byte frame is forwarded to eth_send_telem() (implemented in eth.c) on every tick, independent of UART DMA state.

---

Integration Checklist

• Open a 115200-baud serial connection to USART3 (or listen on the UDP socket).
• Scan the byte stream for the two-byte sync sequence 0x55 0xAA.
• Read the next 61 bytes (length + payload + CRC).
• Verify CRC16-CCITT over bytes [2..60]; discard frame on mismatch.
• Deserialize TelemetryPayload_t in the field order above (little-endian floats).
• Check pll_locked before using theta / omega for phase-sensitive calculations.
• Check fault_flags != 0 and handle mode == 0x03 (FAULT) before commanding.