MQTT connector

General principles of MQTT

MQTT (Message Queuing Telemetry Transport) is a real-time messaging protocol for exchanging data by topic with a publish / subscribe approach. A topic is a point (or a set of points) representing a piece of data (or a set of data).

The MQTT protocol is made up of two main types of entities:

• The MQTT broker: collects and makes available the requested data. It plays the role of server.
• The MQTT client: it can publish data to a broker and subscribe to receive data from a broker. OIBus is an MQTT client.

The connection to the MQTT broker

The MQTT client connects to the broker with different options:

• URL: of the form mqtt: // address: 1883. The 1883 port is the default MQTT port but may be different depending on the broker’s configuration.
• Authentication: it is possible to specify an authentication if the broker requires it. To do this, you must fill in the Username and Password fields.
• Quality of service (QoS): it offers three options specific to the MQTT protocol.


• QoS0: at most once . This means that the message is sent once but MQTT does not guarantee that the message will be received correctly. Good reception will depend on the quality of the underlying network of MQTT.
• QoS1: at least once . This means that the message is sent multiple times as duplicates until the client validates the correct receipt of at least one of the duplicates. In some cases, the client may then receive the same message more than once.
• QoS2: exactly once . This means that the message is sent only once, and a new attempt to send takes place after a certain time until the client confirms the good reception. There is no risk of multiple receptions in this case.



Both QoS1 and QoS2 allow persistent connections. A persistent connection allows the broker to keep a certain number of messages in memory (configured on the broker) until the client reconnects in case of connection loss. Persistent connections are not yet managed by OIBus.

The topic

The broker organizes the data by tree structure. Here is an example:

France
| -> Paris
      | -> temperatureTank1
      | -> temperatureTank2
| -> Chambery
      | -> temperatureTank1
      | -> temperatureTank2





It is then possible to subscribe to a dataset by entering a parent node, for example France / # or France / Chambery / #. It is also possible to directly enter the final data, for example France / Paris / temperatureTank1.

Notions of Points and Subscriptions

When an MQTT client subscribes to a data item on the broker, the broker sends the new values ​​as soon as they are available according to the connection options (in particular the QoS). The scan mode is therefore always listen. This is a subscription from the MQTT client waiting for the broker to send it new values.

The point id is the name of the data as referenced in the target application.

When subscribing to a set of points as with xxxx / #: the point id is configured under the form yyyy # which will give point id by concatenation of yyyy with the detail of the topic.

For example if we subscribe to a set of points like France / # and the point id is configured as France:# , then the list of point id obtained will be:

France:Paris/temperatureTank1
France:Paris/temperatureTank2
France:Chambery/temperatureTank1
France:Chambery/temperatureTank2




Mqtt payload

The payload contained in the messages sent by the broker may differ from broker to broker. The OIBus MQTT client can adapt to this payload through the MQTT payload configuration:

For example, if the payload is of the form:

{
"pointId": "point1",
"value": "666.666",
"timestamp": "2020-02-02 02:02:02",
"quality": "true"
}




Then the following configuration must be applied:

Data array path : Ø
Value path : value
Node id path : Ø
Timestamp path : timestamp
Quality path : quality




Another example, with a payload of the form:

"metrics": [
{
"customName": "point1",
"customValue": "666.666",
"customTimestamp": "2020-02-02 02:02:02",
"customQuality": "true"
}
]




Then the following configuration must be applied:

Data array path : metrics
Value path : customValue
Node id path : customName
Timestamp path : customTimestamp
Quality path : customQuality





To go further

You can consult the MQTT website of the standardization body Oasis Open and more particularly the document of MQTT specification.