MQTT Connector

N2N DL supports a MQTT connection option to send and receive messages from LoRaWAN devices using a permanent MQTT Connection

For getting data in MQTT topics one needs to:

Create an MQTT subscription for one’s enterprise or group of devices
Create, download and configure their MQTT client to use X509 client certificate for authentication

Managing MQTT Subscriptions

N2N DL stops sending data to MQTT by default. If you need to get uplinks and downlinks for your enterprise or group of devices you need to create an MQTT subscription.

As with all the other subscriptions, you can create a subscription following these steps:

Navigate to subscriptions page;
Click + button to open a dialog where you can set your new subscription;
Select your enterprise or sub-enterprise;
Choose mqtt for subscription type;
Fill other filters, like device type or subgroups if needed;
Click create subscription button.

Access

Authentication

N2N DL supports X509 client certificates for authentication. X509 MQTT client certificates are attached to API keys and inherit the permissions of the API Key.

In order to create and download the X509 certificate please follow these steps:

Navigate to access page;
Create an API key if needed (for example, you do not have any yet) by clicking + button;
Alternatively, you can use the existing API key if it has needed permissions;
Click MQTT button on the API key row to manage X509 certificates for the API key:
Click create MQTT certificate button to create an X509 certificate:
Download certificate, private key and CA;
You can also copy the example MQTT Mosquitto command line to try to connect to MQTT topic with your certificate:
Click back to list of MQTT certificates button.

IMPORTANT: You can download certificate and its private key only once on this page for a newly created certificate. If you lost the certificate, you will need to create a new one. You cannot restore the lost certificate. N2N DL does not see or store your certificates.

IMPORTANT: You need to keep your client certificate and its private key in a protected environment to avoid compromising your access to MQTT. If you think that X509 certificate has been compromised, you can deactivate and then delete it and create a new certificate.

Authorisation

Authorisation to MQTT topics is based on the API key permissions associated with the MQTT certificate and enterprise/group part of MQTT topic. If these do not match the access is rejected.

If a client attempts to subscribe to uplinks for an enterprise or a group of devices it does not have read access to, the connection is terminated;
If a client attempts to send a downlink to a device in an enterprise or a group it does not have write access to, the connection is terminated.

Endpoint

The MQTT connector endpoint is available at mqtt.nnnco.io on port 8883 with TLS enabled.

Handling MQTT Data

Receiving uplinks

A client can receive uplinks by subscribing to MQTT topics of some pre-defined names as described below. Your API Key must have access to enterprise or group of devices you are subscribing to.

Topic	Description
`n2n/groups/:absoluteEnterpriseGroupId/:deviceId/uplinks`	Subscribe to an individual device
`n2n/groups/:absoluteEnterpriseGroupId/+/uplinks`	Subscribe to devices that belong to an enterprise or in a group

The :absoluteEnterpriseGroupId has the following formats:

`:absoluteEnterpriseGroupId`	Description
`nnn.:enterpriseId.master`	if you want to subscribe to all the devices belonging to the enterprise. This subscription does not include the sub-enterprise devices
`nnn.:enterpriseId.subEnterpriseId.master`	if you want to subscribe to the devices belonging to the sub-enterprise
`nnn.:enterpriseId.:groupId`	if you want to subscribe to the devices in a particular group

Example of the uplink topic names:

n2n/groups/nnn.your-enterprise.master/+/uplinks
n2n/groups/nnn.your-enterprise.sub-enterprise.master/+/uplinks
n2n/groups/nnn.your-enterprise.sub-enterprise-level-1.sub-enterprise-level-2.master/+/uplinks
n2n/groups/nnn.your-enterprise.sub-enterprise-level-1.sub-enterprise-level-2.temperature-sensors-group/+/uplinks
n2n/groups/nnn.your-enterprise.test-devices/+/uplinks

You are able to subscribe to several topics simultaneously to combine your subscriptions to form the scope your application needs.

Uplinks are received as JSON encoded text messages with the following format:

{
	"deviceId": "00000000000000FE",
	"hexPayload": "c300014fdb022a",
	"deviceType": "anything-here",
	"network": {
		"type": "loraWan",
		"source": "actility",
		"loraWan": {
			"lrrTs": 1567752577392,
			"loraPort": 2,
			"uplinkCnt": 4009,
			"adrBit": 1,
			"mType": 2,
			"downlinkCnt": 110,
			"lrcId": "00000231",
			"rssi": -50,
			"snr": 9.25,
			"spFact": 7,
			"subBand": "G0",
			"lrrCnt": 1,
			"lrrId": "9C3A65DB",
			"late": false,
			"lrrList": [{
				"lrrId": "9C3A65DB",
				"chain": 0,
				"rssi": -50,
				"snr": 9.25,
				"esp": -50.48772
			}]
		}
	},
	"ts": 1567752579039
}

As for messages an optional readingList field can be present if the raw payload was decoded by N2N DL.

Sending Downlinks

Downlink payloads can be sent to a device by publishing a well-formed message on a topic with the following format.

n2n/groups/:absoluteEnterpriseGroupId/:deviceId/downlinks

For example:

n2n/groups/nnn.your-enterprise.master/00000000000000FE/downlinks

An example of well-formed downlink request can be seen below:

{
    "correlationId": "someRandomString",
	"hexPayload": "aabbcc",
	"loraPort": 101,
	"downlinkCounter": 123,
	"flushQueue": true,
	"validityTime": 20
}

The meaning of the fields is as follows

correlationId - required: NEW field that allows you to match the downlink delivery status with the downlink
hexPayload - required: the payload to send to the device
loraPort - required: the lora port to use
downlinkCounter - optional: the downlink counter to use for this request
flushQueue - optional: set to true to empty the downlink queue before enqueuing this request
validityTime - optional: validity time in minutes (min: 1 max: 65k) for the downlink to stay pending (Class A devices only)

The MQTT broker will accept well-formed downlinks in JSON format. New implementation of MQTT let your see downlink delivery status.

Downlink delivery status

If you want to know whether your downlink that has been sent via MQTT is processed or not and get some diagnostics, you can subscribe to the topic:

n2n/groups/:absoluteEnterpriseGroupId/downlinks/statuses

It is important that :absoluteEnterpriseGroupId in the topic name above is the same as in the MQTT topic which you use to publish downlinks.

An example of delivery status message - delivery of the downlink has been successful:

{
    "correlationId": "test123456789",
    "deviceId": "8CF9574000002CD2",
    "networkPart": "N2N DL",
    "isSuccessful": true
}

When there is an error delivery status message will be like this:

{
    "correlationId": "test123456789",
    "deviceId": "8CF9574000002CC2",
    "networkPart": "NETWORK_SERVER",
    "isSuccessful": false,
    "errorCode": "FAILED_DELIVER_TO_NETWORK_SERVER",
    "errorMessage": "failed to send downlink to device 8CF9574000002CC2 due to error: Network Server Error: No Base Station Available"
}

The list of possible values for errorCode:

DEVICE_NOT_FOUND
ACCESS_DENIED
FAILED_DELIVER_TO_NETWORK_SERVER
SYSTEM_DELIVERY_ERROR

Join Request and Join Accept MAC uplinks/downlinks

N2N DL now supports delivery of LoRaWAN JoinRequests/JoinAccepts uplinks/downlinks. They are delivered in the same MQTT topics as the normal data uplinks and downlinks.

To receive both JoinRequests and JoinResponses you need to subscribe to two MQTT topics: n2n/groups/.../uplinks and n2n/groups/.../downlinks

JoinRequest example (in MQTT uplinks topic):

{
    "subId": 408,
    "deviceName": "DEVICE_NAME",
    "deviceId": "FFF3D57BA0000B9C",
    "joinRequestPayload": "00b20600d07ed5b3709c0b00a07bd5b3702b2a61a40457",
    "joinRequest": {
        "joinEUI": "fff3d57ed00006b2",
        "devEUI": "fff3d57ba0000b9c",
        "devNonce": "2a2b"
    },
    "micHex": "61a40457",
    "ts": 1654774475993,
    "type": "uplink",
    "network": {
        "type": "loraWan",
        "source": "actility",
        "loraWan": {
            "lrrTs": 1654774475993,
            "uplinkCnt": 165400,
            "mType": 0,
            "mTypeDecoded": "JoinRequest",
            "lrcId": "00000231",
            "rssi": -99,
            "snr": 6,
            "spFact": 10,
            "subBand": "G0",
            "lrrId": "00002E14",
            "lrrCnt": 3,
            "lrrList": [
                {
                    "lrrId": "00002E14",
                    "chain": 0,
                    "rssi": -99,
                    "snr": 6,
                    "esp": -99.973228
                },
                {
                    "lrrId": "00002E0F",
                    "chain": 0,
                    "rssi": -119,
                    "snr": -11,
                    "esp": -130.331955
                },
                {
                    "lrrId": "DA005866",
                    "chain": 0,
                    "rssi": -120,
                    "snr": -12,
                    "esp": -132.265717
                }
            ]
        }
    }
}

JoinResponse example (in MQTT downlinks topic):

{
    "subId": 408,
    "deviceName": "DEVICE_NAME",
    "deviceId": "FFF3D57BA0000B9C",
    "joinResponsePayload": "203158cecc711ebdc70e00ed6249f201119fd7e6d9486849a497d71807d85b207a",
    "ts": 1654774429424,
    "type": "downlink",
    "network": {
        "type": "loraWan",
        "source": "actility",
        "loraWan": {
            "lrrTs": 1654774429424,
            "mType": 1,
            "mTypeDecoded": "JoinAccept",
            "downlinkCnt": 29760,
            "lrcId": "00000231",
            "spFact": 10,
            "subBand": "G0",
            "lrrId": "00002E14",
            "lrrList": []
        }
    }
}

Connecting using Mosquitto

If you intend to connect to the N2N DL MQTT connector using mosquitto, TLS encryption must be enabled.

X509 client certificates is the only authentication method available in N2N DL

mosquitto_sub -h mqtt.nnnco.io -p 8883 --key fc2c2d164e1c4c6bd11918a07176a5261cbbf8dae3120316c0a4a0a0476aebec-private-key.pem --cert fc2c2d164e1c4c6bd11918a07176a5261cbbf8dae3120316c0a4a0a0476aebec-cert.pem --cafile nnn-iot-ca.pem -t n2n/groups/nnn.master/+/+ -d -i client-fc2c2d164e1c4c6bd11918a07176a5261cbbf8dae3120316c0a4a0a0476aebec