Skip to content

iSR Client MQTT

MQTT telemetry from the iSR Client on MQTT SaaS: the client’s own status, connectivity, bandwidth, and heartbeat. This is published directly by the client — not relayed from the iShareRadio Hub service or from station controller hardware.

Station controller module readings use the same {account_id}/{client_id}/… topic tree but are documented separately in Station Controller MQTT.

For QoS rules, the QoS 2 add-on, and fair-use caps, see MQTT QoS and topics.

Topic layout on MQTT SaaS

Every publish uses:

{account_id}/{client_id}/{subpath}
Segment Value on SaaS
{account_id} Your tenant UUID from Settings → Profile (iSR Client mqtt_account_id must match)
{client_id} The iSR Client’s MQTT Client ID from the portal credential dialog — use the same value as the MQTT username for a single-device login
{subpath} state/…, event/…, or telemetry/… (tables below)

Do not add a topic root for MQTT SaaS. Leave iSR Client mqtt_topic_prefix empty so paths start with {account_id}/…. An optional prefix before the account id is for legacy on-prem deployments only; the portal, history, Flux, and subscribers all expect account-first paths.

Platform layout setup: MQTT clients — platform layout.

Example (placeholders):

550e8400-e29b-41d4-a716-446655440000/isr-shack-01/state/summary
550e8400-e29b-41d4-a716-446655440000/isr-shack-01/telemetry/bandwidth
550e8400-e29b-41d4-a716-446655440000/isr-shack-01/event/change

Subscribe or query with wildcards under that client prefix, for example {account_id}/isr-shack-01/#.

Installation, broker credentials, and publish intervals: iSR Client installers. Create the MQTT login and copy {account_id} / {client_id} from the MQTT clients portal flow first.

Identified by

What How
Topic path {account_id}/{client_id}/…
Client id device_id in state/summary (same as {client_id} for single-device logins)
User labels callsign, username from pairing; custom display name on the paired hub device (Device.custom_display_name) — not duplicated in MQTT state/summary today
Status hub_status, lan_status, cell_status, radio_status, and matching state/* topics

Payload fields such as hub_status and the topic state/hub report the client’s link to the iShareRadio Hub — one component inside the client’s own snapshot, not separate hub telemetry.

Telemetry overview

Kind Cadence Subpath pattern
Status snapshot Configurable interval (default 30 s) state/summary plus component topics under state/
Bandwidth When a new sample is available telemetry/bandwidth (+ optional telemetry/bandwidth/rx / tx)
Heartbeat On schedule telemetry/heartbeat
Status change Immediate on transition event/{component} and event/change

Status and connectivity (state/)

Recommended publish QoS: 2 for every state/ topic.

Subpath QoS Payload shape Example
state/summary 2 JSON object Full client status (see field table below)
state/hub 2 Plain string iShareRadio Hub link colour token, e.g. "green"
state/lan 2 Plain string LAN / UDPB status, e.g. "green" or "unknown"
state/cell 2 Plain string Remote radio path, e.g. "green"
state/radio 2 Plain string Radio proxy status, e.g. "green" or "blue"
state/paired 2 Plain string "true" or "false"
state/clients/sdr 2 Plain string "true" or "false"
state/clients/cat 2 Plain string "true" or "false"
state/clients/dax 2 Plain string "true" or "false"
state/clients/lc 2 Plain string "true" or "false"

Status colour tokens on state/hub, state/lan, state/cell, and state/radio mirror the client GUI (common values: green, blue, red, yellow, unknown, plus error tokens such as timeout, auth, no_internet on the hub link).

state/summary fields (representative):

Field Type Notes
device_id string Operational id; matches {client_id} for single-device MQTT logins
version string Client build version
is_paired boolean Paired to iShareRadio Hub
callsign, username string From pairing (optional)
host_os, platform, host_ip, mac_address string Host metadata
runtime integer Minutes since client start
hub_status, lan_status, cell_status, radio_status string Same tokens as the matching state/* topics
sdr_connected, cat_connected, dax_connected, lc_connected boolean Flex client connections
timestamp string RFC3339 UTC

Example — state/summary (truncated):

{
  "version": "2.4.1",
  "device_id": "isr-shack-01",
  "is_paired": true,
  "callsign": "VE7ABC",
  "username": "ve7abc",
  "host_os": "Ubuntu 22.04",
  "platform": "linux/amd64",
  "runtime": 323,
  "hub_status": "green",
  "lan_status": "green",
  "cell_status": "green",
  "radio_status": "blue",
  "sdr_connected": true,
  "cat_connected": false,
  "dax_connected": true,
  "lc_connected": true,
  "timestamp": "2026-05-19T18:42:00Z"
}

Events (event/)

Recommended publish QoS: 2.

Subpath QoS Payload When
event/{component} 2 Plain status string e.g. event/hub → "green"
event/change 2 JSON envelope Same transition with component, status, timestamp

Example — event/change:

{
  "component": "hub",
  "status": "green",
  "timestamp": "2026-05-19T18:42:05Z"
}

Telemetry (telemetry/)

Recommended publish QoS: 0 (at-most-once).

Subpath QoS Payload Notes
telemetry/bandwidth 0 JSON rx_mbps, tx_mbps, bytes/sec, timestamp
telemetry/bandwidth/rx 0 Plain float string e.g. "12.34"
telemetry/bandwidth/tx 0 Plain float string e.g. "0.52"
telemetry/system 0 JSON Optional host snapshot: version, device_id, host_os, platform, host_ip, mac_address, runtime, …
telemetry/heartbeat 0 JSON timestamp, status, uptime

Example — telemetry/bandwidth:

{
  "timestamp": "2026-05-19T18:42:00Z",
  "rx_bytes_per_sec": 1543210,
  "tx_bytes_per_sec": 64000,
  "rx_mbps": 12.35,
  "tx_mbps": 0.51
}

Effective QoS on the platform

The recommended QoS columns above are what isr-client publishes when configured for QoS 2 on state/ / event/ and QoS 0 on telemetry/. Effective QoS (history and metering) also depends on your plan:

Factor Effect on QoS 0 Effect on QoS 1 Effect on QoS 2
No QoS 2 add-on Stored as QoS 0 Stored as QoS 1 Demoted to effective QoS 1 for state/ / event/
QoS 2 add-on active Stored as QoS 0 Stored as QoS 1 state/ / event/ kept at QoS 2 until fair-use cap
QoS 2 fair-use cap reached Unchanged state/ / event/ demoted to QoS 1 until next UTC day Same demotion
MQTT client max QoS Allowed if max ≥ 0 Allowed if max ≥ 1 Allowed only if max = 2 and add-on active

Summary: QoS 1 is the normal at-least-once path without the add-on. QoS 0 suits high-rate telemetry; QoS 2 suits discrete state/ and event/ topics when the add-on is on.