MQTT

#  What is are MQTT nodes used for in Node-RED

Node-RED comes with 2 MQTT nodes.

#  MQTT-in

The MQTT-in node is used to subscribe to a topic pattern on a given MQTT broker. This means messages published to a topic that matches the pattern will be delivered to the flow by this node.

#  MQTT-out

The MQTT-out noe is used to publish messages to a topic from the flow.

#  Configuring

Both of the nodes mentioned above make use a configuration node which holds all the details about connecting to a given MQTT broker. This includes things like:

  • hostname
  • port
  • username/password

MQTT Config Node

Node-RED supports MQTT v3.x and v5 as well as allowing connecting to brokers using both native MQTT and MQTT over WebSockets.

#  Examples

Simple publish and subscribe

Cheerlights

Node Documentation

Connects to a MQTT broker and subscribes to messages from the specified topic.

Outputs

payload string | buffer
a string unless detected as a binary buffer.
topic string
the MQTT topic, uses / as a hierarchy separator.
qos number
0, fire and forget - 1, at least once - 2, once and once only.
retain boolean
true indicates the message was retained and may be old.
responseTopic string
MQTTv5: the MQTT response topic for the message
correlationData Buffer
MQTTv5: the correlation data for the message
contentType string
MQTTv5: the content-type of the payload
userProperties object
MQTTv5: any user properties of the message
messageExpiryInterval number
MQTTv5: the expiry time, in seconds, of the message

Details

This node requires a connection to a MQTT broker to be configured. This is configured by clicking the pencil icon.

Several MQTT nodes (in or out) can share the same broker connection if required.

Dynamic Subscription

Inputs

These only apply when the node has been configured for dynamic subscriptions.

action string
the name of the action the node should perform. Available actions are: "connect", "disconnect", "subscribe" and "unsubscribe".
topic string|object|array
For the "subscribe" and "unsubscribe" actions, this property provides the topic. It can be set as either:
  • a String containing the topic filter
  • an Object containing topic and qos properties
  • an array of either strings or objects to handle multiple topics in one
broker broker
For the "connect" action, this property can override any of the individual broker configuration settings, including:
  • broker
  • port
  • url - overrides broker/port to provide a complete connection url
  • username
  • password

If this property is set and the broker is already connected an error will be logged unless it has the force property set - in which case it will disconnect from the broker, apply the new settings and reconnect.

Connects to a MQTT broker and publishes messages.

Inputs

payload string | buffer
the payload to publish. If this property is not set, no message will be sent. To send a blank message, set this property to an empty String.
topic string
the MQTT topic to publish to.
qos number
0, fire and forget - 1, at least once - 2, once and once only. Default 0.
retain boolean
set to true to retain the message on the broker. Default false.
responseTopic string
MQTTv5: the MQTT response topic for the message
correlationData Buffer
MQTTv5: the correlation data for the message
contentType string
MQTTv5: the content-type of the payload
userProperties object
MQTTv5: any user properties of the message
messageExpiryInterval number
MQTTv5: the expiry time, in seconds, of the message
topicAlias number
MQTTv5: the MQTT topic alias to use

Details

msg.payload

The topic used can be configured in the node or, if left blank, can be set by msg.topic.

Likewise the QoS and retain values can be configured in the node or, if left blank, set by msg.qos and msg.retain respectively. To clear a previously retained topic from the broker, send a blank message to that topic with the retain flag set.

This node requires a connection to a MQTT broker to be configured. This is configured by clicking the pencil icon.

Several MQTT nodes (in or out) can share the same broker connection if required.

Dynamic Control

Inputs

action string
the name of the action the node should perform. Available actions are: "connect", and "disconnect".
broker broker
For the "connect" action, this property can override any of the individual broker configuration settings, including:
  • broker
  • port
  • url - overrides broker/port to provide a complete connection url
  • username
  • password

If this property is set and the broker is already connected an error will be logged unless it has the force property set - in which case it will disconnect from the broker, apply the new settings and reconnect.

Configuration for a connection to an MQTT broker.

This configuration will create a single connection to the broker which can then be reused by MQTT In and MQTT Out nodes.

The node will generate a random Client ID if one is not set and the node is configured to use a Clean Session connection. If a Client ID is set, it must be unique to the broker you are connecting to.

Birth Message

This is a message that will be published on the configured topic whenever the connection is established.

Close Message

This is a message that will be published on the configured topic before the connection is closed normally, either by re-deploying the node, or by shutting down.

Will Message

This is a message that will be published by the broker in the event the node unexpectedly loses its connection.

WebSockets

The node can be configured to use a WebSocket connection. To do so, the Server field should be configured with a full URI for the connection. For example:

ws://example.com:4000/mqtt