Protocol

Protocol

A radio frame is one short message from the transmitter. For a gentle explanation, start with How it works. This page summarises the supported radio and frame layout; the exact recurrence, decoder conventions and offsets are in docs/PROTOCOL.md.

This describes the supported receive path, not every Taggle generation. Unknown fields stay uninterpreted. A CRC detects accidental errors; it does not authenticate a transmitter.

Radio summary

Setting	Value
SDR centre / samples	922.2 MHz, 2.4 MS/s, unsigned 8-bit interleaved I/Q
Target carrier	About 921.995 MHz; acquisition searches ±100 kHz around the expected baseband offset
Modulation	BPSK, about 1172.66 coded symbols/s
Spreading	4095-chip m-sequence per coded bit, about 4.802 Mchip/s on the nominal ADC clock
PN polynomial	x^12+x^9+x^6+x^5+x^2+x+1, packed as 0x1267
Preamble	104 constant symbols
Error coding	Rate 1/2, constraint length 7, masks 0x6d, 0x4f (octal 155, 117 in the documented convention)
Coded body lengths	288 / 336 / 384 bits for 18 / 21 / 24-byte decoded frames; total 392 / 440 / 488 symbols including preamble

The fitted symbol period is near 2046.625 ADC samples and is refined per burst; absolute clock accuracy is not established. The configured centre must retain the supported carrier band. This is not a whole-band scan of 915–928 MHz.

Frame formats

For exact bit offsets, polynomial conventions, error checks and decoding rules, use the repository's protocol specification. This wiki summarises the user-visible result:

Decoded format	What ha-taggle can use	Evidence
18-byte clear	Transmitter ID, hourly sequence and three raw counter slots, plus signal diagnostics	One Gladstone transmitter and generated tests
21-byte clear	The same supported fields, with extra bytes left uninterpreted	Generated tests only
24-byte encrypted	Clear ID and signal diagnostics only; no usage	Generated tests only

Three raw counter slots give two hourly pulse differences. The 16-bit counter wraps at 65,536; its starting value and litres per pulse are unknown. The 8-bit hourly sequence wraps at 256. ha-taggle counts overlapping intervals once and uses elapsed time to help interpret sequence changes. An inconsistent sequence causes a new baseline, rather than guessed usage.

A later frame can recover a single missed transmission. Intervals that remain unrecovered stay missing. “Today” groups recovered intervals by the local date of their estimated end, rather than by utility clock-hour buckets. Neither the radio counter nor ha-taggle's meter_count is the absolute dial reading. See Calibration and Entities reference for the usage totals.

In 0.3.0, scan output includes sample-derived UTC frame time, ID and one-decimal signal measurements, plus counts only for configured clear IDs. It has no frame-length field. The scan guide gives a complete example. Missing counts for an unconfigured ID establish neither encryption nor frame length.

Limits and validation

The receiver captures only part of the wideband spread signal. Antenna quality, noise, collisions, USB loss, radio clock drift and CPU performance affect reception. Daily totals can be incomplete; counter resets are ambiguous; flag meanings remain unknown; modulo differences cannot distinguish multiple wraps. Missing usage stays missing. This is not billing-grade accuracy.

Generated tests create fake frames and filtered PN-modulated IQ using the project's encoder; they do not establish compatibility with every transmitter. Only one Gladstone transmitter has field confirmation (18-byte clear format); 21-byte clear and 24-byte encrypted handling have generated tests only. See docs/PROTOCOL.md for exact generation, acquisition and validation details.