MQTT Client Data Source

The MQTT Client data source connects Mango to an MQTT Broker, enabling Mango to subscribe to topics and receive data as it is published. MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol widely used in IoT, telemetry, and industrial applications. Unlike polling-based protocols, MQTT is event-driven -- data arrives at Mango as soon as it is published to the broker, with no wasted bandwidth when values are unchanged.

This data source acts as an MQTT client that subscribes to one or more topics on a broker. Each data point subscribes to its own topic and can optionally publish values back to the broker, making points settable for bidirectional communication.

Overview

Property	Value
Module	mangoAutomation-Mqtt
Protocol	MQTT v3.1.1
Direction	Bidirectional (subscribe + publish)
Typical Use	IoT device data collection via MQTT broker

Prerequisites

• An MQTT broker accessible over the network (e.g., Mosquitto, HiveMQ, EMQX, AWS IoT Core, or any MQTT 3.1/3.1.1 compatible broker).
• The broker URI in the format tcp://hostname:1883 (plain TCP) or ssl://hostname:8883 (TLS-encrypted).
• Knowledge of the topic structure used by the publishing devices.
• For TLS connections: the CA certificate in PEM format if the broker uses a non-public certificate authority.
• For authenticated brokers: username and password credentials.

Configuration

Data Source Settings

Setting	Description
Name	A descriptive name for the data source.
Broker URI	The MQTT broker address. Use tcp:// for plain connections or ssl:// for TLS-encrypted connections. Example: tcp://192.168.1.50:1883.
Client ID	A unique identifier for this Mango MQTT client, used by the broker to track session state. Must be less than 65,535 characters and unique among all clients connecting to the same broker.
Clean session	Controls whether the broker retains session state across reconnects (see details below).
Auto reconnect	When enabled, Mango automatically reconnects after connection loss with exponential back-off (starting at 1 second, doubling to a maximum of 2 minutes).
QoS type	Quality of Service level for subscriptions (0 = at most once, 1 = at least once, 2 = exactly once).
Keep alive interval	Seconds between keepalive ping messages. If no data is exchanged within this period, Mango sends a ping to detect broken connections. Default: 60 seconds. A value of 0 disables keepalive.
Connection timeout	Maximum seconds to wait for the initial connection to the broker. Default: 30 seconds. A value of 0 disables the timeout.
X509 CA (PEM format)	(Optional) The CA certificate in PEM format for TLS connections. The broker's server certificate must be signed by this CA.

Clean Session Behavior

Setting	Effect
false (durable)	The broker retains subscriptions and queues messages for this client when disconnected. Upon reconnect, any messages published while offline are delivered. This ensures reliable delivery but uses broker storage.
true (non-durable)	The broker discards all session state when the client disconnects. No messages are queued during disconnection.

For most Mango deployments, set Clean session to false and Auto reconnect to true. This ensures that short network outages do not cause data loss, because the broker will queue messages and deliver them when Mango reconnects.

Data Point Configuration

Each MQTT data point subscribes to a specific topic and can optionally publish to a topic.

Setting	Description
Subscribe topic	The MQTT topic to subscribe to for receiving values.
Publish topic	(Optional) The MQTT topic to publish to when setting values. If not configured, the point is read-only.
Topic type	How to interpret message payloads: Plain, JSON, or JSON with Timestamp.
Data type	The Mango data type: Numeric, Binary, Multistate, or Alphanumeric.
Multiplier / Additive	For numeric points: displayed = (raw * multiplier) + additive. The reverse is applied on publish.

Topic Types

Plain: The message payload is read and written as a simple string value. A message containing 72.5 on a numeric point will store the value 72.5.

JSON: The message payload is a JSON document, and the point value is extracted using a JSON Pointer (RFC 6901). This is useful when a single MQTT message contains multiple values in a JSON object.

• Subscribe JSON pointer: Path to the value within the JSON document (e.g., /temperature).
• Publish property name: JSON property name used when publishing values as a JSON object.

JSON with Timestamp: Like JSON, but also extracts a timestamp from the JSON document. This is useful when the publishing device includes a timestamp with each value.

• Value JSON pointer: Path to the value.
• Timestamp JSON pointer: Path to the timestamp.
• Timestamp format: A Java DateTimeFormatter pattern (e.g., yyyy-MM-dd'T'HH:mm:ss.SSSZ).
• Publish value property: Property name for the value when publishing.
• Publish timestamp property: Property name for the timestamp when publishing.

JSON Pointer Examples

Given this JSON message:

{
  "sensors": {
    "temperature": 72.5,
    "humidity": 45.2
  },
  "timestamp": "2026-02-16T14:30:00Z"
}

JSON Pointer	Extracted Value
/sensors/temperature	72.5
/sensors/humidity	45.2
/timestamp	"2026-02-16T14:30:00Z"

JSON Pointer uses / as a path separator. Special characters are escaped: ~0 represents ~ and ~1 represents /. Array elements are accessed by index (e.g., /items/0 for the first element).

Common Patterns

IoT Sensor Networks

Many IoT sensor platforms publish data to MQTT topics in a hierarchical structure such as:

building/floor1/room101/temperature
building/floor1/room101/humidity
building/floor1/room102/temperature

Create one data point per topic, using the Plain topic type if each message contains a single numeric value, or the JSON topic type if messages contain structured data.

Sparkplug B Integration

For Sparkplug B-compatible devices, Mango offers a separate MQTT Sparkplug Data Source module designed specifically for the Sparkplug B protocol. Use the MQTT Client data source for general-purpose MQTT communication and the Sparkplug data source when connecting to Sparkplug B infrastructure.

Bidirectional Control

To both read sensor data and send commands through MQTT:

1. Set the Subscribe topic to the topic where the device publishes its current state (e.g., device/thermostat/current-temp).
2. Set the Publish topic to the topic where the device listens for commands (e.g., device/thermostat/set-temp).
3. When a user sets the point value in Mango, the value is published to the command topic.

JSON Messages with Multiple Values

When a device publishes a single JSON message containing multiple measurements:

{"temp": 72.5, "humidity": 45, "pressure": 1013.25}

Create three data points all subscribing to the same topic, each with a different JSON Pointer:

• Point 1: Topic type = JSON, Pointer = /temp
• Point 2: Topic type = JSON, Pointer = /humidity
• Point 3: Topic type = JSON, Pointer = /pressure

Each point extracts its specific value from the shared message.

TLS-Secured Connections

For production deployments, always use ssl:// connections. If the broker uses a certificate signed by a public CA (e.g., Let's Encrypt), no additional configuration is needed. If the broker uses a self-signed or private CA certificate:

1. Obtain the CA certificate in PEM format.
2. Paste the certificate contents into the X509 CA (PEM format) field.
3. Save and enable the data source.

Troubleshooting

Broker URI Format Reference

The MQTT Client data source accepts four URI schemes:

Scheme	Transport	Example
tcp://hostname:port	Plain TCP (unencrypted)	tcp://localhost:1883
ssl://hostname:port	TLS-encrypted	ssl://broker.example.com:8883
ws://hostname:port/path	WebSocket (unencrypted)	ws://broker.example.com:8083/mqtt
wss://hostname:port/path	WebSocket + TLS	wss://broker.example.com:8084/mqtt

Common URI mistakes and their symptoms:

Incorrect URI	Problem
tcp:/broker.example.com:1883	Missing slash — must be tcp://
ssl://broker.example.com	Missing port — always specify explicitly
ws://broker.example.com:8083	Missing WebSocket path (e.g., /mqtt)
tcp://localhost:abcd	Non-numeric port — will cause a parse error
tcp://	Missing hostname and port

Connection Failures

1. Verify the broker URI -- ensure the scheme (tcp/ssl), hostname, and port are correct.
2. Check broker availability -- use an MQTT client tool (e.g., mosquitto_sub, MQTT Explorer) to verify the broker is reachable.
3. TLS errors -- if using ssl://, verify the CA certificate is correct and the broker's certificate is valid.
4. Authentication -- verify username and password if the broker requires authentication.
5. Client ID conflicts -- if another client is connected with the same Client ID, the broker may disconnect one of them. Ensure the Client ID is unique.

No Data Received

1. Verify the topic name -- MQTT topics are case-sensitive. A subscription to Temperature will not receive messages published to temperature.
2. Check QoS settings -- QoS 0 does not guarantee delivery. If messages are being lost, try QoS 1 or 2.
3. Verify the publisher is active -- check that the upstream device is actually publishing to the expected topic.
4. Check the topic type -- if using JSON topic type, verify the JSON Pointer matches the actual message structure.
5. Wildcard subscriptions -- note that Mango data points subscribe to exact topics, not wildcard patterns. Each point must specify the full topic path.

Reconnection Issues

1. Auto reconnect disabled -- if the data source does not reconnect after a broker restart, enable auto reconnect.
2. Clean session true with no re-subscribe -- when clean session is true, the broker forgets all subscriptions on disconnect. Mango re-subscribes on reconnect, but messages published during the outage are lost.
3. Broker queue limits -- if clean session is false but the broker has a message queue limit, extended outages may cause the oldest messages to be discarded.

Data Parsing Errors

1. JSON parse failures -- verify the message payload is valid JSON when using JSON or JSON with Timestamp topic types.
2. Incorrect JSON Pointer -- use a JSON tool to validate the pointer against the actual message structure.
3. Timestamp format mismatch -- the timestamp format string must exactly match the format in the JSON message. Test with a sample message.
4. Numeric conversion failures -- if a message contains non-numeric text but the point is configured as Numeric, the value will not be stored.

MQTT Publisher

The MQTT Publisher is a separate module that pushes Mango point values to an MQTT broker on a schedule or when values change. Unlike the data source (which subscribes and receives data), the publisher sends data out.

Publisher Connection Settings

Setting	Description
Publisher ID	Unique identifier per broker.
MQTT Transport	TCP, TLS, WebSocket, or WebSocket + TLS.
Broker Host / Port	Hostname and port of the broker. Defaults: 1883 (TCP), 8883 (TLS).
WebSocket Path	Required for WebSocket transports (e.g., /mqtt).
Username / Password	Authentication credentials.
MQTT Version	3.1.1 or 5.0.
Keep Alive Interval	Seconds between keepalive pings.
Socket / MQTT Connect Timeout	Milliseconds to wait for connection.
Initial / Max Reconnect Delay	Reconnect back-off timing (ms).

Publisher Payload Settings

Setting	Description
MQTT Payload Format	JSON or Protobuf.
Topic	The MQTT topic to publish to.
Interpolate Topic	When enabled, the topic is evaluated as an expression (e.g., ${!xid}).
Tags	Key-value pairs appended to the payload for structured data.

Last Will Message (Optional)

Configure a Will Message that the broker automatically publishes if Mango disconnects abnormally:

Setting	Description
Will Topic / Payload	Topic and message content for the Will.
QoS	Quality of Service for the Will (0, 1, or 2).
Retain	Whether the broker retains the Will for new subscribers.
Message Expiry Interval	(MQTT v5) Duration the broker holds the Will message.

MQTT v5 Features

MQTT 5.0 publishers support additional metadata:

• Connect User Properties — key-value metadata sent on connection.
• Response Topic — topic for request/response patterns.
• Correlation Data — links requests to responses.
• Content Type — describes the payload (e.g., application/json).
• Last Will Delay Interval — delay (seconds) before the broker publishes the Will.

Related Pages

• Data Sources Overview — General data source and data point concepts including event-driven collection
• HTTP Receiver Data Source — Another event-driven data source for receiving pushed data from external systems
• OPC UA Data Source — Another protocol supporting subscription-based updates for industrial data
• Persistent TCP Data Source — High-speed data synchronization between Mango instances