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
Orion API 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.retain
: to specify the MQTT retain value to use in the notifications associated to the subscription (true
orfalse
). This is an optional field, if omitted then retainfalse
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 this section of the Orion API 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
,qs
andmethod
cannot be used, as they doesn’t have equivalence in MQTT- Macro replacement is performed in
topic
andpayload
fields.url
,qos
,retain
,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). Orion also closes
connection in case of MQTT notification errors (e.g. MQTT broker is down), so it will be re-created next
time a successfully MQTT notification gets published.
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'
To clear all mosquitto broker retained messages:
sudo service mosquitto stop
sudo rm /var/lib/mosquitto/mosquitto.db
sudo systemctl start mosquitto.service