MQTT In

This node connects to an MQTT broker and subscribes to messages from a specified topic.

The MQTT server is automatically configured and managed by FlowFuse. When this node is added to the canvas, a corresponding MQTT broker client is created automatically. The connection settings are handled internally, requiring no manual configuration.

Topic

Defines the topic to subscribe to. The topic can include MQTT wildcards:

+ for a single-level wildcard
# for a multi-level wildcard

QoS (Quality of Service)

Specifies the message delivery guarantee level:

0: Fire and forget
1: At least once
2: Once and once only (default)

If not defined, the default value is 0.

Output Properties

When a message is received, the node outputs the following properties:

msg.payload: The message content. Strings are passed as-is, and binary data is output as a Buffer.
msg.topic: The topic on which the message was received.
msg.qos: The QoS level of the received message.
msg.retain: True if the message was retained on the broker.
msg.responseTopic: MQTTv5 response topic.
msg.correlationData: MQTTv5 correlation data.
msg.contentType: MQTTv5 content type of the payload.
msg.userProperties: MQTTv5 user properties.
msg.messageExpiryInterval: MQTTv5 message expiry time in seconds.

Dynamic Subscription Control

The MQTT In node can be configured to dynamically manage connections and topic subscriptions. When this feature is enabled, the node accepts control messages through its input.

Input Properties

These inputs only apply when dynamic subscriptions are enabled:

msg.action: Defines the action to perform. Supported actions include: "connect", "disconnect", "getSubscriptions", "subscribe", and "unsubscribe".

For "connect", msg.broker this can override broker configuration properties such as:
- broker
- port
- url (overrides broker and port)
- username
- password
- clientid
- cleansession
If a broker is already connected, an error is logged unless force is specified. In that case, the node disconnects, applies the new settings, and reconnects with the updated configuration.

For "subscribe" or "unsubscribe", msg.topic specifies the target topic(s). This can be:

A string containing a single topic filter.
An object containing topic and qos properties.

An array of strings or objects for multiple topics.
Subscribes to one or more topics.

// Single topic
msg.action = 'subscribe';
msg.topic = 'sensors/temperature';

// Single topic with QoS
msg.action = 'subscribe';
msg.topic = { topic: 'sensors/temperature', qos: 1 };

// Multiple topics
msg.action = 'subscribe';
msg.topic = ['sensors/temperature', 'sensors/humidity'];

// Multiple topics with QoS
msg.action = 'subscribe';
msg.topic = [
  { topic: 'sensors/temperature', qos: 1 },
  { topic: 'sensors/humidity', qos: 2 }
];

Unsubscribe

Removes subscriptions from one or more topics.

// Single topic
msg.action = 'unsubscribe';
msg.topic = 'sensors/temperature';

// Multiple topics
msg.action = 'unsubscribe';
msg.topic = ['sensors/temperature', 'sensors/humidity'];

For getSubscriptions the msg.payload output is an array of subscription objects holding the topic and qos level
```
[
  { topic: 'sensors/temperature', qos: 1 },
  { topic: 'sensors/humidity', qos: 2 }
]
```

Example: Cheerlights

This example subscribes to the public topic cheerlights/coloured/hex on the Mosquitto test broker.
Each time a new color is published, the color code is displayed in the Debug panel.

Notes

The MQTT In node automatically reconnects if the connection to the broker is lost.
Retained messages are received immediately when subscribing to a topic that has one.
The node can work alongside the MQTT Out node for bi-directional communication.