MQTT Destination Connector

The MQTT Destination connector publishes data from the Mapped graph to an MQTT broker. This connector acts as a data destination, streaming Mapped entities and their latest timeseries values to configurable MQTT topics. It supports MQTT protocol versions 3, 4, and 5, with flexible authentication options including username/password and TLS certificate-based authentication.

Use Cases

• Real-time Data Distribution: Stream building automation data from Mapped to external systems via MQTT for real-time monitoring and control applications.
• IoT Platform Integration: Publish Mapped graph data to IoT platforms and edge devices that consume MQTT messages for analytics and visualization.
• Event-Driven Architectures: Enable downstream systems to react to changes in building data by subscribing to MQTT topics populated with Mapped entities and points.

Configuration

Auth Requirements

To configure the MQTT Destination connector, you need:

• MQTT Broker URL: The endpoint of your MQTT broker (e.g., mqtt://broker.example.com:1883 or mqtts://broker.example.com:8883)
• Base Topic: The MQTT topic where data will be published

Optional Authentication Credentials (at least one method recommended):

• Username/Password: Basic authentication credentials for the MQTT broker
• TLS Certificates: For secure MQTTS connections:
• Client Key: Private key for client authentication
• Client Key Passphrase: Passphrase for the client key (if encrypted)
• Client Certificate: Client certificate for mutual TLS authentication
• Server CA: Certificate Authority certificate to verify the broker's identity

Place Mappings

This connector does not require place mappings as it publishes existing data from the Mapped graph rather than ingesting data from an external source.

Advanced Options

Protocol Version

• Options: 3, 4, or 5
• Description: MQTT protocol version to use when connecting to the broker. Version 5 is set as the default and includes enhanced features like improved error reporting and session management.

Client ID

• Unique identifier for this MQTT client connection. If not specified, a default identifier will be generated automatically based on the username and system information.

Reconnect Backoff (seconds)

• The delay in seconds before attempting to reconnect to the MQTT broker after a connection failure. Configuring this helps manage reconnection behavior in unstable network conditions.

Keepalive

• The interval in seconds for keepalive ping messages sent to the MQTT broker to maintain the connection. This ensures the broker knows the client is still active.

Graph Entities & Timeseries

Entities

This connector does not create entities in the Mapped graph. Instead, it reads existing entities and publishes them to MQTT topics.

Published Data Structure

The connector publishes all entities from the Mapped graph with the following structure:

Thing entities are published with these fields:

• id: Entity identifier
• name: Entity name
• description: Entity description
• firmwareVersion: Firmware version information
• mappingKey: Mapping key for the entity
• dateCreated: Creation timestamp
• dateUpdated: Last update timestamp
• model: Associated model information including manufacturer details
• hasLocation: Related location entity references
• hasPart: Child entity references
• hasPoint: Associated timeseries points with latest values

Timeseries point data includes:

• id: Point identifier
• name: Point name
• description: Point description
• exactType: Specific point type
• valueMap: Value mapping configuration
• datatype: Data type of the point (BOOL, INT, DOUBLE, STRING, JSON)
• unit: Unit of measurement
• series: Latest timeseries value with timestamp and simplified value format

Published Point Data Types

The connector supports publishing the following datatypes:

Mapped Datatype	Published Format	Description
BOOL	Boolean	True/false values
INT	Integer	32-bit integer values
DOUBLE	Float	64-bit floating point values
STRING	String	Text values
JSON	JSON Object	Complex structured data

Each published point includes:

• timestamp: ISO 8601 formatted timestamp of the latest reading
• simpleValue: The point value in its native format (automatically determined from the datatype)

Message Format

Published MQTT messages contain the complete entity structure in JSON format, with timeseries points including their latest simplified values for easy consumption by downstream systems.