Introduction
Apart from HTTP notifications, Orion is able to notify using MQTT. In this case, a MQTT message is published in a given MQTT broker specified at subscription time each time a notification is triggered.
From an operational point of view, MQTT subscriptions are like HTTP ones,
as described in this section of the documentation and in the
NGSIv2 specification (e.g. the notification
payload is the same, you can set an expiration date, a filtering expression, etc.) but they use mqtt
instead of http
in the notification
object.
...
"notification": {
"mqtt": {
"url": "mqtt://<mqtt_host>:1883",
"topic": "sub1"
}
}
...
The following elements can be used within mqtt
:
url
to specify the MQTT broker endpoint to use. URL must start withmqtt://
and never contains a path (i.e. it only includes host and port)topic
to specify the MQTT topic to useqos
: to specify the MQTT QoS value to use in the notifications associated to the subscription (0, 1 or 2). This is an optional field, if omitted then QoS 0 is used.user
andpasswd
: optional fields, to be used in the case MQTT broker needs user/password based authentication. If used, both fields have to be used together. Note that for security reasons, the password is always offuscated when retrieving subscription information (e.g.GET /v2/subscriptions
).
Another difference between MQTT and HTTP subscriptions in that the former don't include the following fields:
lastSuccessCode
. There is no equivalence to HTTP response codes in MQTT caselastFailureReason
. The only failure reason that Orion is able to detect is connection fail to the corresponding MQTT broker. Thus, there is no need of providing extra detail.
However, note that lastSuccess
and lastFailure
fields (which specify the timestamp of the last
success/failure) are supported in MQTT subscriptions in the same way than in HTTP subscriptions.
Custom notifications
Custom notifications (described in the NGSIv2 specification) in MQTT subscriptions work the same as in HTTP subscriptions, taking into account the following:
mqttCustom
is used instead ofhttpCustom
- The same fields used in
mqtt
can be used inmqttCustom
. headers
andqs
cannot be used, as they doesn’t have equivalence in MQTT- Macro replacement is performed in
topic
andpayload
fields.url
,qos
,user
andpasswd
are fixed values
Connection management
The endpoint of the MQTT broker associated to a subscription is specified in the url
field at subscription time,
but the connection to it is done first time a MQTT notification is published.
Once established, connection is kept opened while it is being used, i.e. MQTT notifications are published. If
a connections is not used (i.e. no MQTT is published) Orion will close it after a predefined keepalive time
(specified with the -mqttMaxAge
CLI parameter, one hour by default).
MQTT cheatsheet
The following commands can be useful to test and debug MQTT notifications (using mosquitto_sub and mosquito_pub).
To subscribe with QoS 2:
mosquitto_sub --disable-clean-session --id 1 -q 2 -d -h <host> -p 1883 -t '#'
To create a shared subscription (cluster name “g1”)
mosquitto_sub -h <host> -p 1883 -t '$share/g1/#'
To publish using TLS (not yet supported by Orion, pending on this issue):
mosquitto_pub -d --insecure --cafile file.pem -h <host> -p 1883 -u <username> -P <password> -t '/topic' -m 'payload'