# DVS-Reflector — Operator's Guide *For the person who runs a reflector — not the person who wrote it.* This guide assumes you are a ham who is comfortable with computers and Linux, but who does not live in the terminal. It explains what these programs do, how to set one up, how to keep it healthy, and what to do when something looks wrong. Everything here matches the code as of commit d013655. --- ## 1. The big picture A **reflector** is a meeting room on the air. Repeaters and hotspots from anywhere on the internet connect to it. When one connected user talks, everyone else connected to the room hears them — exactly like a conventional repeater, except the "repeater" lives on your server and the links are IP connections instead of RF. This package contains **five separate reflector programs**, one per digital mode: | Program | Mode | Addresses users by | Default port (UDP) | |------------------|------|--------------------|--------------------| | `P25Reflector` | P25 | Talkgroup (TG) | 41000 | | `NXDNReflector` | NXDN | Talkgroup (TG) | 41400 | | `YSFReflector` | YSF | Callsign (no TG) | 42000 | | `M17Reflector` | M17 | Callsign + Module | 17000 | | `DMRReflector` | DMR | Talkgroup (TG) + Timeslot | 62031 | Pick the program that matches the radios your users actually have. Most operators run one. If you run more than one, they are completely independent programs — each gets its own directory, config file, and port. Section 5 covers linking them together. **Key concept — talkgroups.** P25 and NXDN traffic is addressed to a number (the talkgroup, e.g. TG 9999). A reflector can pass everything, or you can tell it "only relay TG 9999" (that's the `TG=` setting). YSF has no talkgroups — it addresses traffic by callsign, which is why YSF rooms are called by name, not number. **Key concept — modules.** M17 uses modules (A–Z) instead of talkgroups. A module is like a room: users on module A only hear other module A traffic. The allowed modules are configured via `[Modules]` in the INI file. **What you need to run one:** - Any Linux machine (a Raspberry Pi is plenty). Debian/Ubuntu easiest. - One UDP port reachable from the internet (the default ports above). - The compiled program plus its `.ini` config file. That's it. There is no database, no web server required, no registration needed for users to connect (gateways register with an "open poll" — they just need your address and port). --- ## 2. Quick start — first reflector in ~15 minutes **Step 1 — build it.** On the machine that will host the reflector: ```bash sudo apt install build-essential libmosquitto-dev libssl-dev # one-time cd P25Reflector # or NXDNReflector / YSFReflector make ``` This produces the `P25Reflector` binary in the same directory. `make` first builds the shared `Common/libdvcommon.a` (logging, MQTT, threading, etc.) and links it in automatically — no extra steps. **Step 2 — edit the config.** Open `P25Reflector.ini` in a text editor. For a first install there are only a few things that matter: ```ini [General] Daemon=0 # 0 = run in foreground while you test [Network] Port=41000 # UDP port users connect to [MQTT] Enabled=0 # set 1 only if you run an MQTT broker (sec. 6) [P25 Core] Enabled=0 # set 1 only if you're linking to a hub (sec. 5) ``` > **Note:** every reflector ships a sample config in its source directory > (`P25Reflector.ini`, `NXDNReflector.ini`, `YSFReflector.ini`, > `M17Reflector.ini`); production-shaped copies live in `deploy/`. The samples > ship with `[MQTT] Enabled=1` pointing at `127.0.0.1:1883` (set to `0` unless > you run a broker) and `[ Core] Enabled=0` — edge links to a hub are off > by default, so a fresh install will not try to reach anything but your broker > (harmless but noisy if that isn't running either). **Step 3 — run it.** ```bash ./P25Reflector P25Reflector.ini ``` You should see log lines like: ``` M: Starting P25Reflector-... M: Configuration: M: Network port: 41000 ``` (The startup dump lists your whole configuration — a quick way to confirm what you actually configured.) **Step 4 — point a gateway at it.** On the user's hotspot/repeater gateway (Pi-Star, DVSwitch, a P25/NXDN/YSF gateway), set the reflector address to your machine's IP (or hostname) and the port from step 2. When they link, the reflector logs the registration: ``` M: Adding WA9VWJ (198.51.100.24) ``` **Step 5 — confirm audio.** Have a user talk. The log shows the transmission with the source and destination: ``` M: Transmission from WA9VWJ at P25REPEATER to TG 9999 M: Received end of transmission ``` If you see that, you're live. Read the rest of this guide for what the other settings do and how to keep it running. --- ## 3. The config file, section by section All five programs use the same layout: plain-text `Name=Value` lines under `[Section]` headers. `#` starts a comment. The sections below apply to all five unless noted. ### `[General]` | Key | Meaning | |----------|---------| | `Daemon` | `0` = stay in the foreground (logs print to the screen). `1` = fork into the background. See "Running it in the background" below for the `mmdvm` caveat. | | `TG` | P25 and NXDN only. Talkgroup gating: `TG=9999` relays only TG 9999; `TG=0` or no line = relay **all** talkgroups. | ### `[Id Lookup]` — optional, makes logs friendlier | Key | Meaning | |-----|---------| | `Name` | A file mapping numeric IDs to callsigns — `DMRIds.dat` (P25) or `NXDN.csv` (NXDN). With it, logs show the callsign (`Transmission from WA9VWJ ...`) instead of just the number (`Transmission from 1234567 ...`). | | `Time` | Hours between re-reading that file (e.g. `24` = daily). | If the file is missing, the program logs a warning at startup and runs anyway — IDs just display as numbers. Refresh the file periodically (it's a community database; the usual source is the same one your hotspot uses). ### `[Log]` | Key | Meaning | |-----|---------| | `DisplayLevel` | How much goes to the screen: `0` off, `1` everything (default), `3` normal messages, `5` errors only. | | `FileLevel` | Same scale, for the log file. | | `FilePath` | **Absolute** directory for the log file. A relative path resolves against wherever you started the program — use `/absolute/path`. | | `FileRoot` | Log file name prefix. `P25Reflector` produces `P25Reflector-2026-08-20.log`. | | `FileRotate` | `1` = start a new file each day. | Log line prefixes: `M:` message, `I:` info, `W:` warning, `E:` error. Example: ``` I: 2026-08-20 13:13:33.024 MQTT (events) connected to broker ``` ### `[Network]` | Key | Meaning | |-----|---------| | `Port` | The UDP port gateways connect to (defaults above). | | `Debug` | `1` dumps raw packet bytes to the log — only for diagnosing a problem. | **Firewall / NAT note:** this is the #1 "nobody can connect" cause. The port must be open for **inbound UDP** on your router/firewall, and forwarded to the reflector machine if it's behind NAT. Test with a user's gateway before chasing anything else. ### `[Block List]` — blocking a user | Key | Meaning | |-----|---------| | `File` | `BlockList.txt` — one entry per line. P25/NXDN: numeric source IDs. YSF: callsigns. M17: callsigns. | | `Time` | Seconds between checks for changes (default `5`). | | `AllowListFile` | M17 only. Whitelist file — if populated, only listed callsigns may connect. Empty = allow all. | | `AllowListTime` | M17 only. Seconds between whitelist reload checks (default `5`). | **Editing a block list does not require a restart.** Edit the file, save it, and within `Time` seconds the reflector picks it up. Blocked users' audio is dropped and the event is logged (and published over MQTT as `tx/blocked` if MQTT is on). ### `[MQTT]` — optional live status feed | Key | Meaning | |-----|---------| | `Enabled` | `1` publishes events to an MQTT broker (e.g. Mosquitto). `0` off. | | `Host` / `Port` | The broker address. Default `127.0.0.1:1883` (broker on the same machine). | | `TopicPrefix` | Base topic, e.g. `dvs-reflector/p25/reflector`. | What you get for enabling it is described in section 6. Two notes: - If the broker is down **at startup**, the reflector does not give up — it retries every 5 seconds for as long as it runs and connects as soon as the broker appears. - If you don't run a broker, set `Enabled=0`, or the log will show a `MQTT connection failed` warning at startup (the program continues fine). ### `[P25 Core]` / `[NXDN Core]` / `[YSF Core]` / `[M17 Core]` / `[DMR Core]` — linking to a hub This is the section that turns a reflector into an **edge** of a bigger network. See section 5. If you are not linking to a hub, set `Enabled=0`. | Key | Meaning | |-----|---------| | `Enabled` | `1` = this reflector links up to a hub. | | `Address` / `Port` | The hub reflector's address and port. | | `Callsign` | The identity the hub shows for this edge (e.g. `SPOKE-A`). | | `TG` | P25/NXDN/DMR: which talkgroup may cross the hub link. `0` = no core-side filter, so everything the reflector accepts is passed. Independent of `[General] TG`, which is the accept filter and applies to core-sourced traffic too. | | `Module` | M17 only: which module to register on the hub (`A` default). Local traffic on this module is relayed up, and hub traffic is distributed to local clients on this module (same-letter mapping). | | `ReceiveOnly` | `1` = this edge never transmits to the hub (listen-only). | Core links auto-reconnect. When the hub stops answering (keepalive/poll echoes stop for 90s P25/YSF, 30s NXDN/M17/DMR, or the M17 PING stream stops for 30s), the link is torn down and re-established every 10s until the hub returns. ### M17-specific: `[Modules]` — room configuration M17 uses modules (A–Z) instead of talkgroups. This section configures which modules are enabled and their descriptions. | Key | Meaning | |-----|---------| | `Modules` | Which modules to enable (e.g., `Modules = ADMSZ`). Uppercase, deduplicated, sorted A–Z. | | `DescriptionX` | Description for module X (e.g., `DescriptionA = Main Room`). | ### M17-specific: `[Security]` — callsign validation | Key | Meaning | |-----|---------| | `ValidateCallsigns` | `0` = log-only (default, safe for bridges from DMR/D-STAR/YSF). `1` = drop frames with mismatched source callsigns (pure M17 environments only). | ### NXDN-only: `[Icom Network]` — the worldwide NXCore link NXDN can optionally link to **NXCore** (the NXDN worldwide interlink network) via `flicom.nxcore.org`. If you're just running a reflector for your own group, ignore this section (it ships disabled). - Linking to NXCore **requires registration** — email the NXCore administrator (see `www.nxdninfo.com`) and request your talkgroups. Unregistered nodes are silently dropped. - `TGEnable` / `TGDisable`: a group call to `TGEnable` opens the link; a call to `TGDisable` closes it (`0` = never). `TGEnable=65000` is the common convention. ### YSF-only: `[Info]` — directory listing The YSF reflector directory lives at `dvref.com`. This section stores the ID, name, and description you get when you register. It is informational — the program itself doesn't use the values — but filling it in keeps your listing consistent with your config. --- ## 4. Day-to-day operation ### What a healthy log looks like A normal day shows only: ``` M: Adding WA9VWJ (198.51.100.24) <- someone's gateway connected M: Transmission from WA9VWJ at REPEATER to TG 9999 <- someone is talking M: Received end of transmission <- ...and stopped ``` Every 2 minutes the reflector logs packet statistics (`Stats: rx=... tx=...` — a sign it's alive and counting traffic). Warnings (`W:`) and errors (`E:`) are the lines worth reading; see the troubleshooting table. ### Talkgroup gating (P25/NXDN) Set `TG=9999` in `[General]` and the reflector will relay **only** that talkgroup and ignore everything else. Useful if the reflector is for a specific net or group. `TG=0` (or no line) passes everything. One P25 characteristic to know: P25 packets carry the destination talkgroup a moment *after* the transmission starts. With gating on, the very first packet of a P25 transmission may not reach your local users — the reflector has to learn the TG first. It's a property of the protocol, not a fault. ### Blocking a user 1. Find their ID: a `Transmission from 1234567 at REPEATER1 blocked` line in the log (or your lookup file). YSF: use their callsign. 2. Add it to `BlockList.txt` (one per line). 3. Save. Within 5 seconds the reflector reloads and starts dropping them. No restart. Unblocking is the same process in reverse. ### Keeping it running Three options, simplest first: 1. **Run it in a terminal** (`Daemon=0`) — fine for a test or a machine you have a console on, but it stops when you log out. 2. **`Daemon=1`** — the program forks itself into the background. One caveat: if you start it as **root**, it tries to switch to a user named `mmdvm` and will refuse to run if that user doesn't exist. Either create the user, or run it as a normal user. 3. **A service** — the clean way on Debian/Ubuntu. Create `/etc/systemd/system/p25reflector.service`: ```ini [Unit] Description=P25 Reflector After=network-online.target [Service] WorkingDirectory=/opt/P25Reflector ExecStart=/opt/P25Reflector/P25Reflector /opt/P25Reflector/P25Reflector.ini Restart=on-failure User=reflector [Install] WantedBy=multi-user.target ``` then `sudo systemctl enable --now p25reflector`. Put the `.ini` and `BlockList.txt` in the same directory as the binary (the block list is resolved relative to where it runs). `[Id Lookup] Name` is used verbatim, so it may be an absolute path — the hub ships `/var/lib/dvswitch/DMRIds.dat` (P25) / `/var/lib/dvswitch/NXDN.csv` (NXDN), refreshed daily. ### Backups Everything that matters is three small text files: the `.ini`, `BlockList.txt`, and your lookup file. Copy that directory (or just those files) to your NAS or a USB stick. That's the whole backup — the binary can always be rebuilt. --- ## 5. Linking reflectors together (hub and edge) — for multi-reflector operators > **Just want to *use* an existing network** (connect a hotspot, run a net)? > Skip this section and read NETWORK.md instead — it explains > DVSwitch-Net from the operator's chair. If you run more than one reflector — or want to join someone else's — the "core link" feature lets any reflector act as a **hub**, with other reflectors attached to it as **edges**. Think of it as linking your room to other rooms: the hub relays what it hears to all of its edges, and edges relay their local traffic up to the hub. - **Hub** — just a reflector with no `[ Core]` section (or `Enabled=0`). Any stock reflector is already a hub. - **Edge** — a reflector with `[ Core]` enabled, pointing at the hub's address and port. ``` gateway --> edge reflector --[native UDP]--> hub reflector --> other edges ``` Example (P25 edge): ```ini [P25 Core] Enabled=1 Address=198.51.100.24 # hub reflector's IP Port=41000 # hub reflector's port Callsign=SPOKE-A # how the hub sees this edge TG=9999 # talkgroup to relay (0 = use [General] TG) ``` Things worth knowing: - **Voice passes through unchanged** — there's no transcoding, so audio quality is identical to a direct connection. - The edge keeps the link alive with a poll every 30 seconds; a hub drops silent edges after 120 seconds. - **No loops:** traffic from the hub is injected into the edge's *local* repeaters only — it's never sent back up to the hub. - **First one wins:** if a local user and a hub user transmit at the same instant, the transmission that started first is heard; the other is dropped until it finishes. (The sample configs' `Enabled=1` pointing at `127.0.0.1` is the developers' self-test — for a real edge, point it at your actual hub.) - MQTT (if enabled) shows both paths: local transmissions report the user's callsign; hub-originated transmissions report source `Core`. SOT/EOT events are published on both the edge and the hub, so a dashboard on either end shows the whole network. Each mode links only to its own kind — a P25 edge links to a P25 hub, NXDN to NXDN, YSF to YSF, M17 to M17, DMR to DMR. There's no cross-mode linking. ### M17 linking M17 linking works like P25/NXDN/YSF but uses modules instead of talkgroups: ```ini [M17 Core] Enabled=1 Address=203.0.113.10 # hub reflector's IP Port=17000 # hub reflector's port Callsign=SPOKE-A # how the hub sees this edge (must be valid base-40) Module=A # which module to register on the hub (same-letter mapping) ReceiveOnly=0 # 1 = listen-only edge (never transmits up) ``` The edge registers with the hub as an ordinary M17 client (11-byte `CONN` handshake, `PING`/`PONG` keepalives, `DISC` on shutdown). Local traffic on `Module` is relayed up; hub traffic is distributed to local clients on the same module. The link auto-reconnects (retry every 10s, stale after 30s of hub silence). Notes: - The `Callsign` must decode as valid M17 base-40 (our hub is lenient; a strict mrefd-style server also requires an amateur-format callsign — include a digit, e.g. `EDGE7`). - **Listen-only** edges (`ReceiveOnly=1`) receive all traffic but never transmit up. Equivalent to mrefd `LSTN` registration. - **Whitelist** (`[Block List] AllowListFile`): if populated, only listed callsigns may connect. Empty = allow all. Hot-reloadable. - **GPS metadata**: if clients send GPS data in their LSF, the reflector extracts and publishes it to MQTT (`gps/position` topic). ### DMR linking DMR links to a hub as an ordinary HBP repeater — the hub cannot distinguish the edge from a normal gateway: ```ini [DMR Core] Enabled=1 Protocol=HBP # HBP (MMDVM/our hub) or IPSC (C-Bridge network) Address=203.0.113.10 # hub reflector's IP Port=31000 # hub reflector's port (HBP); C-Bridge master socket for IPSC Callsign=EDGE_A # how the hub sees this edge RadioId=310057 # DMR radio ID for the link Password=passw0rd # hub's HBP password (HBP) TG=3100 # talkgroup to relay (0 = use [General] TG) ReceiveOnly=0 # 1 = listen-only edge (never transmits up) ``` Notes: - With `Protocol=HBP` the edge registers with the hub as an ordinary DMR repeater (`MSTNAK`/`DMRD` stream). Per-slot mutual exclusion: local and core streams are exclusive on the same timeslot, while the other timeslot keeps working independently. - With `Protocol=IPSC` the edge joins a C-Bridge master (e.g. BrandMeister) as a home repeater, translating `GROUP_VOICE` between IPSC and DMRD at the link edge. - The link auto-reconnects (keepalive ping every 10s, link declared stale after 30s, retry every 10s). --- ## 6. Optional: live status with MQTT If you install an MQTT broker on the same machine (Debian/Ubuntu: `sudo apt install mosquitto` — no config needed) and set `[MQTT] Enabled=1`, the reflector publishes machine-readable events under your `TopicPrefix`: | Topic | What it means | |-------|---------------| | `tx/start` | A transmission began (source, mode, destination talkgroup, unique session id) | | `tx/end` | The transmission ended (same session id, duration in seconds) | | `tx/blocked` | A blocked user tried to talk | | `gateway/add`, `gateway/remove`, `gateway/disappeared` | Users linking / unlinking / going silent | | `watchdog/expired` | A stream stalled and was cleaned up | | `stats` | Periodic counters (`rx/tx` packets **and bytes**) | | `status/status` | Periodic reflector status blob: version, callsign, modules, uptime, pid, start time, whitelist/blocklist sizes, lookup size, M17 security counters | | `status/users` | Periodic last-heard snapshot (callsign, gateway, module, last-heard time) | | `log` | Every log line, mirrored verbatim | `gateway/add` payloads also carry the gateway's connect time, IP/port, and module (M17) so consumers don't have to parse the human-readable text. Each transmission's start and end are linked by a session id (`sid`), so anything that consumes the feed — a dashboard, a bot, your own script — can track conversations end to end. The feed is also what the bundled web dashboard uses to display live activity — see "The bundled web dashboard" below. To watch the feed yourself, the repo includes a tiny tool: ```bash timeout 30 python3 mqtt_echo.py 'dvs-reflector/#' 25 ``` This prints everything the reflector publishes for 30 seconds — a handy health check after setup. (Note: the reflector's own log lines mention two MQTT connections — `MQTT (events)` and `MQTT (log)`; that's normal. One is for the event feed, the other mirrors log lines to the `log` topic.) ### The bundled web dashboard The `dashboard/` directory is a complete live web page for your reflector: who's linked, who's transmitting right now, a last-heard list, and traffic stats — all updating by itself in the browser. It's the same dashboard the DVSwitch project publishes, with MQTT as its primary data source. **How it gets its data.** `api.php` (the dashboard's backend) reads two possible sources: a state file written by `mqtt_bridge.py` (preferred — near-real-time), or the reflector's log files (fallback — works even without MQTT, but is only as current as the logs). A badge in the page header tells you which is active: green `MQTT` or gray `LOG`. **One-time install (Debian/Ubuntu):** ```bash # 1. PHP with the modules the dashboard uses sudo apt install php-cli php-sqlite3 php-curl php-mbstring # 2. Generate a config for YOUR reflector (creates config/.php) cd dashboard php setup.php /opt/P25Reflector/P25Reflector.ini # 3. Optional but recommended: ID database for callsign hover tooltips php update_db.php # 4. Make config readable and the db/ directory writable by web + bridge chmod -R 755 config/ && chmod -R 777 db/ ``` **Serve it.** The simplest way is PHP's built-in web server, from the `dashboard/` directory: ```bash php -S 0.0.0.0:8080 ``` then open `http://your-host:8080` in a browser. (You can also drop the directory into an existing Apache/nginx site — with Apache, `http://host/Name` maps to the `?conf=Name` config.) **Feed it from MQTT (recommended).** Keep the broker running and `[MQTT] Enabled=1` in the reflector `.ini`, then run the bridge: ```bash pip3 install paho-mqtt # or: sudo apt install python3-paho-mqtt python3 mqtt_bridge.py # broker at 127.0.0.1:1883 by default ``` The bridge subscribes to `dvs-reflector/#` — which matches the shipped `TopicPrefix` values (`dvs-reflector/p25/reflector`, etc.). If you change `TopicPrefix` in an `.ini`, edit the bridge's subscription to match. If your broker is on another machine: `MQTT_BROKER=192.168.1.10 python3 mqtt_bridge.py`. Run the bridge the same way you run the reflector (terminal, or a systemd service) — the dashboard shows live data only while the bridge is up. If the bridge stops or the broker is down for more than 5 minutes, the dashboard automatically falls back to log parsing, so it never goes blank. **Multiple reflectors.** Run `setup.php` once per reflector to create one config per install, then switch between them with the **Switch** menu in the page (or open `http://host:8080/index.php?conf=Name` directly). The hub ships configs for `P25Reflector`, `NXDNReflector`, `YSFReflector` and `M17Reflector` (each defines `REFLECTOR_MODE` = `P25`/`NXDN`/`YSF`/`M17`). Each profile now **filters the consolidated MQTT state to its own mode** — selecting "M17 Reflector (Hub)" shows only M17 last-heard/gateways/transmit. The M17 profile's log fallback parses the M17 log format (`Transmission started from … at …`) so it works even if the bridge is down. The dashboard has its own README (`dashboard/README.md`) with the full feature list and credits. **Credits and gateway modules.** The page footer is mode-aware, so the attribution reflects the origin of the code behind each reflector: P25/NXDN/YSF show `Reflector by DVSwitch, core by G4KLX` (they are built on G4KLX's reflector cores), while M17 shows `Reflector by DVSwitch` (the M17 reflector is essentially all DVSwitch code). The **Gateways** panel now shows the module a client is logged into — meaningful for M17, where a client registers on a specific module (e.g. `E`); P25/NXDN/YSF gateways link without a module and show `—`. This uses the `module` field the reflectors publish on `gateway/add` (see `CUSTOMIZATIONS.md` / `docs/dashboard-api.md`). **Pushing stats to a collector (optional).** The bridge can also POST heartbeats, live TX events and gateway lists to an external collection server (P25_NA-style contract). Outbound-only, off by default, configured in `bridge.ini` — see `docs/COLLECTOR-API.md`. Pushes survive outages: failed payloads are retried with backoff and kept in a dead-letter ring (`db/push_deadletter.json`, replayable with `tools/replay_deadletter.py`); live queue counters appear on MQTT topic `dvs-reflector/bridge/status`. **URFd-style HTTP API (optional).** The bridge can also serve a JSON report over HTTP — the same kind of monitoring API URFd exposes — without any extra daemon. Enable it in `bridge.ini`: ```ini [api] port = 8090 ; 0 disables (default) bind = 127.0.0.1 ; use 0.0.0.0 to expose to remote dashboards redact = true ; blank client IP/port for public exposure mask_callsigns = false ; optionally also mask callsigns (off by default) ``` Then: | Endpoint | Returns | |----------|---------| | `GET /` `/api` `/report` `/status` | JSON report; add `?mode=p25|nxdn|ysf|m17` for one mode, omit for all modes keyed by mode | | `GET /api/config` | URFd-parity reflector config (`reflector.name`, `description`, `modules`, `version`, `date`) | | `GET /api/history` | URFd-parity last-heard (`my`, `ur`, `rpt1`, `rpt2`, `module`, `protocol`, `duration`); `?limit=N` | | `GET /health` | `{"status":"ok"}` | | `GET /openapi.json` | OpenAPI 3.1.0 specification of this API (machine-readable) | | anything else | `404 {"error":"not found"}` | `/api/config` and `/api/history` mirror the live URFd API (e.g. URF106) so URFd-style dashboards work against DVS-Reflector unchanged. The API is served on plain HTTP port 8080 (matching URF106) through nginx; the human dashboard is on 443 (TLS) and port 80 redirects to it — see `deploy/nginx-hub.conf`. `/openapi.json` describes the whole surface (report, URFd-parity, health) and is served alongside the URFd endpoints so tooling can consume the same API both in its URFd-compatible form and as a documented OpenAPI contract. The per-mode report includes version, callsign, name, mode, modules + module descriptions (M17), uptime, pid, start time, whitelist/blocklist sizes, lookup sizes, M17 security counters, the identity config summary, active streams, connected clients (with IP, port, connect time, module), last-heard, and rx/tx packet+byte counters. **Feeding the dashboard and dvsref.** The bridge consolidates all five reflectors and serves the consolidated report; it also pushes heartbeats, snapshots, live TX events and gateway syncs to a collector (dvsref) — DMR/M17 are reported alongside P25/NXDN/YSF (see `docs/COLLECTOR-API.md`). --- ## 7. Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| | Nobody can link / no audio at all | Firewall/NAT blocking the UDP port | Open the port (inbound UDP) on the router and host firewall; test with one gateway | | Users link but no one hears them | TG gating excludes their talkgroup (P25/NXDN) or wrong module (M17) | Check `[General] TG=` (P25/NXDN) or `[Modules] Modules=` (M17) | | P25: very start of a transmission is clipped | Normal with TG gating (protocol learns the TG mid-TX) | Nothing to fix; it's inherent to P25 gating | | `W: MQTT connection failed` at startup | No broker running | `sudo apt install mosquitto`, or set `MQTT Enabled=0` | | Log file not where you expected | Relative `FilePath` resolves against the working directory | Use an absolute path in `[Log] FilePath` | | `Could not get the mmdvm user, exiting` | `Daemon=1` started as root, no `mmdvm` user | Create the user, run as a normal user, or use a systemd service | | Repeated `core link`/hub connection messages | Edge configured but hub unreachable (or you don't have one) | Fix `Address`/`Port` in `[ Core]`, or set `Enabled=0` | || Two users transmit at the same time — one side is silent | Normal: first-wins mutual exclusion drops the later transmission | Nothing to fix; the dropped side resumes when the other ends | | IDs show as numbers, no callsigns | Lookup file missing or stale | Provide `DMRIds.dat` (P25) / `NXDN.csv` (NXDN); refresh periodically | | Blocked user still getting through | Block list not reloaded / wrong ID format | Wait 5 s after saving; P25/NXDN use numeric ID, YSF/M17 use callsign; check `[Block List] File` path | || Dashboard header badge shows gray `LOG` instead of green `MQTT` | Bridge not running, broker down, or MQTT disabled in the `.ini` | Start `mqtt_bridge.py`, check mosquitto is up and `[MQTT] Enabled=1` | || Dashboard says "No configuration found" | `setup.php` was never run for this reflector | `php setup.php /path/to/your.ini`, then refresh | || M17: "Callsign spoof" in log | Bridge from DMR/D-STAR/YSF with different callsign | Set `[Security] ValidateCallsigns=0` (default) — log-only, not blocking | || M17: "Encrypted stream rejected" | Client sending encrypted audio | Reflector only relays clear-mode voice; check client encryption settings | || M17: "CRC error" in log | Corrupt frame from client or network | Usually transient; if persistent, check network quality | || M17: "Reserved SID rejected" | Client sending SID 0x0000 or 0xFFFF | Client bug; update client firmware | || Need more detail | — | Set `[Network] Debug=1` for raw packet dumps (turn it off afterwards — it's noisy) | If a symptom isn't here: read the `W:` and `E:` lines in the log file (`-.log`). They are usually specific about what failed. --- ## 8. A word about the hobby You are the control operator of this machine. A few habits that keep everyone happy: - Make sure users identify per the regulations — a reflector is a "gateway" into your station's network, and the person keying up is responsible for their ID, but if you're running a public node, a courtesy announcement or net script helps. - If you open it to the public, publish the connection details (address, port, talkgroup) where your users will find them — and say what TG/room it is. - Blocklist is your tool: repeat offenders can be dropped without a restart, and unblocked just as easily. - Keep a copy of your `.ini` and `BlockList.txt` — the whole config fits in two small text files. 73 and enjoy the reflectors.