Skip to main content

MQTT Device Connectivity

How devices connect to Beacon Tower via MQTT — from first boot to live telemetry.

Architecture​

The MQTT Provider (beacontower-mqttprovider) is the bridge between MQTT devices and the Beacon Tower platform. It accepts MQTT connections from devices, forwards telemetry to the message queue for processing, manages device twins, and relays commands.

The MQTT Broker handles the MQTT transport (TLS, authentication, ACLs). The MQTT Provider service subscribes to all device topics and bridges messages into the platform.

Connection Lifecycle​

A device goes through these stages to start sending data:

1. Onboarding​

Before a device can connect, it must be provisioned. Beacon Tower supports two onboarding paths:

For shared-secret onboarding:

  1. An administrator creates an enrollment group with a routing target pointing to the MQTT broker
  2. The device is registered in the enrollment group
  3. The device calls GET /get_settings to receive its MQTT credentials
  4. The device is provisioned with POST /provision_device

Provisioning creates four records in the provider database:

  • Provider client — device identity with encrypted credentials
  • MQTT user — username/password for broker authentication
  • MQTT ACL — topic access permissions (devices/{deviceId}/#)
  • Device twin — initial empty twin with version counters

2. MQTT Connection​

With credentials in hand, the device connects to the MQTT broker:

ParameterValue
HostFrom onboarding response (mqtt_host)
PortFrom onboarding response (mqtt_port), typically 1883 (TCP) or 8883 (TLS)
UsernameThe device ID
PasswordThe primary key from onboarding
Client IDAny unique string (conventionally the device ID)
Clean Sessiontrue

3. Publish and Subscribe​

Once connected, the device communicates via four topic families:

TopicDirectionPurpose
devices/{deviceId}/telemetryDevice → CloudSensor readings and metrics
devices/{deviceId}/twin/reportedDevice → CloudDevice state (firmware version, config)
devices/{deviceId}/twin/desiredCloud → DeviceDesired configuration from operators
devices/{deviceId}/methods/{name}/invokeCloud → DeviceCommand invocations

Each device is ACL-restricted to devices/{deviceId}/# — it cannot see or publish to other devices' topics.

What Happens to Telemetry​

When a device publishes to devices/{deviceId}/telemetry:

  1. The MQTT Broker authenticates and delivers the message
  2. MQTT Provider receives it via its wildcard subscription
  3. The message is published to the message queue on topic telemetry.{providerId}::{deviceId} with headers (messageType, providerId, providerClientId, enqueuedTime)
  4. The ingress pipeline consumes from the queue, parses the payload, and routes individual signals to the corresponding assets
  5. Assets forward data to flows and persist to the time-series database

This pipeline is described in detail in Telemetry Ingestion.

Performance Characteristics​

The MQTT Provider is designed for high-throughput IoT workloads:

  • Batched publishing — Messages are batched (256 messages or 50ms window) before publishing to the queue
  • Backpressure — A bounded channel (10,000 capacity) drops messages under extreme load rather than consuming unbounded memory
  • Pipelined delivery — Queue publishes use fire-all-then-collect-acks for throughput
  • Concurrent twin updates — Up to 16 parallel database writes for reported properties

Next Steps​