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


the trailing s is optional

For example:


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:


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:


the trailing s is optional

For example:


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.



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


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


The MQTT connector endpoint is available at 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.

Connecting using Mosquitto

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

Mosquitto libriaries and tools are designed to run on embedded devices and TLS support requires the CA file(s) to be explicity provided as parameters.

The cafile required to support TLS encryption with N2N-DL can be downloaded at this address and can be used like in the following example:

mosquitto_sub -h -p 8443 -u anything -P "<your api key here>" -t n2n/v3/devices/+/uplink -v -q 1 -V mqttv311 -d --cafile /path/to/nnnco.pem