MQTT is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices to the cloud with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, oil and gas, building automation, etc...
MQTT has typically a central endpoint, the MQTT broker (server), that gets information from MQTT clients (TCP clients) such as sensors and retransmits the data to other MQTT clients, such as a smartphone applications or building management systems. Each MQTT client can publish data into its corresponding MQTT topics, and/or subscribe to MQTT topics of interest. Note that the MQTT broker acts mainly as a communication hub redistributing the data between the clients.
In most cases, the universal IoT gateway acts as a MQTT client and connects to the IoT Cloud of a third part company. The following article Airthings To Bacnet shows an use case where the MQTT driver is connected as client to the the Airthings cloud (Airthings MQTT broker).
Note that many IoT clouds such as Microsoft Azure, Google Nest, AWS IoT Core are communicating using the MQTT protocol, but have very specific additional application layers on top of it for security, authentication, and data communication. It follows that the generic MQTT client cannot be used to connect to these clouds, but it is necessary to use specific drivers (... TODO ADD LINK TO DRIVERS PAGE)
¶ 1. Getting started
This section shows how to establish connection with the mosquitto public MQTT broker. Two MQTT clients are configured, the first MQTT will be connected with simple MQTT (no encryption) and publish data to the broker, while the second client will be connected through WSS (WebSocket Secure) and subscribe to receive the published data.
The screenshot below shows the parameters for the connection. The first MQTT client gateway is named "MQTT demo" and it uses the standard MQTT protocol version 4 on the MQTT port 1883 without encryption.
A MQTT topic address can easily be added by selecting the Addresses menu and clicking on "Insert address". Here the MQTT topic is named "IoT_gateway". As we will later add subtopics to publish different kind of data (air temperature, air quality, and air humidity), the datatype "parentJson" is selected.
After creating the parent topic, a child address named %mqtt:IoT_gateway/temperature is added. This new topic will be used to publish temperature data, so its datatype must be "number".
In the same manner, two additional addresses are added %mqtt:IoT_gateway/airQuality and %mqtt:IoT_gateway/humidity. Once the 3 addresses are added, you can manually publish new values (here 53, 60, and 23.4) on the topics. Note that because the parent topic %mqtt:IoT_gateway is configured with the datatype "parentJson", it gets automatically updated with a JSON object containing the children values.
In the following screenshot, a second MQTT client gateway over WebSocket Secure (WSS) is created. This new MQTT client will subscribe to our IoT_gateway MQTT topics. To do so, the address with name mqtt:IoT_gateway/+ is created. The + symbol is a wild card single level subscription. It means that the MQTT client subscribes to all topics following this pattern IoT_gateway/[XYZ], where XYZ does not contain additional levels (/ character). The addresses (here %mqtt:IoT_gateway/airQualityIndex, %mqtt:IoT_gateway/humidity, and %mqtt:IoT_gateway/temperature) are automically added when the broker transmits the new messages to the client. Note that some MQTT brokers do not automatically send the last known message on topic subscription, in this case it is needed to wait for a new message to be published. When you publish manually new messages from the first MQTT client named "MQTT demo", you can notice that the new values are received on the second MQTT client. If you want to subscribe to multi-level topics, the # wildcard symbol can be used. Check this article about best practices for more explanations about MQTT wildcards subscriptions.
¶ 2. Gateway
The MQTT driver can be configured either as a MQTT broker (server) or as a client. The mode parameter lets you select if you want to be "broker" or "client" (see table below).
| Label | JSON Key | Description |
|---|---|---|
| Mode | mode | The paramter is a string and its value is either "broker" or "client". A MQTT broker acts as a server and a communication hub between MQTT clients. On the other hand MQTT clients connect to their MQTT broker and subscribe / publish to MQTT topics. |
¶ 2.1 MQTT broker parameters
| Label | JSON Key | Description |
|---|---|---|
| useAuthenticate | serverOptions.useAuthenticate | Boolean parameter (checkbox) that determines wether the MQTT clients need to authenticate themselvese or not. |
| authenticate | serverOptions.authenticate | A list of users allowed to connect, identified by their username and password. It is formatted as a JSON object, the key being the name, and the value the password: {"Etienne" : "secretPassword123", "Patrick" : "earlyalzheimers"} |
| Interfaces | serverOptions.interfaces | A list of interfaces for the MQTT broker server to listen to. There is 3 types of supported protocols for server sockets TCP (mqtt), TLS (mqtts), WS (mqtt over websocket). Each interface type has its own set of sub parameters. |
¶ 2.1.1 TCP broker parameters
| Label | JSON Key | Description |
|---|---|---|
| Port | serverOptions.interfaces[n].port | Specifies the TCP port number on which the MQTT broker server listen. By default it should be 1883. |
| Host | serverOptions.interfaces[n].host | By default the server listens on all network interfaces (address 0.0.0.0), but a specific network interface address can be specified (such as 192.168.1.99). |
¶ 2.1.2 TLS broker parameters
| Label | JSON Key | Description |
|---|---|---|
| Port | serverOptions.interfaces[n].port | Specifies the TLS port number on which the MQTT broker server listen. By default it should be 1883. |
| Host | serverOptions.interfaces[n].host | By default the server listens on all network interfaces (address 0.0.0.0), but a specific network interface address can be specified (such as 192.168.1.99). |
| Auto manage certs. | serverOptions.interfaces[n].auto | Boolean, specifies if security keys and certificates are managed automatically or manually. |
| Key | serverOptions.interfaces[n].key | Private key in PEM format, only used if security keys are managed manually. |
| Cert | serverOptions.interfaces[n].cert | Cert in PEM format, only used if security keys are managed manually. |
¶ 2.1.3 WS broker parameters
| Label | JSON Key | Description |
|---|---|---|
| Port | serverOptions.interfaces[n].port | Specifies the TCP port number on which the web server listens for new websockets. Defaults to 8888 |
| Host | serverOptions.interfaces[n].host | By default the server listens on all network interfaces (address 0.0.0.0), but a specific network interface address can be specified (such as 192.168.1.99). |
¶ 2.2 MQTT client parameters
| Label | JSON Key | Description |
|---|---|---|
| Host | clientOptions.host | Domain name or ip address of the MQTT broker. |
| Port | clientOptions.port | Port of the MQTT broker (usually 1883 for MQTT, and 8883 for MQTTS) |
| Protocol | clientOptions.protocol | MQTT transport layer: "mqtt" (TCP unencrypted), "mqtts" (TLS encrypted), "ws" (websocket over HTTP), "wss" (websocket over HTTPS). |
| Protocol version | clientOptions.protocolVersion | Select the MQTT protocol version 3, 4, or 5. |
| Client id | clientOptions.clientId | It is often not necessary to specify a client id. However some applications / brokers require you to configure a specific client id. |
| Username | clientOptions.username | The username is not always needed but can be necessary for autentication. |
| Password | clientOptions.password | Defining a password can be necessary for authentication. |
| URL Path | json.clientOptions.path | URL path for the websocket (only applies to ws and wss protocols) |
| rejectUnauthorized | clientOptions.rejectUnauthorized | Boolean. If true, the server certificate is verified against the list of supplied CAs. Only applies to mqtts and wss protocols. |
| cert | clientOptions.cert | Optional TLS cert in PEM format. |
| servername | clientOptions.servername | Optional TLS server name for the SNI (Server Name Indication). |
| passphrase | clientOptions.passphrase | TLS optional shared passphrase used for a single private key and/or a PFX. |
| ca | clientOptions.ca | Optional TLS trusted CA certificates. Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla. For self-signed certificates, the certificate is its own CA, and must be provided. |
| pfx | clientOptions.pfx | Optional TLS PFX or PKCS12 encoded private key and certificate |
| key | clientOptions.key | Optional TLS private keys in PEM format |
| ECDHCurve | clientOptions.ecdhCurve | Optional TLS ecdh curve name. A string describing a named curve or a colon separated list of curve NIDs or names, for example P-521:P-384:P-256, to use for ECDH key agreement. Set to auto to select the curve automatically. |
¶ 2.3 Gateway JSON examples
Examples taken from the 2 MQTT clients in the getting started tutorial.
{
"name": "MQTT demo",
"driver": "mqtt",
"description": "",
"active": 1,
"json": {
"mode": "client",
"serverOptions": {
"useAuthenticate": false,
"authenticate": "{}",
"interfaces": [
{
"type": "tcp",
"port": 1883
}
]
},
"clientOptions": {
"host": "test.mosquitto.org",
"port": 1883,
"path": "",
"protocol": "mqtt",
"protocolVersion": "4",
"clientId": "",
"username": "",
"password": "",
"rejectUnauthorized": false,
"servername": "",
"passphrase": "",
"ca": "[]",
"pfx": "[]",
"key": "[]",
"cert": "[]",
"ecdhCurve": "auto"
}
}
}
{
"name": "MQTT over WSS",
"driver": "mqtt",
"description": "",
"active": 1,
"json": {
"mode": "client",
"serverOptions": {
"useAuthenticate": false,
"authenticate": "{}",
"interfaces": [
{
"type": "tcp",
"port": 1883
}
]
},
"clientOptions": {
"host": "test.mosquitto.org",
"port": 8081,
"path": "",
"protocol": "wss",
"protocolVersion": "4",
"clientId": "",
"username": "",
"password": "",
"rejectUnauthorized": false,
"servername": "",
"passphrase": "",
"ca": "[]",
"pfx": "[]",
"key": "[]",
"cert": "[]",
"ecdhCurve": "auto"
}
}
}
¶ 3. Addresses
MQTT addresses start with the prefix %mqtt:, and the rest of the address name is the MQTT topic. MQTT topics can have multiple levels like a tree sucture. Each level is separated by the slash / character. Example of valid address names: %mqtt:IoT_gateway/airQualityIndex, %mqtt:IoT_gateway/humidity, %mqtt:IoT_gateway/temperature, %mqtt:MQTT_TOPIC/X/Y/Z. It is possible to have empty string between levels, although it is not recommanded, such as in %mqtt:/A or %mqtt:X//A
¶ 3.1 Addresses parameters
| Label | JSON Key | Description |
|---|---|---|
| Datatype | datatype | Supported MQTT messages encoding at the moment is plain text (utf-8) interpreted as "number", "string", "json", or "parentJson". For other encodings, please contact us. |
| Retain | retain | If this flag is set to true, it tells the broker that the messages published using this topic must be stored, or in other words, retained. This parameter only applies when the gateway is acting as a MQTT client. |
| QOS | qos | Desired Quality of Service (QoS) for messages delivery. There is 3 modes, "At most once" (QoS 0) "At least once" (QoS 1), and "Exactly once" (QoS 2). This parameter only applies when the gateway is acting as a MQTT client. |
¶ 3.2 Addresses JSON examples
{
"name": "%mqtt:IoT_gateway",
"description": "",
"json": {
"qos": 0,
"retain": false,
"datatype": "parentJson"
},
"value": {"airQualityIndex":12,"humidity":22,"temperature":23.4},
"value_string": "{\"airQualityIndex\":12,\"humidity\":22,\"temperature\":23.4}",
"value_date": 1696943247274
}
{
"name": "%mqtt:IoT_gateway/temperature",
"description": "",
"json": {
"qos": 0,
"retain": false,
"datatype": "number"
},
"value": 23.4,
"value_string": "23.4",
"value_date": 1696943247274
}