APRS PropView MQTT Setup Guide

PropView Settings

In PropView Settings, open MQTT Integration and set:

• MQTT Enabled: checked
• Broker Host: the broker hostname or IP, for example homeassistant.local or 192.168.1.25
• Port: usually 1883
• Topic Prefix: usually aprs/propview
• Username/Password: the broker credentials, if your broker requires them
• Watched Callsigns: optional callsigns that should get retained Home Assistant presence, last-heard, and distance entities

Save settings. PropView reconnects MQTT live after broker, login, topic, or discovery settings change.

Topics Published

With the default topic prefix aprs/propview, PropView publishes:

• aprs/propview/propagation retained JSON with current propagation metrics
• aprs/propview/score retained numeric regional propagation score
• aprs/propview/level retained regional propagation level text
• aprs/propview/ha/status retained JSON for connectivity, station counts, packet age, warnings, message waiting, and band-opening state
• aprs/propview/watched/<callsign> retained JSON for each configured watched callsign
• aprs/propview/alert JSON event payload when alerts fire
• aprs/propview/event and aprs/propview/event/<type> JSON automation event payloads

Example propagation payload:

{
  "my_score": 35.0,
  "my_level": "fair",
  "regional_score": 61.2,
  "regional_level": "good",
  "rf_stations_1h": 12,
  "max_distance_km": 420.5,
  "timestamp": 1779926400.0
}

Home Assistant With Mosquitto

1. In Home Assistant, open Settings, Add-ons, Add-on Store.
2. Install Mosquitto broker.
3. Start the add-on and enable Start on boot.
4. Create or choose a Home Assistant user for MQTT authentication.
5. In PropView, set Broker Host to the Home Assistant host/IP, Port to 1883, and enter that username/password.
6. Enable Home Assistant Discovery. The default Discovery Prefix is homeassistant.
7. Save PropView settings. PropView will reconnect MQTT and publish discovery configs.

To confirm messages are arriving, install a tool such as MQTT Explorer and subscribe to aprs/propview/# and homeassistant/sensor/aprs_propview/#, or use Home Assistant's MQTT integration diagnostics.

Manual Mosquitto Broker

On Debian or Raspberry Pi OS:

sudo apt update
sudo apt install mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto

For a quick local test from the broker machine:

mosquitto_sub -h localhost -t 'aprs/propview/#' -v

If PropView runs on another machine, use the broker machine's LAN IP as the Broker Host.

Home Assistant Entities

With Home Assistant Discovery enabled, PropView publishes retained discovery configs for these sensors and binary sensors:

• My Station Propagation Score and Level
• Regional Propagation Score and Level
• RF Stations 1h
• Max RF Distance
• RF/APRS-IS station counts, last RF packet age, and weather alert count
• APRS-IS connected, RF interface connected, band opening active, Sporadic-E possible, new station heard, message waiting, weather warning active, and interface-down binary sensors
• Watched callsign heard-recently, last-heard, and distance entities for each configured watched callsign

Discovery uses homeassistant/sensor/<device_id>/<sensor>/config and homeassistant/binary_sensor/<device_id>/<sensor>/config topics plus aprs/propview/status for availability. Keep the Device ID stable after entities are created.

If Home Assistant discovery is disabled or unavailable, add MQTT sensors in configuration.yaml:

mqtt:
  sensor:
    - name: "APRS PropView Score"
      state_topic: "aprs/propview/score"
    - name: "APRS PropView Level"
      state_topic: "aprs/propview/level"
    - name: "APRS PropView RF Stations 1h"
      state_topic: "aprs/propview/propagation"
      value_template: "{{ value_json.rf_stations_1h }}"
    - name: "APRS PropView Max Distance km"
      state_topic: "aprs/propview/propagation"
      value_template: "{{ value_json.max_distance_km }}"

Restart Home Assistant or reload MQTT entities after editing YAML.

Node-RED Setup

Node-RED also connects as an MQTT client. It subscribes to the same broker PropView publishes to, then routes the received messages into debug panels, dashboards, Home Assistant calls, or automations.

An importable dashboard flow is included in deploy/node-red/aprs-propview-dashboard-flow.json. An optional Alexa Smart Home starter flow is available in deploy/node-red/aprs-propview-alexa-dashboard-flow.json. See deploy/node-red/README.md for palette requirements, MQTT broker setup, and Alexa discovery notes.

1. Install Node-RED and confirm it can reach your MQTT broker. In Home Assistant, the Node-RED add-on can usually reach the Mosquitto add-on by using the Home Assistant host/IP and port 1883.
2. Open the Node-RED editor, drag an mqtt in node onto the flow, and double-click it.
3. Add a new broker connection. Set Server to the broker host/IP, Port to 1883, and enter the MQTT username/password if your broker requires them.
4. Set Topic to aprs/propview/# to receive all PropView topics, or use one exact topic such as aprs/propview/propagation.
5. Set Output to a parsed JSON object if your Node-RED version offers that option. Otherwise, wire the MQTT node into a json node.
6. Wire the output to a debug node, deploy the flow, then watch the debug sidebar for PropView messages.

Useful starter flows:

• mqtt in topic aprs/propview/propagation -> json -> debug to inspect the full propagation payload.
• mqtt in topic aprs/propview/score -> dashboard gauge/chart node to display the regional score.
• mqtt in topic aprs/propview/event -> json -> Home Assistant notification, speech, or achievement logging.
• mqtt in topic aprs/propview/alert -> json -> notification, email, Home Assistant service call, or dashboard text node.

When using the wildcard topic aprs/propview/#, Node-RED puts the actual topic in msg.topic and the value in msg.payload. That makes it easy to use a switch node to route score, level, propagation, and alert messages down different paths.

// Function node example after aprs/propview/propagation
msg.payload = {
    score: msg.payload.regional_score,
    level: msg.payload.regional_level,
    rf_stations: msg.payload.rf_stations_1h,
    max_distance_km: msg.payload.max_distance_km
};
return msg;

Automation Events

PropView publishes non-retained JSON events on aprs/propview/event. These are meant for Home Assistant and Node-RED automations, not dashboard state.

{
  "event": "new_max_distance",
  "callsign": "W1ABC",
  "source": "rf",
  "distance_km": 1240.0,
  "previous_distance_km": 980.2,
  "heading": 63.4,
  "is_direct": true,
  "hop_count": 0
}

Current events include first_heard, new_max_distance, and message_received. PropView publishes them to the aggregate event topic and a typed topic such as aprs/propview/event/message_received so automations can route them without parsing every event first.

Troubleshooting

• If PropView logs MQTT: failed to connect, confirm broker host, port, username, password, and firewall rules.
• If Home Assistant does not discover entities, confirm MQTT discovery is enabled in Home Assistant and verify homeassistant/sensor/aprs_propview/# config topics are retained.
• If Home Assistant entities appear but do not update, first verify aprs/propview/# topics with mosquitto_sub or MQTT Explorer.
• If Node-RED does not show messages, attach a debug node directly to the MQTT node, subscribe to aprs/propview/#, and confirm the broker connection says connected.
• If using Docker or a VM, remember that localhost means inside that container or VM. Use the broker's reachable LAN host/IP instead.
• PropView publishes propagation periodically, so wait for the next propagation update after startup.