Data Subscriptions

N2N-DL supports transparent PUSH of messages from each device through data subscriptions.

Multiple data subscription options are available as well as a MQTT Connector/Broker.

N2N DL Integration Options

Data subscriptions

Every new incoming reading matching an existing subscription is put on a queue for delivery.

The queue is then flushed every 10 to 3600 seconds (approx) to the specified endpoint.

Failed deliveries are continuously retried until the delivery succeeds or the queue is automatically rotated.

Currently the delivery queue has a fixed maximum length of 50k items and is autorotating i.e. older non-delivered elements are deleted first.

Filter types

Currently the following subscription filters are available:

Filter by Optional Notes
enterpriseId NO
groupIds YES multiple groupIds can be specified per subscription
deviceType YES 1 device type per subscription

Low Level platform support

The following endpoints are currently supported:

Type Supporty Type
HTTP/S Full. Custom headers supported.
Amazon IoT Core MQTT subscription for uplinks only.
Amazon SNS Full. IAM role needed.
Amazon Kinesis Full. IAM role needed.
MQTT See the MQTT documentation
Kafka endpoint Scheduled Q4 2021

Formats

Currently the N2N-DL Push APIs supports the JSON format only.

An example of the JSON format is available below:

[{
	"subId": 11,
	"deviceName": "test-device",
	"deviceMeta": {
		"key": "value"
	},
	"deviceId": "0000000001E014E7",
	"deviceType": "risingHf",
	"hexPayload": "0144482b0f007a1bab",
	"readingList": [{
		"channelId": 0,
		"type": "digital",
		"value": 1,
		"label": "status"
	}, {
		"channelId": 1,
		"type": "temperature",
		"value": 2.75,
		"unit": "°C"
	}, {
		"channelId": 2,
		"type": "humidity",
		"value": 15,
		"unit": "%"
	}, {
		"channelId": 3,
		"type": "time",
		"value": 30,
		"unit": "s"
	}, {
		"channelId": 4,
		"type": "lora-rssi",
		"value": -58
	}, {
		"channelId": 5,
		"type": "lora-snr",
		"value": 6.75
	}, {
		"channelId": 6,
		"type": "voltage",
		"value": 3.21,
		"unit": "V",
		"label": "battery"
	}],
	"port": 8,
	"ts": 1594271461671,
	"type": "uplink",
	"network": {
		"type": "loraWan",
		"source": "actility",
		"loraWan": {
			"lrrTs": 1594271461671,
			"loraPort": 8,
			"uplinkCnt": 520675,
			"adrBit": 1,
			"mType": 2,
			"downlinkCnt": 16796,
			"lrcId": "00000231",
			"rssi": -64,
			"snr": 10.25,
			"spFact": 7,
			"subBand": "G0",
			"lrrCnt": 1,
			"lrrId": "C00019C5",
			"late": false,
			"lrrLat": -33.674412,
			"lrrLong": 151.08992,
			"lrrList": [{
				"lrrId": "C00019C5",
				"chain": 0,
				"rssi": -64,
				"snr": 10.25,
				"esp": -64.391785
			}]
		}
	}
}]

High level platform support

The following high level IoT platforms are directly supported

Type Supporty Type
Ubidots Requires Ubidots token

Creating a subscription

Simple HTTP/s

curl -X POST \
  https://www.nnnco.io/v3/api/core/subscriptions \
  -H 'Content-Type: application/json' \
  -u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021 \
  -d '{
	"enterpriseId": "nnn",
	"type": "http",
	"endpoint": {
		"url": "https://hookb.in/yDd0ewyzp9tO7OPzdQVe"
	},
	"pushInterval": 10
}'

{
    "enterpriseId": "nnn",
    "type": "http",
    "endpoint": {
        "url": "https://hookb.in/yDd0ewyzp9tO7OPzdQVe"
    },
    "pushInterval": 10,
    "format": "json",
    "subscriptionId": 42,
    "deliveries": 0,
    "pending": 0
}

Debugging a data subscription

We can inspect the items that are currently pending on the delivery queue by calling

curl -X GET \
  https://www.nnnco.io/v3/api/core/subscriptions/42/pending \
  -u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021 \
  -H 'Content-Type: application/json'

[
    {
        "subId": 42,
        "deviceId": "70B3D5A9F0019902",
        "deviceType": "aradGladiator",
        "hexPayload": "9aa86416d6080000000807",
        "readingList": [
            {
                "channelId": 0,
                "type": "digital",
                "value": 226.2,
                "label": "meter-reading",
                "unit": "m3"
            }
        ],
        "port": 1,
        "ts": 1581556484889,
        "type": "downlink",
        "network": {
            "type": "loraWan",
            "source": "actility",
            "loraWan": {
                "lrrTs": 1581556484889,
                "loraPort": 1,
                "uplinkCnt": 415,
                "adrBit": 1,
                "mType": 4,
                "downlinkCnt": 415,
                "lrcId": "00000231",
                "rssi": -90,
                "snr": 9,
                "spFact": 7,
                "subBand": "G0",
                "lrrCnt": 1,
                "lrrId": "C00019BC",
                "late": false,
                "lrrLat": -33.742016,
                "lrrLong": 150.62085,
                "lrrList": [
                    {
                        "lrrId": "C00019BC",
                        "chain": 0,
                        "rssi": -90,
                        "snr": 9,
                        "esp": -90.514969
                    }
                ]
            }
        }
    }
]

as well as the latest deliveries:

curl -X GET \
  'https://www.nnnco.io/v3/api/core/subscriptions/42/deliveries' \
  -u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021 \
  -H 'Content-Type: application/json'

[
    {
        "enterpriseId": "nnn",
        "subscriptionId": 42,
        "response": {
            "data": "{\"success\":false,\"message\":\"404 Not Found\"}",
            "headers": {
                "server": "nginx",
                "date": "Thu, 13 Feb 2020 01:31:06 GMT",
                "content-type": "application/json; charset=utf-8",
                "content-length": "43",
                "connection": "close",
                "cache-control": "no-cache, no-store, must-revalidate",
                "pragma": "no-cache",
                "expires": "Fri, 31 Dec 1998 12:00:00 GMT",
                "x-ratelimit-limit": "300",
                "x-ratelimit-reset": "5",
                "x-ratelimit-remaining": "234",
                "etag": "W/\"2b-TsMtXpt9QO/RWSxmyL7EEhm+8t4\""
            },
            "status": 404,
            "statusText": "Not Found"
        },
        "startedTs": 1581557465344,
        "deliveryId": "42-1581557465",
        "payload": {
            "byteSize": 22623,
            "numItems": 40,
            "format": "json"
        },
        "result": "ERROR",
        "errorMessage": "Http call failed 404 / {\"success\":false,\"message\":\"404 Not Found\"}",
        "completedTs": 1581557466530
    }
]

Swagger

More information is available in the Push APIs Swagger Link