Skip to content

README.md

Latest commit

 

History

History
284 lines (196 loc) · 10.1 KB

README.md

File metadata and controls

284 lines (196 loc) · 10.1 KB
Raw

mqtt-aprs

mqtt-aprs bridges APRS-IS traffic into MQTT topics and can optionally send APRS packets back to APRS-IS from a dedicated MQTT command topic.

The program is designed for unattended service use:

  • It validates configuration before startup.
  • It reconnects to MQTT and APRS-IS with retry loops.
  • It can publish either structured APRS fields or raw packets.
  • It publishes a retained MQTT presence topic for service monitoring.
  • It supports an explicit, opt-in MQTT-to-APRS transmit path.

This project uses aprslib for APRS-IS connectivity and APRS parsing.

It is a descendant of the original mqtt-owfs-temp work by Kyle Gordon and the mqtt-aprs fork by eloebl.

Documentation Map

  • This README is the operator guide for installation, configuration, startup, and troubleshooting.
  • docs/PROGRAM_REFERENCE.md is the full runtime and code-structure reference.
  • mqtt-aprs.cfg.example is the annotated sample configuration.
  • mqtt-aprs.service is the bundled systemd unit for unattended service deployment.
  • mqtt-aprs.default is a legacy defaults file retained in the repository for compatibility history; the bundled systemd unit does not currently consume it.

Features

  • Receive APRS-IS packets and publish them to MQTT.
  • Publish structured fields such as position, altitude, distance, icon, telemetry, and message text.
  • Fall back to raw packet publishing when parsing is disabled or a packet is unsupported.
  • Retry APRS-IS connections across common APRS ports.
  • Expose a config validation mode with --check-config.
  • Optionally transmit APRS packets from MQTT through APRS-IS.

Data Flow

  1. The service connects to the MQTT broker.
  2. It publishes RF/<MQTT_SUBTOPIC>/state with 1 while online and 0 when stopping.
  3. It connects to APRS-IS and consumes packets.
  4. If APRS_PROCESS = True, parsed fields are published under per-station MQTT topics.
  5. If APRS_PROCESS = False, only the raw packet is published to the base MQTT topic.
  6. If MQTT_TX_ENABLE = True, the service subscribes to a dedicated MQTT topic and forwards approved APRS frames to APRS-IS.

For the full startup sequence, retry model, topic serialization rules, and class/function map, see docs/PROGRAM_REFERENCE.md.

MQTT Topic Layout

Receive topics

Base topic:

RF/<MQTT_SUBTOPIC>

Presence topic:

RF/<MQTT_SUBTOPIC>/state

Structured per-station topics when APRS_PROCESS = True:

  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/raw
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/path
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/format
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/icon
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/latitude
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/longitude
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/distance
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/altitude
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/speed
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/course
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/comment
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/telemetry
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/message
  • RF/<MQTT_SUBTOPIC>/<CALLSIGN>/status

Transmit topics

When MQTT_TX_ENABLE = True, the service subscribes to:

MQTT_TX_TOPIC

If MQTT_TX_TOPIC is left blank, it defaults to:

RF/<MQTT_SUBTOPIC>/tx

Transmit result messages are published to:

<MQTT_TX_TOPIC>/status

Status payloads are JSON objects with these fields:

  • ok: Boolean success flag.
  • packet: The APRS packet text that was accepted or rejected.
  • error: Present only when transmission failed or was rejected.

MQTT-to-APRS Transmission

Transmission is disabled by default and should be enabled only when you intend to send packets to APRS-IS.

Safety rules enforced by the program:

  • MQTT_TX_ENABLE must be True.
  • APRS_PASSWORD must be a verified APRS passcode and cannot be -1.
  • The payload must be a single APRS frame on one line.
  • The outbound frame source callsign must match the configured APRS callsign base.
  • APRS-IS server commands such as lines beginning with # are rejected.

Accepted MQTT TX payload formats:

Raw text payload:

N0CALL>APRS,TCPIP*:>status text

JSON payload:

{"packet": "N0CALL>APRS,TCPIP*:>status text"}

Example publishes:

mosquitto_pub -h 10.0.0.1 -t RF/aprs/tx -m 'N0CALL>APRS,TCPIP*:>status text'
mosquitto_pub -h 10.0.0.1 -t RF/aprs/tx -m '{"packet":"N0CALL>APRS,TCPIP*:>status text"}'

Worked transmit example:

N0CALL-10>APRS,TCPIP*:>mqtt-aprs test packet

Packet breakdown:

  • N0CALL-10 is the source callsign/SSID. Its base callsign must match APRS_CALLSIGN.
  • APRS,TCPIP* is the destination and APRS-IS path.
  • :>mqtt-aprs test packet is the APRS information field, in this case a status payload.

Equivalent test publish:

mosquitto_pub -h 10.0.0.1 -t RF/aprs/tx -m 'N0CALL-10>APRS,TCPIP*:>mqtt-aprs test packet'

Configuration Reference

All settings live in the [global] section.

MQTT settings

Option Required Description
DEBUG No Enables debug logging when True.
LOGFILE No Path to an additional runtime log file. Logs always go to stderr/journal; when this is set they are also written to the file.
MQTT_HOST Yes MQTT broker hostname or IP address.
MQTT_PORT No MQTT broker TCP port. Defaults to 1883.
MQTT_SUBTOPIC Yes Topic suffix published under RF/<MQTT_SUBTOPIC>.
MQTT_USERNAME No MQTT username.
MQTT_PASSWORD No MQTT password.
MQTT_TX_ENABLE No Enables MQTT-to-APRS transmission when True. Defaults to False.
MQTT_TX_TOPIC No Command topic for outbound APRS frames. Defaults to RF/<MQTT_SUBTOPIC>/tx.

APRS settings

Option Required Description
APRS_CALLSIGN Yes APRS-IS login callsign.
APRS_PASSWORD Yes APRS passcode. Use -1 for receive-only mode. A valid passcode is required when MQTT_TX_ENABLE is True.
APRS_HOST Yes APRS-IS hostname.
APRS_PORT No Preferred APRS-IS port. Defaults to 14580.
APRS_FILTER No APRS-IS server-side filter string.
APRS_PROCESS No When True, publish parsed fields. When False, publish only raw packets.
APRS_LATITUDE No Reference latitude used to calculate distance. Must be set together with APRS_LONGITUDE.
APRS_LONGITUDE No Reference longitude used to calculate distance. Must be set together with APRS_LATITUDE.
METRICUNITS No When True, publish metric values. When False, convert distance, speed, and altitude to imperial units.

Installation

apt update
apt install -y git python3 python3-venv python3-pip ca-certificates nano

/usr/sbin/useradd --system --user-group --no-create-home --shell /usr/sbin/nologin mqtt-aprs

git clone https://github.com/JohnCanty/mqtt-aprs /opt/mqtt-aprs
chown -R mqtt-aprs:mqtt-aprs /opt/mqtt-aprs

python3 -m venv /opt/mqtt-aprs/venv
/opt/mqtt-aprs/venv/bin/pip install --upgrade pip setuptools
/opt/mqtt-aprs/venv/bin/pip install setproctitle paho-mqtt aprslib

mkdir -p /etc/mqtt-aprs
cp /opt/mqtt-aprs/mqtt-aprs.cfg.example /etc/mqtt-aprs/mqtt-aprs.cfg
chown -R mqtt-aprs:mqtt-aprs /etc/mqtt-aprs

touch /var/log/mqtt-aprs.log
chown mqtt-aprs:mqtt-aprs /var/log/mqtt-aprs.log
chmod 640 /var/log/mqtt-aprs.log

cp /opt/mqtt-aprs/mqtt-aprs.service /etc/systemd/system/mqtt-aprs.service

Validation And Startup

Edit the configuration:

nano /etc/mqtt-aprs/mqtt-aprs.cfg

Validate it before starting the service:

/opt/mqtt-aprs/venv/bin/python /opt/mqtt-aprs/mqtt-aprs.py --check-config

Load and start the systemd service:

sudo systemctl daemon-reload
sudo systemctl enable --now mqtt-aprs

Runtime notes:

  • The default config path is /etc/mqtt-aprs/mqtt-aprs.cfg.
  • You can override the config path with --config /path/to/mqtt-aprs.cfg.
  • You can also override it with the MQTT_APRS_CONFIG environment variable.
  • The bundled systemd unit runs --check-config before starting the long-running service process.
  • The bundled systemd unit starts after network.target. The bridge itself retries MQTT and APRS connection failures, so it does not rely on network-online.target.

Operational Checks

Show service status:

sudo systemctl status mqtt-aprs

Run the service manually in the foreground:

/opt/mqtt-aprs/venv/bin/python /opt/mqtt-aprs/mqtt-aprs.py --config /etc/mqtt-aprs/mqtt-aprs.cfg

Show recent service logs:

sudo journalctl -u mqtt-aprs -n 100 --no-pager

Show logs from the current boot with monotonic timestamps:

sudo journalctl -b -u mqtt-aprs -o short-monotonic --no-pager

If LOGFILE is set, the same runtime messages are also written to that file.

Watch MQTT output live during testing:

mosquitto_sub -h 10.0.0.1 -v -t 'RF/aprs/#'

Troubleshooting

  • If the service starts with the wrong ExecStart, copy the bundled service file again and run sudo systemctl daemon-reload.
  • If the service only misbehaves during boot, inspect sudo journalctl -b -u mqtt-aprs -o short-monotonic --no-pager first. The bundled unit validates config before launch, and the process itself keeps retrying until MQTT and APRS become reachable.
  • If --check-config fails, fix the missing or invalid settings before starting the service.
  • If the transmit topic rejects packets, confirm the frame is single-line and starts with the configured callsign base.
  • If APRS transmission is enabled but packets are rejected by APRS-IS, verify that APRS_PASSWORD is a valid passcode for APRS_CALLSIGN.

For detailed internals, field-by-field MQTT payload rules, and lifecycle behavior, see docs/PROGRAM_REFERENCE.md.

Improvement Areas

The current codebase is serviceable, but there are still worthwhile next steps:

  • Add automated tests for config parsing, packet validation, and MQTT topic mapping.
  • Publish richer typed payloads for list-like fields such as APRS paths if downstream consumers prefer JSON everywhere.
  • Expose optional metrics or health endpoints for long-running service monitoring.

APRS is a registered trademark of Bob Bruninga, WB4APR.