Node-Red provides both an MQTT subscribe (input) and publish (output) node.
The configuration for these nodes are almost Identical as the main part of the configuration concerns the actual client connection.
Because of this it is useful to think of the publish and subscribe nodes as consisting of two components as shown in the schematic below:
Before we look a the actual configuration we will look at MQTT client connections in general.
How MQTT works
If you are unfamiliar with the MQTT protocol I would recommend that you take a read of how MQTT works before Continuing
Connecting to an MQTT Broker or Server.
To connect to an MQTT broker or server you need to know the Broker IP address or name, and the port that it is using (default 1883).
In addition a client needs to provide a client name to identify itself. Each client connection requires a unique client name.
A single client connection can be used to both publish and subscribe.
An MQTT broker can enforce encryption and username/password authentication in which case the connecting client must comply.
There are various flags and parameters that a client can set. These are:
- Clean Session Flag
- Time to Live
- Last Will and Testament
Clean Session Flag
MQTT clients will usually by default establish a clean session with a broker.
A clean session is one in which the broker isn’t expected to remember anything about the client when it disconnects.
With a non clean session the broker will remember client subscriptions and may hold undelivered messages for the client.
Time to Live
This is a mechanism used to determine if a connection is still present. The default interval is 60 seconds.
Last Will and Testament
The idea of the last will message is to notify a subscriber that the publisher is unavailable due to network outage.
The last will message is set by the client on a topic and is stored on the broker.
It Is sent to all subscribers if the publishing client disconnects abnormally.
If the publisher disconnects normally the last Will Message is not sent.
By default the node connects automatically when you start the flow, however node-red now supports dynamic connections that allow you to control the connection.
Publishing MQTT Messages- The Publish Node
When a client publishes a message to a broker it needs to send:
- The message topic
- The message QOS
- Whether the message should be retained.- Retain Flag
The retain Flag is normally set to False which means that the broker doesn’t keep the message.
If you set the retain flag to True then the last message received by the broker with the retained flag set will be kept.
The QOS of the published message has no effect on the retained message.
The retain flag setting is the only setting that is unique to the publish node.
To publish a Message to an MQTT broker you use the MQTT publish node.
To use a publish node drag the node from the node palette on the left into the main workspace.
Double click on the node to configure it. The main configuration screen is shown below:
The main setting is the broker or server setting.
You can select a previously configured server which you can edit by clicking on the edit button, or add a new broker by selecting the add new mqtt server option from the server list.
The server name that appears in the server list is a combination of the client ID and Broker name or IP address.
Note: The MQTT specification originally used the term broker but it has now been changed to server.
You can also configure the topic address,the QOS for the message and the retain flag.
The topic address,the QOS and the retain flag can also be provided by the preceding node as part of the message object using:
- msg.topic =mytopic
- msg.qos =0,1 or 2
- msg.retain =true or false
Publish Message Format
If you pass in numeric data it is converted to a string and if you pass in Boolean data it is also converted into a string before being published.
Editing the Server Settings
If you click on the edit icon to the right of the server you can edit the server settings.
The server settings has 4 tabs.
- connection tab
- Birth Message
- Will Message
The port defaults to 1883 which is the standard MQTT port.
You can use either the IP address or FQDN for the server address.
The client name needs to be unique on the broker.
You can configure the client to use SSL for the connection by enabling the TLS box- see later
The default keep alive is 60 secs and clean session is False. It is normal to enable clean sessions.
This lets you configure a user name and password for the connection.
Whether you need a username/password for the connection is determined by the MQTT broker.
The birth message is published by the client when the MQTT node starts.
A birth message is not part of the MQTT specification but it is part of the Sparkplug specification.
The Will message is part f the MQTT specification and is stored on the broker, and sent in the advent of a failed client connection.
The message payload will either be a message to indicate the connection has failed or a status indicator.
The retained message will usually be set so that new clients know the status.
Using SSL for Encryption
The client supports SSL encryption between the client and server as well as using certificate based authentication.
To configure a secure connection you will need enable TLS
and add the CA certificate to node-red by uploading it. In the screen shot below I used the same self generated certificate as I used on Mosquitto broker.
If the CA file is on your local computer you can use it by enabling the use key and certificates from local files option., and entering the path and file name:
Alternatively you can upload the files using the upload buttons.
Note: the verify server certificate checks the the name on the certificate is correct and should be enabled on live systems. Leaving it un-checked is like using the -insecure option of the mosquitto_pub /_sub tool. Entering a name in the box doesn’t seem to make any difference.
If you are using Client certificates then you will also need to upload or provide the pathname to the client key and certificate as shown below:
SSL Public Certificates
If you are using a public broker like cloudmqtt then you will need to use a public CA.
You will need to get a copy of ca-certificates.crt or ca-certificates.pem file.
This file contains a list of trusted CA certificates and is available from Mozilla.
If you are using Linux it is usually in /etc/SSL/certs, but you can download it from the curl site here.
You will then need to upload it, just like with the self generated certificate as shown in the screen shot below.:
Configuring The Subscribe Node
When a client subscribes to a broker it needs to provide a topic and QOS.
The subscribe node has no unique settings.
To use a subscribe node drag the node from the node palette on the left into the main workspace.
Double click on the node to configure it. The main configuration screen is shown below, and is almost identical to the publish node.
Note: You don’t currently appear to be able to subscribe to multiple topics using the same node.
Prior to version .20 the received payload was either a string or buffer object (if detected by the node)
In version .20 you can choose the expected payload type using a new drop down box as shown below.
Editing A subscribe or Publish Node Using the Same Client connection Name
If 2 or more nodes anywhere in the Workspace use the same connection name e.g.
A publish node uses the connection name
firstname.lastname@example.org:1883 and another node or nodes (publish or subscribe) use that connection name.
Then changes to the connection properties e.g port number,clean sessions etc will affect all of the nodes using that connection name.
I’ve created a video on how to Publish and Subscribe to an MQTT broker Using Node Red
There have been quite a few changes in the MQTT nodes starting in version 2.
The first most important change was the addition to MQTT v5 features to the MQTT Nodes.
MQTTv5 introduced many new features. See- MQTT v5 Features for details
MQTT clients need to indicate to the broker what MQTT version they are using. Node-red currently defaults to 3.1.
It is part of the connection settings
If you configure the node for MQTTv5 the publish and subscribe node will contain extras settings other than those shown above.
To understand these extra settings you should acquaint yourself with the new features.
Node-red version 2.1 has introduced new dynamic node features allowing connections,subscriptions and broker settings to be controlled dynamically.
Using these features you have much better control of the MQTT connections. see MQTT Dynamic Connections
If you are using mosquitto for the broker you should be aware of the security changes in mosquitto v2.
By default it requires authentication and doesn’t listen on a network address.
The following simple configuration file will make mosquitto start like previous versions:
listener 1883 allow_anonymous true
- MQTT Dynamic Connections
- How to Install and Run The Aedes Broker on Node-Red
- MQTT Data Logger -Node-Red
- Node-Red HTTP Request Node for Beginners
- Node-Red Configuration Nodes Overview