g4klx/ircDDBGateway
1
0
Fork 0
mirror of https://github.com/g4klx/ircDDBGateway.git synced 2026-04-03 03:14:47 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity
ircDDBGateway/CONFIGURATION.md
Andy Taylor fc571c1e13 Fix MQTT implementation, align with DStarGateway, and add documentation 
MQTT Implementation (aligned with DStarGateway / MMDVMHost):
- Rewrite MQTTConnection with mosquitto_loop_stop() fix to prevent
  background thread zombies on shutdown
- Add MQTT authentication support (mqttAuth, mqttUsername, mqttPassword)
- Add configurable client name (mqttName) used as topic prefix
- Use PID-based client IDs (avoids time_t truncation on 32-bit ARM)
- Use std::string interface throughout (no wxString in MQTT layer)
- Align JSON link status fields with DStarGateway (repeater/reflector/
  protocol/reason/action) for dashboard compatibility

Shutdown Safety:
- Add MQTTLogFinalise() calls to both daemon (IRCDDBGatewayAppD::run)
  and GUI (IRCDDBGatewayApp::OnExit) shutdown paths to ensure clean
  MQTT disconnection and thread cleanup before process exit

JSON Status Events:
- Update all ~30 WriteJSON call sites across DPlus, DExtra, DCS, and
  CCS protocol handlers to use new function signatures
- Simplify IRCDDBGatewayThread::writeJSONStatus to delegate to
  WriteJSONStatus

Config Parser Hardening:
- Add empty-line crash guard to IRCDDBGatewayConfig, TimerControlConfig,
  and TimeServerConfig parsers (str.IsEmpty() check before GetChar)

Documentation:
- Add MQTT.md with topic structure, JSON examples, and troubleshooting
- Add CONFIGURATION.md with full reference for all config files
- Add BUILD.md with build parameters and dependency information
- Add linux/ example configs for ircddbgateway, timeserver, timercontrol
- Modernise README.md with feature list and DStarGateway recommendation
2026-03-08 21:34:45 +00:00

341 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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). |
Reference in a new issue View git blame Copy permalink