
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
. The1883
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
andPassword
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.