MQTT Publishing

This page explains how Beacon Tower publishes asset data to MQTT — enabling external systems, dashboards, and integrations to subscribe to real-time asset telemetry and diagnostics over MQTT.

Overview

The MQTT Publisher is an asset-centric service that publishes processed asset data to an MQTT broker for consumption by external systems, dashboards, and integrations.

Backend services use the Publisher's subscription API to request that specific asset data be published to MQTT topics. The Asset Processor reads these subscriptions, collects the relevant asset data, and routes it through NATS to the Publisher for delivery.

Backend Service
  → PUT /api/subscriptions (subscribe to asset data)
      ↓
MQTT Publisher
  → Stores subscription (which assets, which topics)
  → Publishes subscription.created CloudEvent
      ↓
Asset Processor (reads subscription list)
  → Collects data for subscribed assets
  → Sends telemetry/diagnostic events to NATS
      ↓
MQTT Publisher (NATS consumer)
  → Receives pre-filtered asset data
  → Publishes to MQTT broker on the correct topics
      ↓
MQTT Broker
  → External systems, dashboards, integrations subscribe

Subscription API

The core interface of the MQTT Publisher. Backend services call these endpoints to control which asset data gets published to MQTT. All endpoints require Azure AD B2C authentication.

Subscribe (Create or Update)

curl -X PUT https://mqtt-publish.beacontower.ai/api/subscriptions \
  -H "Authorization: Bearer <b2c-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "analytics-dashboard",
    "topicPatterns": [
      "beacontower/v1/assets/pump-001/telemetry",
      "beacontower/v1/assets/pump-001/diagnostics"
    ],
    "assetIds": ["pump-001"]
  }'

Field	Type	Required	Description
id	uuid	No	Subscription ID. If provided and exists, updates the subscription. If omitted, creates a new one.
clientId	string	Yes	Identifier for the subscribing system
topicPatterns	string[]	Yes	MQTT topics to publish asset data on
assetIds	string[]	Yes	Assets whose data should be published

Returns 201 Created for new subscriptions or 200 OK for updates.

When a subscription is created, the Publisher emits a subscription.created CloudEvent to NATS. The Asset Processor picks this up and begins routing data for the subscribed assets.

List Subscriptions

# All subscriptions (paginated)
GET /api/subscriptions?pageSize=20

# Filter by asset
GET /api/subscriptions?assetId=pump-001

# Next page
GET /api/subscriptions?pageSize=20&continuationToken=<token>

Get by ID

GET /api/subscriptions/{subscriptionId}

Unsubscribe (Delete)

DELETE /api/subscriptions/{subscriptionId}

Soft-deletes the subscription and publishes a subscription.deleted CloudEvent. The Asset Processor stops routing data for this subscription.

MQTT Topic Structure

Published asset data follows a versioned, hierarchical topic structure:

beacontower/v1/assets/{assetId}/{stream}

Asset Data Streams

Topic	Description
beacontower/v1/assets/{assetId}/telemetry	Sensor readings and measurements
beacontower/v1/assets/{assetId}/diagnostics	Device health and status information
beacontower/v1/assets/{assetId}/properties	Asset metadata and property updates
beacontower/v1/assets/{assetId}/commands	Commands sent to the asset
beacontower/v1/assets/{assetId}/responses	Asset responses to commands

System Topics

Topic	Description
beacontower/v1/alarms/raised	Newly raised alarms
beacontower/v1/alarms/cleared	Cleared alarms
beacontower/v1/events/system	System-level events
beacontower/v1/events/audit	Audit trail events

Wildcard Subscriptions

MQTT clients can use wildcards when subscribing on the broker:

Pattern	Matches
beacontower/v1/assets/+/telemetry	Telemetry from all assets
beacontower/v1/alarms/+	All alarm types
beacontower/v1/#	Everything under the root

How It Works

Data Flow

The Publisher is a thin forwarding layer. It does not process or transform data — it receives pre-filtered, pre-serialized payloads from the Asset Processor and publishes them to the MQTT broker.

1. Subscription registered — A backend service creates a subscription via the API
2. Asset Processor notified — The subscription.created CloudEvent tells the Asset Processor which assets to track
3. Asset Processor routes data — For each subscribed asset, the Asset Processor sends telemetry and diagnostic events to NATS with pre-computed topics and serialized payloads
4. Publisher receives events — A background NATS consumer picks up these events
5. Publisher writes to MQTT — The event handler publishes the payload to the MQTT broker on the specified topic with QoS 1 (at least once) delivery

CloudEvents

The Publisher emits lifecycle events to NATS JetStream:

Event	Trigger	Consumer
subscription.created	New subscription via API	Asset Processor starts routing data
subscription.deleted	Subscription removed via API	Asset Processor stops routing data

The Publisher also consumes events from the Asset Processor:

Event	Source	Action
Telemetry event	Asset Processor	Publish to MQTT broker
Diagnostic event	Asset Processor	Publish to MQTT broker

Reliability

• QoS 1 (At Least Once) delivery to the MQTT broker
• Automatic reconnection with exponential backoff on broker disconnect
• Retry logic with configurable max attempts on publish failure
• Soft delete on subscriptions preserves audit history

Architecture

┌─────────────────────────────────────────────┐
│ MQTT Publisher                               │
│                                              │
│  Subscription API ◄── Backend Services       │
│       │                                      │
│       ├─► PostgreSQL (subscriptions)         │
│       └─► NATS (subscription.created/deleted)│
│                                              │
│  NATS Consumer ◄── Asset Processor           │
│       │              (telemetry/diagnostic)   │
│       └─► MQTT Broker ──► External Systems   │
└─────────────────────────────────────────────┘

Dependencies

Component	Role
PostgreSQL	Stores subscription state
NATS JetStream	Subscription lifecycle events (outbound) and asset data events (inbound)
Mosquitto	MQTT broker for publishing asset data to subscribers
Azure AD B2C	Authentication for the subscription management API

Where It Fits

Asset Processor
  → reads subscriptions from Publisher
  → collects data for subscribed assets
  → sends telemetry/diagnostic events to NATS
        │
        ▼
  MQTT Publisher (NATS consumer)
        │
        ▼
  MQTT Broker
        │
        ▼
  Dashboards, Analytics, Integrations

The Asset Processor reads the Publisher's subscription list to decide which processed asset data to route for MQTT publication.

Next Steps

• SignalR Streaming — Real-time push notifications over WebSocket
• REST API — Query historical and latest asset data over HTTP
• Telemetry Ingestion — How raw telemetry enters the platform via NATS