# MQTT Support for DStarRepeater

DStarRepeater can optionally publish log messages and repeater status to
an MQTT broker, providing the same kind of live telemetry that MMDVMHost
offers. This makes it possible to monitor D-Star repeater activity from
dashboards, home-automation systems, or any MQTT client.

**MQTT support is entirely optional.** When built without the MQTT flag
the compiled binary is identical to the tree before MQTT was added — no
MQTT code is included and no additional libraries are required.

## Building

### Without MQTT (default)

```
make
```

Produces the same `dstarrepeaterd` as the original codebase. No
`libmosquitto` dependency.

### With MQTT

Install `libmosquitto-dev` first:

```
sudo apt-get install libmosquitto-dev
```

Then build with the `MQTT` flag:

```
make MQTT=1
```

This adds `-DMQTT` to the compiler flags and links against
`-lmosquitto`. All MQTT code paths are guarded by
`#if defined(MQTT)` / `#endif`, so the flag acts as a clean on/off
switch.

## Configuration

Add the following keys to your `dstarrepeater` configuration file
(the same flat key=value format used by all other settings):

```
mqttHost=127.0.0.1
mqttPort=1883
mqttAuth=0
mqttUsername=
mqttPassword=
mqttKeepalive=60
mqttName=dstar-repeater
```

| Key             | Default           | Description                                        |
|-----------------|-------------------|----------------------------------------------------|
| `mqttHost`      | `127.0.0.1`       | MQTT broker hostname or IP address                 |
| `mqttPort`      | `1883`            | MQTT broker port                                   |
| `mqttAuth`      | `0`               | Enable authentication (`0` = off, `1` = on)        |
| `mqttUsername`   | *(empty)*         | Username when `mqttAuth=1`                         |
| `mqttPassword`  | *(empty)*         | Password when `mqttAuth=1`                         |
| `mqttKeepalive` | `60`              | Keepalive interval in seconds                      |
| `mqttName`      | `dstar-repeater`  | Client name; also used as the MQTT topic prefix    |

If `mqttHost` is left empty, MQTT is disabled at runtime even when
compiled in.

## MQTT Topics

All topics are automatically prefixed with the value of `mqttName`.
For example, with the default name `dstar-repeater`:

### `dstar-repeater/log`

Timestamped log messages, filtered by severity. The format matches the
log file output:

```
M: 2025-03-08 14:22:01: Starting D-Star Repeater - 20180403
M: 2025-03-08 14:22:01: Using wxWidgets 3.0.5 on Linux 6.1.21-v8+
M: 2025-03-08 14:22:01: Callsign set to "GB7XX  B", gateway set to "GB7XX  G"
M: 2025-03-08 14:22:01: Modem type set to "MMDVM"
I: 2025-03-08 14:22:01: MQTT connected to 127.0.0.1:1883 as dstar-repeater
M: 2025-03-08 14:22:01: Starting the D-Star repeater thread
M: 2025-03-08 14:22:01: Poll text set to "linux_mmdvm-20180403"
```

Log levels (highest to lowest):

| Letter | Level         | Numeric |
|--------|---------------|---------|
| `F`    | Fatal         | 6       |
| `E`    | Error         | 5       |
| `W`    | Warning       | 4       |
| `I`    | Info          | 3       |
| `M`    | Message       | 2       |
| `D`    | Debug         | 1       |

Only messages at or above the configured threshold are published. The
default threshold is **2** (Message level), matching MMDVMHost behaviour.

### `dstar-repeater/status`

A JSON object published once per second with the current repeater state.
This is the D-Star equivalent of MMDVMHost's status output:

**Idle (no traffic):**
```json
{
  "myCall1": "",
  "myCall2": "",
  "yourCall": "",
  "rptCall1": "",
  "rptCall2": "",
  "tx": false,
  "rxState": "listening",
  "rptState": "listening",
  "ber": 0.0,
  "text": "",
  "status1": "",
  "status2": "",
  "status3": "",
  "status4": "",
  "status5": ""
}
```

**During an RF transmission:**
```json
{
  "myCall1": "MW0MWZ  ",
  "myCall2": "    ",
  "yourCall": "CQCQCQ  ",
  "rptCall1": "GB7XX  B",
  "rptCall2": "GB7XX  G",
  "tx": true,
  "rxState": "process_data",
  "rptState": "valid",
  "ber": 1.3,
  "text": "Hello from Pi-Star",
  "status1": "",
  "status2": "",
  "status3": "",
  "status4": "",
  "status5": ""
}
```

**During a network (gateway) transmission:**
```json
{
  "myCall1": "G4KLX   ",
  "myCall2": "    ",
  "yourCall": "GB7XX  B",
  "rptCall1": "GB7XX  B",
  "rptCall2": "GB7XX  G",
  "tx": true,
  "rxState": "listening",
  "rptState": "network",
  "ber": 0.0,
  "text": "",
  "status1": "",
  "status2": "",
  "status3": "",
  "status4": "",
  "status5": ""
}
```

#### Status Field Reference

| Field      | Type    | Description                                               |
|------------|---------|-----------------------------------------------------------|
| `myCall1`  | string  | Transmitting station's callsign (8 chars, space-padded)   |
| `myCall2`  | string  | Transmitting station's short suffix (4 chars)             |
| `yourCall` | string  | Destination callsign (`CQCQCQ` for CQ calls)             |
| `rptCall1` | string  | Repeater callsign with module letter                      |
| `rptCall2` | string  | Gateway callsign                                          |
| `tx`       | boolean | `true` when the repeater is transmitting                  |
| `rxState`  | string  | `listening`, `process_data`, or `process_slow_data`       |
| `rptState` | string  | See repeater states below                                 |
| `ber`      | float   | Bit Error Rate as a percentage (0.0 when idle)            |
| `text`     | string  | Slow-data text message (if any)                           |
| `status1`–`status5` | string | User-configured status text messages             |

#### Repeater States (`rptState`)

| Value          | Meaning                                              |
|----------------|------------------------------------------------------|
| `listening`    | Idle, waiting for traffic                            |
| `valid`        | Receiving valid RF traffic                           |
| `valid_wait`   | Valid RF transmission ended, waiting for ack window  |
| `invalid`      | Receiving RF traffic that failed validation          |
| `invalid_wait` | Invalid RF ended, waiting                            |
| `timeout`      | Transmission timed out                               |
| `timeout_wait` | Timeout ended, waiting                               |
| `network`      | Receiving traffic from the gateway/network           |
| `shutdown`     | Repeater is shut down                                |

### `dstar-repeater/json`

Event-driven JSON messages published at D-Star state transitions, in the
format expected by [Display-Driver](https://github.com/MW0MWZ/Display-Driver).
This means DStarRepeater can drive an OLED/TFT display via MQTT with no
modifications to Display-Driver.

Unlike the `status` topic (polled once per second), the `json` topic only
publishes when something actually changes — a transmission starts, ends,
or is lost.

**RF transmission starts:**
```json
{"D-Star":{"action":"start","source_cs":"MW0MWZ  ","source_ext":"    ","destination_cs":"CQCQCQ  ","reflector":"GB7XX  G","source":"rf"}}
```

**Network transmission starts:**
```json
{"D-Star":{"action":"start","source_cs":"G4KLX   ","source_ext":"    ","destination_cs":"GB7XX  B","reflector":"GB7XX  G","source":"net"}}
```

**Transmission ends normally:**
```json
{"D-Star":{"action":"end"}}
```

**Transmission lost (watchdog timeout):**
```json
{"D-Star":{"action":"lost"}}
```

**Return to idle (sent after every end/lost):**
```json
{"MMDVM":{"mode":"idle"}}
```

**BER update (published once per second during active RF):**
```json
{"BER":{"mode":"D-Star","value":1.3}}
```

#### Display-Driver Compatibility

These messages use the exact same JSON keys and structure that
Display-Driver expects. If your `mqttName` is set to `dstar-repeater`,
configure Display-Driver to subscribe to `dstar-repeater/json`.

Display-Driver dispatches each top-level key to a specific parser:

| Top-level key | Display-Driver parser | When published                           |
|---------------|----------------------|------------------------------------------|
| `D-Star`      | `parseDStar()`       | Transmission start, end, or lost         |
| `BER`         | `parseBER()`         | Once per second during active RF         |
| `MMDVM`       | `parseMMDVM()`       | On return to idle                        |

## Subscribing to MQTT Output

Use any MQTT client to subscribe. For example, with `mosquitto_sub`:

```bash
# Follow all DStarRepeater topics:
mosquitto_sub -h 127.0.0.1 -t "dstar-repeater/#"

# Log messages only:
mosquitto_sub -h 127.0.0.1 -t "dstar-repeater/log"

# Status JSON only:
mosquitto_sub -h 127.0.0.1 -t "dstar-repeater/status"

# Display-Driver-compatible events:
mosquitto_sub -h 127.0.0.1 -t "dstar-repeater/json"

# Pretty-print status with jq:
mosquitto_sub -h 127.0.0.1 -t "dstar-repeater/status" | jq .

# Pretty-print Display-Driver events with jq:
mosquitto_sub -h 127.0.0.1 -t "dstar-repeater/json" | jq .
```

## Comparison with MMDVMHost

This implementation follows the same conventions as MMDVMHost's MQTT
support:

- Same `CMQTTConnection` class wrapping `libmosquitto`
- Same topic-prefix convention (`{name}/topic`)
- Same log-level filtering and format
- Same PID-based client ID scheme (avoids the `time_t` truncation
  issue on 32-bit ARM)
- Same configuration key names (`mqttHost`, `mqttPort`, etc.)
- Same QoS default (EXACTLY_ONCE / QoS 2)

The key difference is that DStarRepeater is a **publish-only** client —
it does not subscribe to any MQTT topics or accept remote commands via
MQTT. The configuration file format also differs: DStarRepeater uses
flat `key=value` pairs rather than MMDVMHost's INI-style `[MQTT]`
section.

## Troubleshooting

**"Unable to start MQTT connection"** in logs:
- Check that Mosquitto (or another MQTT broker) is running on the
  configured host and port
- Verify credentials if `mqttAuth=1`
- Check firewall rules if connecting to a remote broker

**No messages appearing:**
- Confirm the binary was built with `make MQTT=1`
- Check that `mqttHost` is not empty in the config file
- Verify the broker is accessible: `mosquitto_pub -h 127.0.0.1 -t test -m hello`

**Log messages missing but status works:**
- The log level threshold may be filtering them out. Lower-priority
  messages (Debug, Trace) are not published by default.