FreeDMR/docs/dmr-data-observability.md

DMR Data Observability

FreeDMR can emit passive, per-burst metadata for received DMR data/control traffic. The observer does not change routing, packet bytes, acknowledgement state or delivery behavior.

Enable

The feature is disabled by default. Enable it in [GLOBAL]:

DATA_PACKET_LOGGING: True

Restart FreeDMR after changing the setting.

The setting applies to both HBP and FBP/OpenBridge receive paths. Voice header, voice payload and voice terminator bursts never enter the data observer.

At normal INFO log level, FreeDMR emits only decoded human-readable records:

• *DMR DATA TEXT* for conservative ASCII, UTF-16BE or UTF-16LE text;
• *DMR DATA GPS* for complete NMEA GPRMC/GNRMC positions;
• existing *IN-CALL TA* records for complete Talker Alias text;
• existing *IN-CALL GPS* records for decoded embedded-LC positions.

Set the server log level to DEBUG when raw burst and protocol detail is also required.

Logged fields

At DEBUG, each eligible RX burst produces one bounded *DMR DATA OBSERVE* record:

Field	Meaning
TRANSPORT	Source receive path: HBP or FBP/OBP.
STREAM ID, SEQ, TS, CALL	Wrapper stream and burst metadata.
SRC, DST, PEER	Wrapper source, destination and peer IDs.
TYPE	Data type reported by the HBP/FBP wrapper.
AIR_TYPE, CC	Uncorrected Slot Type data bits carried in the 33-byte DMR burst.
MATCH	Whether wrapper and air-burst data types agree.
CODING	Expected coding for the wrapper data type.
SYNC	Raw 48-bit center sync field.
DPF	Data Packet Format for a BPTC-decoded Data Header.
CSBKO, FID	Opcode and feature-set ID for a BPTC-decoded CSBK.
LOGICAL	Generic 12-byte BPTC(196,96) information extraction where applicable.
RAW	Complete original 33-byte DMR burst payload.
CRC	Validation status. The first implementation reports NOT_CHECKED.

Supported DPF labels are UDT, response, unconfirmed, confirmed, defined short data, raw/status short data and proprietary. Unknown values remain numeric and are labelled UNKNOWN.

CSBK, MBC header/continuation, Data Header and Rate 1/2 bursts receive generic BPTC extraction. Rate 3/4 and Rate 1 payloads are kept raw; this observer does not guess at trellis or rate-1 decoding. Idle and reserved burst types are deliberately skipped to avoid noise and log-volume overhead.

Human-readable reconstruction

The observer keeps a small per-router least-recently-used collector. It retains at most 32 data streams and 256 logical bytes per stream. Only decoded Rate 1/2 logical blocks are accumulated; voice, CSBK, Data Header, Idle, Rate 3/4 and Rate 1 payloads are not added to the human-content buffer.

Obvious text runs of at least four characters are reported. The known UDP port signature 5016 (1398 hexadecimal) gives an ETSI/ANYTONE SMS profile hint, and port 4007 (0fa7) gives a MOTOROLA SMS hint. These are hints for capture analysis, not proof that every payload follows that vendor profile.

Complete $GPRMC and $GNRMC sentences are converted to decimal latitude and longitude and include status, UTC, speed in knots and course. Duplicate text or location observations within the bounded stream buffer are suppressed.

Deliberate limits

This is a capture aid, not a DMR data endpoint. It does not currently:

• validate or correct BPTC, CRC16, CRC9 or data CRC32;
• perform standards-complete DMR fragmentation/pad/CRC reassembly;
• send confirmed-data ACK/NACK/SACK responses;
• infer a vendor profile;
• decode binary MD-380, Motorola LRRP or Hytera LP locations;
• parse ARS, IP packets or vendor application ACKs;
• write new report-socket event formats.

Those features need capture-backed fixtures for ETSI/Anytone, MD-380-like, Hytera and Motorola profiles before they can be implemented reliably.

Performance and privacy

When disabled, the receive path performs only the configuration check and exits. When enabled, per-burst work and collector memory are bounded. Human-readable records are concise at INFO; detailed DEBUG logging can be voluminous, so use it only while collecting protocol captures on a system with appropriate log capacity.

RAW and LOGICAL may contain private message, location or application data. Treat these logs as sensitive and disable the feature after capture work.