# 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]`:

```ini
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.