Skip to content

Deployments

How you structure MQTT credentials and field devices on a tenant. This page is about fleet patterns, tradeoffs, and plan limits — not the portal create dialog (see MQTT clients).

Shared vs single-device credentials

When you create an MQTT client, Credential scope is the main choice. It controls how many physical connections share one password and how MQTT username relates to MQTT Client ID.

How the system treats each type

Shared Single device
Portal intent One login for a fleet or service One login for one connection
MQTT username One generated username (often pub-…) shared by many devices Usually the same as that row’s client_id
MQTT password One password copied to every device using this login One password for that device only
MQTT Client ID at connect Different per device (set by firmware or you) Should match the portal client_id for that row
Portal list One credential root row; each unit often gets its own child row after first publish One row per credential
Typical topics {account_id}/{client_id}/… (platform) or a registered vendor wire tree {account_id}/{client_id}/…
Broker write rule (shared) A connection may only publish to topics for its own Client ID Writes limited to that client’s prefix
Auto-registration Units with vendor layouts can appear automatically when they first publish Row exists before connect 
Shared (many devices, one password):

  Portal:  [credential root: pub-fleet-abc]  →  MQTT_USERNAME / MQTT_PASSWORD
  Device A: same username/password, MQTT Client ID = repeater-01
  Device B: same username/password, MQTT Client ID = repeater-02

Single device (one password, one client):

  Portal:  [row: bench-sensor-1]  →  username = bench-sensor-1, password = …
  Device:  same username/password, MQTT Client ID = bench-sensor-1

Pros and cons

Shared credentials

Good for

  • Many identical devices (repeaters, gateways, OEM fleets) where provisioning one password is practical.
  • Firmware that already defines MQTT Client ID and vendor topic paths and cannot use a portal-assigned pub-… id.
  • A backend service that uses one login but opens separate connections per target (each with the correct Client ID to publish commands).

Tradeoffs

  • Password exposure — Anyone with the fleet password can connect; the broker still limits writes per Client ID, but the login is shared.
  • Rotation — Rotating the password updates every device using that login until you reconfigure them.
  • Operational discipline — Each device must use the correct MQTT Client ID; mismatches cause publish or LWT failures.
  • Not a clone — A second service on the same tenant needs a second shared MQTT client in the portal, not a copy of the fleet password.

Single-device credentials

Good for

  • One ESP32, script, or integration where one device = one credential is easiest to reason about.
  • Isolated revocation — Disable or rotate one device without touching a fleet.
  • Custom apps that already speak {account_id}/{client_id}/… and can set Client ID to the portal value.

Tradeoffs

  • Volume — Many devices means many portal rows and passwords (within plan limits).
  • Provisioning — Each device needs its own create step in the portal (or automation; see MQTT clients — Automation).
  • Poor fit for OEM fleets — A unique portal password per repeater is usually impractical; use shared instead.

When to choose which

Situation Choose
Fleet of field devices with factory Client IDs and topics Shared
One backend app + fleet, need a different password than devices Shared again (second MQTT client in the portal)
Single custom publisher on {account_id}/{client_id}/… Single device
Listen-only on {account_id}/… (no publish on vendor paths) Read-only subscriber

Walkthroughs: Client examples (e.g. ARGUS DL-1 uses shared credentials).

Plan limits (reporting clients)

Base plans advertise a maximum number of enrolled reporting devices (for example Integration Trial 1 → 1). The platform enforces:

physical reporting devices (enrolled MQTT Clients rows)  ≤  max_publisher_clients
What Counts toward plan?
Shared fleet credential (pub-… root in MQTT Clients) No — one login for many units
Enrolled device Yes — each row under Enrolled devices, or each single-device MQTT client

Examples on a 10-client plan:

  • One shared fleet credential + up to ten enrolled devices that publish under it = 10 devices (the credential does not use a slot).
  • Ten single-device MQTT clients and no shared fleet = 10 total.
  • Two shared fleet credentials + eight enrolled devices = 8 toward the cap (credentials are not counted).

When the device limit is reached:

  • The portal blocks new enrolled devices with publisher_limit_reached.
  • Auto-enrollment on first publish (registered vendor layouts) stops adding new device rows; ingest for that new Client ID is dropped until you upgrade the plan or remove devices.

Overview and Settings → MQTT tenants show enrolled devices vs max for each tenant. When enrolled devices are at the limit, extra live MQTT connections without a device row appear as (+N) on that row (blocked for ingest, not an extra plan slot).

Vendor fleets

Products that ship a fixed factory topic tree (instead of {account_id}/{client_id}/… on the device) require a registered native wire layout on the platform before broker ACL and ingest normalization work. Contact support@ishareradio.com to register your product’s topic mapping.

Typical pattern with shared credentials after the layout is registered:

  1. Create one shared MQTT client in the portal (matching wire format if prompted).
  2. Configure each unit with the same username/password and factory MQTT Client ID.
  3. Each unit appears in MQTT Clients after its first publish (counts toward the physical device portion of your plan).

Cutover from another broker: change host, username, and password; keep Client ID and factory topic paths on the device.

Platform storage and subscribers still use {account_id}/{client_id}/…. Setup details: MQTT clients — platform layout and Built-in or vendor topic paths. Device walkthroughs: Client examples.