Integration - MQTT
By default supernode provides MQTT broker service for users to subscribe or publish events on their devices.
Users can subscribe to MQTT broker under topics in the servers after authentication. Before that, you need to make sure you have mosquitto package installed. Use the package manager apt to install these dependencies on the Ubuntu 18.04 LTS server:
sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppasudo apt-get updatesudo apt install mosquitto mosquitto-clients
#
SubscriptionYou can either subscribe to the broker in your console or you can use package for Subscription inside your program.
A template of subscribing to the topic:
mosquitto_sub -h {{ .SUPERNODE_URL }} -p 8883 -t '{{ .EVENT_TOPIC_STRING }}' -v -u '{{ .USER_MQTT_AUTH_JWT }}' -P 'default' -i '`hostname`-$$' --capath /etc/ssl/certs
{{ .SUPERNODE_URL }}
#
How to get {{ .SUPERNODE_URL }}
is the URL of supernode where you registered your devices:
- matchx EU
lora.supernode.matchx.io
- matchx US
ussn.matchx.io
- hHuaweikeji
lora.hunanhuaweikeji.com
- mxcxy
mxcxy.com
- k-supernode
k-supernode.com
- enlink
lora.rosanetworks.com
- du-capital
supernode.iot-ducapital.net
{{ .APPLICATION_ID }}
and {{ .ORG_ID }}
#
How to get - Get JWT for supernode user account, in the following content, we call it
{{ .SUPERNODE_JWT }}
{{ .SUPERNODE_JWT }}
will be used for authenticate your further requests.
Call
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "password": "{{ .SUPERNODE_PASSWORD }}", "username": "{{ .SUPERNODE_USERNAME }}"}' 'https://{{ .SUPERNODE_URL }}/api/internal/login'
Response
{ "jwt": "{{ .SUPERNODE_JWT }}", "is2faRequired": false}
- Get organization list
{{ .ORG_ID }}
is important parameter for your further requests.
Call
curl -X GET --header 'Accept: application/json' --header 'Grpc-Metadata-Authorization: Bearer {{ .SUPERNODE_JWT }}' 'https://{{ .SUPERNODE_URL }}/api/organizations?limit=999&offset=0'
Response
{ "totalCount": "1", "result": [ { "id": "{{ .ORG_ID }}", "name": "Your Organization Name", "displayName": "Your Organization Display Name", "canHaveGateways": true, "createdAt": "2020-04-22T09:53:38.928940Z", "updatedAt": "2021-05-12T12:50:02.391191Z" } ]}
- Get application list with given
{{ .ORG_ID }}
Call
curl -X GET --header 'Accept: application/json' --header 'Grpc-Metadata-Authorization: Bearer {{ .SUPERNODE_JWT }}' 'https://{{ .SUPERNODE_URL }}/api/applications?limit=999&offset=0&organizationID={{ .ORG_ID }}'
Response
{ "totalCount": "1", "result": [ { "id": "{{ .APPLICATION_ID }}", "name": "Your application name", "description": "description", "organizationID": "{{ .ORG_ID }}", "serviceProfileID": "service profile id", "serviceProfileName": "service proile name" } ]}
{{ .USER_MQTT_AUTH_JWT }}
#
How to get Call
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Grpc-Metadata-Authorization: Bearer {{ .SUPERNODE_JWT }}' -d '{ "organizationId": "{{ .ORG_ID }}", "ttlInSeconds": "{{ .TIME_TO_LIVE_IN_SECONDS }}"}' 'https://{{ .SUPERNODE_URL }}/api/mosquitto-auth/login'
Response
{ "jwtMqttAuth": "{{ .USER_MQTT_AUTH_JWT }}"}
{{ .EVENT_TOPIC_STRING }}
#
How to get - Get
{{ .EVENT_TOPIC_STRING }}
for subscribing to all devices' events under same application
Call
curl -X GET --header 'Accept: application/json' --header 'Grpc-Metadata-Authorization: Bearer {{ .USER_MQTT_AUTH_JWT }}' 'https://{{ .SUPERNODE_URL }}/api/mosquitto-auth/subscribe-application-events?applicationId={{ .APPLICATION_ID }}&organizationId={{ .ORG_ID }}'
Response
{ "topic": "Topic for subscribing to application {{ .APPLICATION_ID }}: 'application/{{ .APPLICATION_ID }}/device/+/event/+'"}
- Get
{{ .EVENT_TOPIC_STRING }}
for subscribing to events with given {{ .DEV_EUI }} and {{ .ORG_ID }}
Call
curl -X GET --header 'Accept: application/json' --header 'Grpc-Metadata-Authorization: Bearer {{ .USER_MQTT_AUTH_JWT }}' 'https://{{ .SUPERNODE_URL }}/api/mosquitto-auth/subscribe-device-events?devEui={{ .DEV_EUI }}&organizationId={{ .ORG_ID }}'
Response
{ "topic": [ "Topic for subscribing to device {{ .DEV_EUI }} on event up: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/up'", "Topic for subscribing to device {{ .DEV_EUI }} on event join: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/join'", "Topic for subscribing to device {{ .DEV_EUI }} on event ack: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/ack'", "Topic for subscribing to device {{ .DEV_EUI }} on event error: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/error'", "Topic for subscribing to device {{ .DEV_EUI }} on event status: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/status'", "Topic for subscribing to device {{ .DEV_EUI }} on event location: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/location'", "Topic for subscribing to device {{ .DEV_EUI }} on event txack: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/txack'", "Topic for subscribing to device {{ .DEV_EUI }} on all events: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/event/+'" ]}
#
PublishingA template of publishing with mosquitto_pub looks as this:
mosquitto_pub -h {{ .SUPERNODE_URL }} -p 8883 -u '{{ .USER_MQTT_AUTH_JWT }}' -P 'default' -i '`hostname`-$$' -t '{{ .COMMAND_TOPIC_STRING }}' -m '{{ .MESSAGE }}' --capath /etc/ssl/certs
{{ .COMMAND_TOPIC_STRING }}
#
How to get Call
curl -X GET --header 'Accept: application/json' --header 'Grpc-Metadata-Authorization: Bearer {{ .USER_MQTT_AUTH_JWT }}' 'https://{{ .SUPERNODE_URL }}/api/mosquitto-auth/send-command?devEui={{ .DEV_EUI }}&organizationId={{ .ORG_ID }}'
Response
{ "topic": "Topic for publishing to device {{ .DEV_EUI }}: 'application/{{ .APPLICATION_ID }}/device/{{ .DEV_EUI }}/command/down'"}
{{ .MESSAGE }}
#
How to get The message format should be as follow:
{ "confirmed": true, "fPort": 10, "data": "....", "object": { "temperatureSensor": { "1": 25 }, "humiditySensor": { "1": 32 } }}
confirmed
: whether the payload must be sent as confirmed data down or notfPort
: FPort to use (must be > 0)data
: base64 encoded data (plaintext, will be encrypted by Network Server)object
: decoded object (when application codec has been configured), when providing the 'object', you can omit ' data'