MQTT Connector

N2N-DL V3 offers a MQTT downstream connection option to send and receive messages from LoRaWAN devices using a permanent MQTT Connection

N2N-DL acts as a message broker

  1. publishing messages when uplinks are received and processed
  2. Receiving downlink requests a message published by any of the client

Handling Data

A client can receive uplinks by subscribing to a topic in the format

n2n/v3/devices/:deviceId/uplink(s)

the trailing s is optional

For example:

n2n/v3/devices/00000000000000FE/uplink

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.

Alternatively wildcard subscriptions are also supported:

n2n/v3/devices/+/uplink(s)

the trailing s is optional

When a wildcard subscription is created:

  1. the client will receive all uplinks related to devices it has access to.
  2. the exact list of devices is variable as new devices are put online and assigned to specific groups the current API key has access to or viceversa old ones are removed

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

n2n/v3/devices/:deviceId/downlink(s)

the trailing s is optional

For example:

n2n/v3/devices/00000000000000FE/downlink

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

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

The meaning of the fields is as follows

  • 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 and silently discard malformed ones.

Access

Authentication

We currently support authentication using any username and any valid N2N-DL API Key as the password.

Authorisation

Authorisation is enforced using the MQTT authorisePublish and authoriseSubscribe schemas.

  • If a client attempts to subscribe to uplinks for devices it doesn’t have read access to, the connection is terminated
  • If a client attempts to send a downlink to a device it doesn’t have write access to, the connection is terminated

Endpoint

The MQTT connector endpoint is available at www.nnnco.io on port 8443 with TLS enabled.

The TLS certificate is generated using Letsnecrypt so the Letsencrypt CAA must be trusted by your http client to work.

Protocol and limitations

The N2N-DL MQTT connector:

  • implements MQTT protocol v3.1.1
  • supports QOS 0, 1, 2
  • supports data storage across reconnections using in memory / best effort approach only

Error Handling

MQTT v3.1.1 implements a publish/subscribe paradigm with no explicit error handling so real error handling is currently implemented.

In case of failed authorise-subscribe or authorise-publish calls the connection is immediately terminated.