MQTT clients

MQTT clients are broker logins you create under MQTT Clients in the portal. Each credential gets a username, password, and a TLS broker endpoint. You choose whether that login may publish, subscribe, or both.

You use them for field hardware, gateways, and backend services — anything that connects to the broker with a normal MQTT username and password.

The platform supports Shared vs Single credentials. See Deployments for fleet patterns and plan limits.

The iSR MQTT platform offers a special class of MQTT Topic subscriber for listen-only access to specific live platform topic paths. These are known as Read-only subscribers and useful for third party systems that should not have full MQTT publish or subscribe permissions.

Prerequisites

Active MQTT SaaS base plan.
Account ID (tenant UUID) from Settings → Profile — you need this value in every platform topic path.

Depending on your fleet, you may want an MQTT login to publish only, subscribe only, or both.

When you create an MQTT credential, you specify (and can edit later) Allow publish and Allow subscribe.

Checkbox	Effect
Allow publish	Client may send messages; telemetry is ingested to history and last-payload when your plan allows.
Allow subscribe	Client may receive allowed command/status topics for that credential.

Ingest records publishes only. Traffic the client only subscribes to is not stored unless it also publishes those messages.

The portal does not let you edit raw topic ACL lists; patterns are derived from your tenant, credential scope, and topic layout. See MQTT QoS and topics.

Create an MQTT client (portal)

Sign in at the MQTT portal.
Open MQTT Clients → New publisher client.
Enter a label.
Under Credential scope, pick Shared or Single device (see Deployments).
Set Allow publish / Allow subscribe as needed.
For Single device, choose Platform wire format (default) unless your device uses a registered vendor layout (see Built-in or vendor topic paths).
Click Create and copy the one-time dialog (host, port, TLS, password, and either MQTT_CLIENT_ID or shared MQTT_USERNAME).

The portal does not show the password again on the list. Rotate credentials on the row to issue a new password. For Single device credentials the portal auto-generates a client_id (often shown as pub-… in the credential root row).

Shared: put the same username and password on every device; each unit keeps its own MQTT Client ID from firmware or your configuration.

How to set up MQTT topics (platform layout)

This is the default and recommended layout for custom firmware, scripts, and integrations you control.

Every message on the broker — and every path in InfluxDB, REST history, Grafana, and read-only subscriber filters — uses the same platform tree:

{account_id}/{client_id}/<subpath>

Segment	Value
`{account_id}`	Your tenant UUID from Settings → Profile
`{client_id}`	The per-device id for that connection (see below)
`<subpath>`	Your application path (for example `telemetry/temperature`, `state/summary`)

Recommended subpaths and QoS classes (state/, event/, telemetry/, sample/) are in MQTT QoS and topics.

Single-device credential

Use the portal row’s client_id everywhere it applies:

Portal field	On your MQTT client
`MQTT_CLIENT_ID`	MQTT username and MQTT Client ID on connect (same value)
`MQTT_PASSWORD`	Password
`MQTT_BROKER_HOST` / `MQTT_BROKER_PORT` / `MQTT_USE_TLS`	Broker endpoint
`MQTT_ACCOUNT_ID`	Tenant UUID (also in Settings → Profile)
Topics you publish	`{account_id}/{client_id}/…` using that `MQTT_CLIENT_ID`

Example (placeholders):

Account ID:  550e8400-e29b-41d4-a716-446655440000
client_id:   bench-sensor-1

Publish:     550e8400-e29b-41d4-a716-446655440000/bench-sensor-1/telemetry/temperature
Subscribe:   550e8400-e29b-41d4-a716-446655440000/bench-sensor-1/#

Shared (fleet) credential

One portal login covers many physical devices. MQTT_USERNAME is the shared fleet username (often pub-…). It is not the {client_id} segment in topic paths.

Portal field	On each device
`MQTT_USERNAME`	Same fleet username on every unit
`MQTT_PASSWORD`	Same fleet password on every unit
`MQTT_BROKER_HOST` / `MQTT_BROKER_PORT` / `MQTT_USE_TLS`	Broker endpoint
`MQTT_ACCOUNT_ID`	Tenant UUID
MQTT Client ID	Unique per device — set by firmware or your config (for example `repeater-01`, `gateway-west`)
Topics each device publishes	`{account_id}/{that-device-client-id}/…`

After the first publish, each unit usually appears as its own row under MQTT Clients with that device’s client_id. History, Flux, and read-only subscribers always use {account_id}/{client_id}/…, where {client_id} is the device row, not the shared pub-… username.

Example (placeholders):

Shared MQTT_USERNAME:  pub-fleet-abc
Device A Client ID:    repeater-01
Device B Client ID:    repeater-02

Device A publishes:  {account_id}/repeater-01/telemetry/…
Device B publishes:  {account_id}/repeater-02/telemetry/…

Use the broker host, port, and TLS setting exactly as shown in the portal credential dialog.

Connection behaviour

The broker keys live sessions on MQTT Client ID (and username in this platform for ACL and portal metrics). Under MQTT 3.1.1, if a client connects with a Client ID that is already connected, the broker must disconnect the existing session. You cannot maintain two simultaneous connections with the same Client ID.

Scenario	Allowed?	What happens
Same Client ID, two TCP connections at once	No	Second connect replaces the first (session takeover)
Same username/password, different Client IDs	Yes	Each device is its own session (typical Shared fleet)
One device, two Client IDs (two connections)	Yes	Two logical clients; uncommon — prefer one session per device

Practical implications:

Expect one active connection per Client ID in the portal Connections column (0 or 1 for enrolled devices).
Shared credentials still require a unique Client ID on every physical device — the shared username does not replace per-device Client IDs.
Reusing the same Client ID on two running clients causes connect/disconnect flapping, lost in-flight QoS state, and unreliable online/offline metrics.

For vendor fleets (for example ARGUS DL-1), keep the factory Client ID on each unit. See ARGUS DL-1 integration.

Last Will and Testament (LWT)

Clients may register an LWT at connect. Many products use a retained …/lwt topic with online / offline payloads.

Shared credentials: each device registers LWT only on its topic path, with its MQTT Client ID on the connect packet. One unit cannot set a will on another’s path.

Retain: enable on the will and on the post-connect online publish when firmware expects retained presence. LWT is ingested for portal online/offline when history is enabled.

24-hour retain cap: Broker retained messages are live-state hints, not durable history. The platform enforces a maximum retain age of 86400 seconds (24 h). On MQTT 5, set Message Expiry Interval ≤ 86400 on every retained PUBLISH (the broker adds MEI when missing). On MQTT 3.1.1, stale retains are cleared after 24 h — refresh retained "online" at least daily if presence must stay current. Details: Retained messages and broker limits.

Fixed Vendor Topic Paths

Some products ship a fixed topic tree (for example a vendor root like vendor/prod/{serial}/status) instead of {account_id}/{client_id}/vendor/prod/{serial}/status on the device. Those layouts are not built into the platform by default.

For ingest, ACL, and history normalization to work:

The iShareRadio team can register your product’s wire layout in the native topic catalog (wire root, client-id prefix, device-key rules, subscribe patterns).
You create an MQTT client in the portal with the matching native wire format.
Devices keep publishing on the fixed paths remain as-is configured in the MQTT Client; the platform maps them to {account_id}/{client_id}/… for storage, Grafana, REST history etc.

To onboard a topic layout or OEM fleet, contact support@ishareradio.com with your device model and sample topic paths.

Device-specific walkthroughs (after a layout is registered) live under Client examples. ARGUS DL-1 is one registered layout — see ARGUS DL-1 integration.

Fleet patterns and plan counting for vendor fleets: Deployments — vendor fleets.

Certain subpath keywords (event, telemetry, state, …) may affect effective QoS depending on your plan add-ons. See MQTT QoS and topics.

Automation (REST API)

MQTT clients are broker credentials. They are not the same as REST API tokens (isr_mqtt_rest_…), which are for HTTP only.

If you automate provisioning at scale, use the Mgmt REST API add-on:

Enable Mgmt REST API under Subscriptions.
Create a REST API token in Settings.
Call /api/v1/subscriber/publishers (paths retain the historical name publishers) to create, list, pause, resume, rotate, and delete MQTT clients.

Full reference: MQTT client management API. Overview of all subscriber HTTP APIs: REST API.

History export and live status use separate REST add-ons and endpoints — see History API and Live API.