MQTT
Dec 6 2023 at 12:00 AM
Introduction
The MQTT data source is configured to subscribe to one or more MQTT topics on a Broker. The payload for each message published to the specified topic(s) will consist of the raw bytes received.
MQTT topic paths support the use of wildcards:
- Use ‘#’ to represent one or more subtopics (e.g., “telemetry/#”)
- Use ‘+’ to represent one subtopic (e.g., “telemetry/+/temperature”)
Use topic parsing to set a Source Information key to a specific topic section. |
Example Options File
{
"Devices": {
"Device1": {
"DeviceType": "Generic",
...
"DataSource": {
"DataSourceType": "Mqtt",
"Host": "mqtt.raptor.iotnxt.io",
"PortNo": 1883,
"UseTls": false,
"UserName": "mqttuser",
"Password": "1qazxsw@",
"Topics": {
"Telemetry": "mqttTopic/telemetry/#"
},
"ParseTopic": [
"",
"",
"DeviceName"
]
},
...
}
}
}
Property Details
Here is an overview of the parameters for configuring the MQTT data source:
Property Name | Description |
---|---|
DataSourceType | Specifies that the data source is of type “Mqtt”. |
Host | Indicates the host name or IP address of the MQTT Broker. |
PortNo | Specifies the port number of the MQTT Broker, with a default value of 8883. |
Topics | A list of one or more Topic Names and their associated Topics to subscribe to. |
ParseTopic | A list of string values determining which topic sections are stored in the Source Information. Refer to the section below. |
UseTls | Determines whether to use TLS (Transport Layer Security) to connect to the Broker, with a default setting of true. |
ValidateTlsCertificate | Specifies whether to validate the broker’s certificate during connection, with a default setting of false. |
UserName | The authentication username. If left blank, an anonymous connection will be made. |
Password | The authentication Password. |
ReconnectDelay | The delay time, in milliseconds, after a disconnection before the client attempts to reconnect, defaulting to 5,000 milliseconds (5 seconds). |
CleanSessions | Specifies whether clean sessions are used or not. Defaults to true. |
NoLocal | Determines whether messages published to a topic by this client are ignored by any subscriptions to the same topic. Defaults to true. |
QOSLevel | The Quality-of-Service Level for publishing and subscribing, defaulting to “AtLeastOnce”. Refer to the section below. |
RetainAsPublished | Specifies whether to set the retain flag on the published message. This tells the broker to keep the last message on that topic. On subscription, depending on the value of RetainHandling the last retained message will be sent. Defaults to false. |
RetainHandling | Sets how retained messages are managed on subscription. Defaults to “SendAlways”. See below. |
KeepAlivePeriod | The time in milliseconds for the keep-alive message. Defaults to 15,000 (15 seconds). |
Topic Parsing
When one or more strings are included in the ParseTopic list, the data source will divide the topic path of the received message using ‘/’ as the delimiter. If a string in the ParseTopic list is not blank (“”), the corresponding section of the topic path will be loaded into the Source Information with the specified key. For instance, suppose the topic path is “mqtttopic/telemetry/ABC123/temperature”, and the ParseTopic list is configured as [ “”, “”, “DeviceName” ]. In this case, the following key value pair will be added to the Source Information:
“DeviceName” = “ABC123”
QOSLevel Options
Here is an overview of the MQTT QOSLevel Options:
QOSLevel | Value | Description |
---|---|---|
AtMostOnce | 0 | Once (not guaranteed). This is the fastest method and requires only 1 message. It is also the most unreliable transfer mode. The message will be delivered only once, or not at all. |
AtLeastOnce | 1 | At Least Once (guaranteed). This level guarantees that the message will be delivered at least once but may be delivered more than once. |
OnlyOnce | 2 | Only Once (guaranteed). This level guarantees that the message will be delivered only once. |
RetainHandling Options
Here is an overview of the MQTT RetainHandling Options:
RetainHandling | Value | Description |
---|---|---|
SendAlways | 0 | Send retained messages at the time of the subscribe (original MQTT behaviour). |
SendIfNew | 1 | Send retained messages on subscribe only if the subscription is new. |
DoNotSend | 2 | Do not send retained messages at all. |
Configuration of the MQTT data source node
Every device should include the Device Information, Data Source, and Filter nodes. To create a device, click the +
icon located on the top-left side of the ‘Create Device’ screen as shown in Figure 1. This action opens a configuration window for the device. Within this screen, users can select and add the necessary nodes. To add a node, access the ‘Add Node’ window, as illustrated in Figure 2.
Figure 1 - Create Device
The window below enables the user to add and configure a data source node.
Figure 2 - Add Node
The MQTT node consists of features to:
- Configure the node: Allows users to customize and adjust the settings of the selected node according to their requirements.
- Show nodes compatible with the selected node: Displays nodes that are compatible with the selected node, providing a streamlined view of related options.
- Bring up the help centre for the node: Directs users to the help centre for the selected node, offering detailed guidance and documentation.
- Copy icon: Permits users to duplicate the selected node, facilitating efficient replication of configurations.
- Delete the node: Enables users to remove the selected node from the configuration, allowing for adjustments and refining the setup.
Figure 3 - Node Features
Upon selecting the configure button in Figure 3, the window for the MQTT data source node is presented as illustrated in Figure 4. In this interface, users can input and edit relevant information for configuring the MQTT data source.
Figure 4 - MQTT data source node
The breakdown below helps clarify the functionality and significance of each parameter in the configuration of the MQTT data source.
- Data Source Options: This feature enables users to establish the origin and method type of the data source.
- Data source type
- Configuration path
- Host
- Port
- Topics: Users post their routing key, and the system selects the topic based on that input. Parse topics are simplified representations of these topics.
- Use TLS and Validate TLS Certificate: These checkboxes pertain to security certificates, with “Use TLS” indicating whether to establish a secure TLS connection and “Validate TLS Certificate” specifying whether to validate the broker’s TLS certificate during connection.
- Authentication: Involves the use of a username and password for authorization.
- Reconnect Delay, Clean Sessions, and No Local: These parameters are tied to the execution function of this data source. Reconnect delay is the time delay after disconnection before attempting to reconnect. Clean sessions determine whether clean sessions are used. No Local specifies whether messages published to a topic by this client are ignored by any subscriptions to the same topic.
- QOS Level: Denotes the Quality-of-Service level for publishing and subscribing.
- Retain as Published: Determines whether messages should be retained after being received.