Skip to content

MQTT topic taxonomy and QoS

SaaS platform topics are account-first (tenant UUID as the first segment):

{account_id}/{client_id}/…

Optional topic_prefix (for example isr-client on legacy on-prem deployments) appears before {account_id} when configured: {topic_prefix}/{account_id}/{client_id}/….

Platform topic format (history, REST, Grafana)

All stored and queried data uses the platform path:

{account_id}/{client_id}/<subpath>
  • {account_id} — tenant UUID from Settings → Profile.
  • {client_id} — the per-device id shown on that unit’s row in MQTT Clients (not the shared fleet pub-… username when those differ). How to configure topics on the device: MQTT clients — platform layout.
What you are doing Which topic path to use
Configure your device or app (recommended) {account_id}/{client_id}/… on the wire — see MQTT clients
Flux / Grafana / REST history export Same platform path as above
Filter in Flux Prefer r.account_id == "…"; optional r.topic =~ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\// and/or r.client_id == "…"
Portal device list history_topic_prefix in the API (same prefix as above)

Live MQTT with a read-only subscriber subscribes under {account_id}/#. Payload-bridge republishes ingested messages onto that platform path when fanout is enabled (same shape as history and Flux).

Vendor / factory wire paths

If firmware publishes on a vendor topic tree instead of {account_id}/{client_id}/…, the operator must register that layout in the platform catalog before ingest works. Devices keep factory paths on the wire; the platform normalizes to {account_id}/{client_id}/… for InfluxDB, REST history, and subscribers. Contact support@ishareradio.com to register a new layout. Walkthroughs for registered products: Client examples.

MQTT QoS levels (0, 1, 2)

QoS Delivery When to use on publish
0 At-most-once High-rate or idempotent telemetry (temperature, bandwidth, heartbeats). Duplicates or drops are acceptable.
1 At-least-once Default effective QoS on the platform when the QoS 2 add-on is off, or after the daily QoS 2 fair-use cap is reached. Use for telemetry you want delivered at least once without the QoS 2 add-on, or for command subscriptions (typical subscribe QoS).
2 Exactly-once (client ↔ broker) State and event topics when you need guaranteed handoff to the broker and the Guaranteed delivery (QoS 2) add-on is enabled.

Publish one PUBLISH per reading when signals need different QoS levels. A single JSON blob can only use one QoS.

Subpath under {client_id}/ Recommended publish QoS Typical use
state/ 2 (effective 1 without add-on or when capped) Device mode, connectivity, paired status, relay/digital state
event/ 2 (effective 1 without add-on or when capped) Edge-triggered alarms and event/change envelopes
telemetry/ 0 (optional 1 if at-least-once is required) Temperature, meters, bandwidth, heartbeats
sample/ 0 (optional 1) Optional high-rate samples

Examples

{account_id}/{client_id}/state/summary        → full status JSON (QoS 2)
{account_id}/{client_id}/state/hub            → iShareRadio Hub link (client-reported, QoS 2)
{account_id}/{client_id}/event/change         → component change envelope (QoS 2)
{account_id}/{client_id}/telemetry/temp_probe → one temperature reading (QoS 0)
{account_id}/{client_id}/telemetry/heartbeat  → keepalive (QoS 0)

Station controller readings proxied through isr-client fan out to state/{type} or telemetry/{type} on the same iSR Client {account_id}/{client_id}/… tree; identify the SC unit via station_controller_device_id in the payload. See Station Controller MQTT. iSR Client-native telemetry: iSR Client MQTT.

Guaranteed delivery (QoS 2) add-on

Enable Guaranteed delivery (QoS 2) under Subscriptions in the MQTT SaaS portal to unlock:

  • Effective QoS 2 for state/ and event/ publishes (exactly-once between client and broker).
  • Telemetry you publish at QoS 0 stays at-most-once; telemetry published at QoS 1 is stored and metered as QoS 1.

Fair-use cap

The add-on includes a daily fair-use pool of effective QoS 2 messages per account (UTC calendar day). When the cap is reached, state and event traffic is demoted to QoS 1 (at-least-once) until the next UTC day. The Overview page shows usage and demotion status.

Without the add-on

If the add-on is not active, the platform treats all ingested traffic as QoS 1 for metering and history—even if the client publishes state/ or event/ at QoS 2. Publish telemetry at QoS 0 for lowest overhead, or at QoS 1 when you need at-least-once without the add-on. Keep the topic taxonomy above so portal QoS mix and upgrades stay consistent.

Per-client max QoS

Each MQTT client has a max publish QoS (0, 1, or 2) set in the portal or Mgmt REST API:

Max QoS Meaning
0 Client may only use QoS 0 (telemetry-style).
1 Client may use QoS 0 or 1 (at-least-once allowed; QoS 2 not allowed). Default for new MQTT clients.
2 Client may use QoS 0, 1, or 2 on allowed topics (QoS 2 on state/ / event/ requires the QoS 2 add-on).
  • Create MQTT client (portal): checkbox QoS 2 guaranteed delivery when the add-on is active; otherwise disabled with a tooltip.
  • Edit MQTT client: change label and max QoS (REST: PATCH /api/v1/subscriber/publishers/{client_id} with max_publish_qos).

Portal visibility

  • Overview — approximate account-wide QoS mix (Q0 / Q1 / Q2 percentages) and QoS 2 daily usage.
  • MQTT Clients — Max QoS column (configured cap) and QoS mix (observed traffic).

Retained messages and broker limits

Retained MQTT messages are live-state hints on the broker (LWT presence, last status snapshot, etc.). They are not durable history — use portal Devices, REST history export, or Grafana/Influx for anything beyond the broker retain window.

24-hour retain maximum

Protocol What to publish What the broker does
MQTT 5 Set Message Expiry Interval (MEI) ≤ 86400 seconds on every retained PUBLISH Adds 86400 s MEI when missing; retains older than 24 h are cleared by the janitor tick (and native MEI expiry when set)
MQTT 3.1.1 Retain bit only (no MEI property) Tracks retain age and clears topics older than 24 h on a periodic sweep

Integrator guidance: Prefer MQTT 5 with explicit MEI on retained state (LWT, "online" presence, last-known config). MQTT 3.1.1 devices should refresh retained topics at least daily, or accept that stale retains may disappear after 24 hours.

Wildcard # subscriptions and retain catch-up

Read-only subscriber credentials default to {account_id}/#. When a client subscribes, Mosquitto delivers all matching retained messages in a burst before live traffic.

To protect broker memory and client queues at scale, the platform caps that burst:

Setting Default Purpose
max_queued_messages max_publisher_clients × 3 from your subscription plan catalog (largest tier today: 3000) Maximum queued outbound messages per client session during retain catch-up on a wildcard subscribe. Excess retained deliveries are dropped; live publishes after SUBSCRIBE are unaffected.
max_inflight_messages 20 Maximum unacknowledged QoS 1/2 messages in flight per client session

The × 3 factor assumes up to three retained topics per publisher (typical: LWT + one or two state topics). Fleets with many retained topics per device should avoid relying on {account_id}/# catch-up for full state — subscribe to narrower filters or read history via REST/Grafana.

Practical limits:

  • Single-level + and multi-level # wildcards are allowed in subscriber ACL patterns when provisioned in the portal.
  • A subscriber on {account_id}/# with hundreds of publishers each retaining several topics may not receive every retain if the catch-up exceeds max_queued_messages; design dashboards and apps to use REST history or targeted subscriptions for backfill.
  • Publisher ACLs remain prefix-scoped to {account_id}/{client_id}/… (or registered native wire roots) — publishers cannot use # to read other tenants or devices.

See also: Last Will and Testament (LWT), MQTT overview, Client examples, subscriber MQTT passwords.

iShareRadio client (isr-client)

When MQTT is enabled, the client publishes:

  • Hub/device status under state/ and event/ (QoS 2).
  • Bandwidth and heartbeat under telemetry/ (QoS 0).
  • Station controller readings as separate messages under state/ or telemetry/ depending on reading type.

See also: MQTT overview, Client examples, subscriber MQTT passwords.