Skip to content
This repository was archived by the owner on Mar 10, 2026. It is now read-only.

Fix MQTT implementation, align with DStarGateway, and add documentation #85

Open
MW0MWZ wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fix MQTT implementation, align with DStarGateway, and add documentation #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions BUILD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,3 +83,15 @@ This would build and install all the programs in this repo using 4 threads
(parallel build jobs), in release mode (no debug symbols) with a modified
configuration directory.

### MQTT Dependency

MQTT support is always compiled in. Install `libmosquitto-dev` before
building:

```sh
sudo apt install libmosquitto-dev
```

See [MQTT.md](MQTT.md) for configuration, topic structure, and JSON format.
To disable MQTT at runtime, leave `mqttAddress` empty in the config file.

340 changes: 340 additions & 0 deletions CONFIGURATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,340 @@
# ircDDBGateway Configuration Reference

> **Note:** The config parser treats any line beginning with `#` as a
> comment, and blank lines are skipped. Use `ircddbgateway.example` as
> your starting point for a clean config.

**Config file location:** `/etc/ircddbgateway`
(or `/etc/ircddbgateway_<name>` when using the `-name` command line option)

**Format:** `key=value` — one setting per line, no spaces around the `=`.
Boolean values use `0` for off/false and `1` for on/true.

---

## Gateway Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `gatewayType=0` | `0` | Gateway type — see [Gateway Types](#gateway-types) below. |
| `gatewayCallsign=` | *(empty)* | Gateway callsign, padded to 8 characters (e.g. `GB7XX G`). The final character is always `G` for gateway. |
| `gatewayAddress=` | *(empty)* | IP address to bind for gateway services. Leave empty for automatic. |
| `icomAddress=172.16.0.20` | `172.16.0.20` | Local IP address for Icom repeater stack communication. |
| `icomPort=20000` | `20000` | UDP port for Icom repeater stack communication. |
| `hbAddress=127.0.0.1` | `127.0.0.1` | IP address of the homebrew repeater (DStarRepeater). |
| `hbPort=20010` | `20010` | UDP port for homebrew repeater communication. |
| `latitude=0.000000` | `0.0` | Gateway latitude in decimal degrees (positive = North). |
| `longitude=0.000000` | `0.0` | Gateway longitude in decimal degrees (positive = East). |
| `description1=` | *(empty)* | First line of the gateway description (shown on reflector dashboards). |
| `description2=` | *(empty)* | Second line of the gateway description. |
| `url=` | *(empty)* | URL for the gateway (shown on reflector dashboards). |

### Gateway Types

| Value | Type | Description |
|:-----:|------|-------------|
| `0` | Repeater | Standard repeater gateway |
| `1` | Hotspot | Personal hotspot gateway |
| `2` | Dongle | DV Dongle/AMBE dongle gateway |
| `3` | STARnet | STARnet-only server (no repeater) |

---

## Repeater Settings (1–4)

Up to four repeater modules can be configured. Each module uses a numeric suffix (`1` through `4`). The settings below show the suffix `1` — replace with `2`, `3`, or `4` for additional modules.

| Setting | Default | Description |
|---------|---------|-------------|
| `repeaterCall1=` | *(empty)* | Repeater callsign, 7 characters (e.g. `GB7XX`). Leave empty to disable this module. |
| `repeaterBand1= ` | ` ` *(space)* | Module letter (`A`, `B`, `C`, `D`, or `E`). Combined with callsign to form the 8-character repeater ID (e.g. `GB7XX B`). |
| `repeaterType1=0` | `0` | Repeater hardware type — see [Hardware Types](#hardware-types) below. |
| `repeaterAddress1=127.0.0.1` | `127.0.0.1` | IP address of the repeater hardware or DStarRepeater instance. |
| `repeaterPort1=20011` | `20011` | UDP port for repeater communication. Default ports are 20011–20014 for modules 1–4. |
| `reflector1=` | *(empty)* | Default reflector to link at startup (e.g. `REF001 C` or `XRF012 A`). |
| `atStartup1=0` | `0` | `1` = link to the default reflector at startup. |
| `reconnect1=0` | `0` | Reconnect behaviour — see [Reconnect Values](#reconnect-values) below. |
| `frequency1=0.00000` | `0.0` | Operating frequency in MHz (e.g. `438.50000`). Reported to reflector directories. |
| `offset1=0.0000` | `0.0` | Repeater offset in MHz (e.g. `-7.6000`). |
| `rangeKms1=0.000` | `0.0` | Coverage range in kilometres. |
| `latitude1=0.000000` | `0.0` | Repeater latitude in decimal degrees. |
| `longitude1=0.000000` | `0.0` | Repeater longitude in decimal degrees. |
| `agl1=0.000` | `0.0` | Antenna height above ground level in metres. |
| `description1_1=` | *(empty)* | First line of the repeater module description. |
| `description1_2=` | *(empty)* | Second line of the repeater module description. |
| `url1=` | *(empty)* | URL for this repeater module. |
| `band1_1=0` | `0` | Band data byte 1 (used by Icom stacks). |
| `band1_2=0` | `0` | Band data byte 2. |
| `band1_3=0` | `0` | Band data byte 3. |

### Hardware Types

| Value | Type | Description |
|:-----:|------|-------------|
| `0` | Homebrew | DStarRepeater-based homebrew repeater |
| `1` | Icom | Icom ID-RP2C repeater stack |
| `2` | Dummy | Dummy/test repeater (no hardware) |

### Reconnect Values

| Value | Behaviour |
|:-----:|-----------|
| `0` | Never — once unlinked, stay unlinked |
| `1` | Fixed — reconnect immediately to the default reflector |
| `2` | After 5 minutes |
| `3` | After 10 minutes |
| `4` | After 15 minutes |
| `5` | After 20 minutes |
| `6` | After 25 minutes |
| `7` | After 30 minutes |
| `8` | After 60 minutes |
| `9` | After 90 minutes |
| `10` | After 120 minutes |
| `11` | After 180 minutes |

---

## ircDDB Network Settings (1–4)

Up to four ircDDB networks can be configured simultaneously. Networks 1 and 2 are enabled by default. The settings below show network `1` — networks 2–4 use `2`, `3`, or `4` appended to the key names (e.g. `ircddbHostname2`).

> **Note:** Network 1 uses key names without a numeric suffix (e.g.
> `ircddbHostname` not `ircddbHostname1`).

| Setting | Default | Description |
|---------|---------|-------------|
| `ircddbEnabled=1` | `1` (nets 1–2), `0` (nets 3–4) | `1` = enable this ircDDB network. |
| `ircddbHostname=group1-irc.ircddb.net` | `group1-irc.ircddb.net` (net 1), `rr.openquad.net` (net 2), *(empty)* (nets 3–4) | Hostname of the ircDDB server. |
| `ircddbUsername=` | *(empty)* | Username for ircDDB authentication (usually your callsign). |
| `ircddbPassword=` | *(empty)* | Password for ircDDB authentication. |

---

## Protocol and Service Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `aprsEnabled=0` | `0` | `1` = enable DPRS-to-APRS-IS gateway. Requires an APRS-IS connection. |
| `dextraEnabled=1` | `1` | `1` = enable DExtra (XRF) reflector protocol. |
| `dextraMaxDongles=5` | `5` | Maximum number of DExtra dongle connections allowed. |
| `dplusEnabled=0` | `0` | `1` = enable D-Plus (REF) reflector protocol. Requires registration. |
| `dplusMaxDongles=5` | `5` | Maximum number of D-Plus dongle connections allowed. |
| `dplusLogin=` | *(empty)* | Callsign for D-Plus authentication. Must be registered with US Trust. |
| `dcsEnabled=1` | `1` | `1` = enable DCS reflector protocol. |
| `ccsEnabled=1` | `1` | `1` = enable CCS7 call routing. |
| `ccsHost=CCS704 ` | `CCS704 ` | CCS server callsign (8 characters, space-padded). |
| `xlxEnabled=1` | `1` | `1` = enable XLX reflector protocol. |
| `xlxHostsFileUrl=...` | `http://xlxapi.rlx.lu/api.php?do=GetXLXDMRMaster` | URL to download the XLX hosts list. |

---

## STARnet Settings (1–5)

Up to five STARnet digital voice groups can be configured. Each group uses a numeric suffix (`1` through `5`).

| Setting | Default | Description |
|---------|---------|-------------|
| `starNetBand1=` | *(empty)* | Module letter for this STARnet group (e.g. `A`). Leave empty to disable. |
| `starNetCallsign1=` | *(empty)* | Callsign for the STARnet group (8 characters, e.g. `STN001 L`). |
| `starNetLogoff1=` | *(empty)* | Callsign to send to log off from the group. |
| `starNetInfo1=` | *(empty)* | Info text for the group. |
| `starNetPermanent1=` | *(empty)* | Comma-separated list of callsigns permanently subscribed to the group. |
| `starNetUserTimeout1=300` | `300` | User inactivity timeout in seconds. Users are removed from the group after this period. |
| `starNetGroupTimeout1=300` | `300` | Group inactivity timeout in seconds. The group is deactivated after this period. |
| `starNetCallsignSwitch1=0` | `0` | Callsign display mode — see [Callsign Switch Values](#callsign-switch-values) below. |
| `starNetTXMsgSwitch1=1` | `1` | `1` = transmit group status messages. |
| `starNetReflector1=` | *(empty)* | Reflector to link the STARnet group to (DExtra protocol). |

### Callsign Switch Values

| Value | Mode | Description |
|:-----:|------|-------------|
| `0` | Group Callsign | Show the group callsign in headers |
| `1` | User Callsign | Show the originating user's callsign in headers |

---

## Remote Control

| Setting | Default | Description |
|---------|---------|-------------|
| `remoteEnabled=0` | `0` | `1` = enable the remote control interface. |
| `remotePassword=` | *(empty)* | Password for remote control authentication. |
| `remotePort=0` | `0` | UDP port for remote control. `0` = disabled. |

---

## Miscellaneous

| Setting | Default | Description |
|---------|---------|-------------|
| `language=0` | `0` | Language for voice announcements — see [Language Values](#language-values) below. |
| `infoEnabled=1` | `1` | `1` = enable the `I` (info) callsign command. |
| `echoEnabled=1` | `1` | `1` = enable the echo (parrot) test feature. |
| `logEnabled=0` | `0` | `1` = enable logging to file. |
| `dratsEnabled=0` | `0` | `1` = enable D-RATS data transfer support. |
| `dtmfEnabled=1` | `1` | `1` = enable DTMF command decoding. |

### Language Values

| Value | Language |
|:-----:|----------|
| `0` | English (UK) |
| `1` | Deutsch |
| `2` | Dansk |
| `3` | Francais |
| `4` | Italiano |
| `5` | Polski |
| `6` | English (US) |
| `7` | Espanol |
| `8` | Svenska |
| `9` | Nederlands (NL) |
| `10` | Nederlands (BE) |
| `11` | Norsk |
| `12` | Portugues |

---

## GPSD Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `gpsdEnabled=0` | `0` | `1` = enable GPSD support for automatic position updates. |
| `gpsdAddress=127.0.0.1` | `127.0.0.1` | GPSD server address. |
| `gpsdPort=2947` | `2947` | GPSD server port. |

---

## MQTT Settings

*MQTT is always compiled in. To disable at runtime, leave `mqttAddress` empty. See [MQTT.md](MQTT.md) for full details on topics, JSON format, and troubleshooting.*

| Setting | Default | Description |
|---------|---------|-------------|
| `mqttAddress=127.0.0.1` | `127.0.0.1` | MQTT broker hostname or IP address. Set to empty to disable MQTT at runtime even when compiled in. |
| `mqttPort=1883` | `1883` | MQTT broker port. |
| `mqttKeepalive=60` | `60` | Keepalive interval in seconds. |
| `mqttAuth=0` | `0` | `1` = authenticate with the broker using `mqttUsername` and `mqttPassword`. |
| `mqttUsername=mmdvm` | `mmdvm` | Broker username (when `mqttAuth=1`). |
| `mqttPassword=mmdvm` | `mmdvm` | Broker password (when `mqttAuth=1`). |
| `mqttName=ircddb-gateway` | `ircddb-gateway` | Client name and topic prefix for all published messages. |

### MQTT Topics

With the default `mqttName` of `ircddb-gateway`, the following topics are published:

| Topic | Content |
|-------|---------|
| `ircddb-gateway/log` | Timestamped log messages. |
| `ircddb-gateway/json` | JSON link status events (linking, unlinking, relinking, failed, status). |
| `ircddb-gateway/aprs-gateway/aprs` | APRS position data from the DPRS gateway. |

---

## Window Position (GUI only)

| Setting | Default | Description |
|---------|---------|-------------|
| `windowX=-1` | `-1` | Window X position. `-1` for system default. |
| `windowY=-1` | `-1` | Window Y position. `-1` for system default. |

---

# Companion Program Configuration

The following companion programs have their own separate config files.
The same `key=value` format and comment rules apply. Example configs
are provided in `linux/`.

---

## TimeServer

**Config file:** `/etc/timeserver`
(or `/etc/timeserver_<name>` when using the `-name` option)

**Example:** [linux/timeserver.example](linux/timeserver.example)

The TimeServer transmits time announcements to one or more repeater modules at a configurable interval.

| Setting | Default | Description |
|---------|---------|-------------|
| `callsign=` | *(empty)* | Gateway callsign (8 characters, e.g. `GB7XX G`). |
| `sendA=0` | `0` | `1` = send time announcements to module A. |
| `sendB=0` | `0` | `1` = send time announcements to module B. |
| `sendC=0` | `0` | `1` = send time announcements to module C. |
| `sendD=0` | `0` | `1` = send time announcements to module D. |
| `sendE=0` | `0` | `1` = send time announcements to module E. |
| `address=127.0.0.1` | `127.0.0.1` | Address of the ircDDBGateway instance. |
| `language=0` | `0` | Announcement language — see [TimeServer Language Values](#timeserver-language-values) below. |
| `format=0` | `0` | Announcement format — see [Format Values](#format-values) below. |
| `interval=0` | `0` | Announcement interval — see [Interval Values](#interval-values) below. |
| `windowX=-1` | `-1` | Window X position (GUI only). |
| `windowY=-1` | `-1` | Window Y position (GUI only). |

### TimeServer Language Values

| Value | Language |
|:-----:|----------|
| `0` | English (UK) 1 |
| `1` | English (UK) 2 |
| `2` | English (US) 1 |
| `3` | English (US) 2 |
| `4` | Deutsch 1 |
| `5` | Deutsch 2 |
| `6` | Francais |
| `7` | Nederlands |
| `8` | Svenska |
| `9` | Espanol |
| `10` | Norsk |
| `11` | Portugues |

### Format Values

| Value | Format | Description |
|:-----:|--------|-------------|
| `0` | Voice Time | Voice announcement of the current time |
| `1` | Voice All | Voice announcement of time, date, and location |
| `2` | Text Time | Slow-data text with the current time |

### Interval Values

| Value | Interval |
|:-----:|----------|
| `0` | Every 15 minutes |
| `1` | Every 30 minutes |
| `2` | Every 60 minutes |

---

## TimerControl

**Config file:** `/etc/timercontrol`
(or `/etc/timercontrol_<name>` when using the `-name` option)

**Example:** [linux/timercontrol.example](linux/timercontrol.example)

TimerControl provides scheduled reflector linking — automatically linking and unlinking repeater modules at configured times.

| Setting | Default | Description |
|---------|---------|-------------|
| `address=` | *(empty)* | Address of the ircDDBGateway remote control interface. |
| `port=0` | `0` | Port of the ircDDBGateway remote control interface. Must match `remotePort` in the gateway config. |
| `password=` | *(empty)* | Password for the remote control interface. Must match `remotePassword` in the gateway config. |
| `delay=0` | `0` | `1` = delay scheduled actions by a random amount to avoid all repeaters acting simultaneously. |
| `windowX=-1` | `-1` | Window X position (GUI only). |
| `windowY=-1` | `-1` | Window Y position (GUI only). |

---

## Programs Without Config Files

The following companion programs take their parameters entirely from
command line arguments and do not use config files:

| Program | Description |
|---------|-------------|
| `texttransmit` | Sends a slow-data text message to a repeater module. |
| `voicetransmit` | Sends a voice announcement file to a repeater module. |
| `aprstransmit` | Sends APRS data to the gateway. |
| `remotecontrol` | GUI remote control client (uses wxWidgets config storage, not a text file). |
Loading