Getting Started
Getting access
In order to get programmatic access to the data from the devices an API key is needed.
Alternatively user credentials to our admin interface can be used.
API keys and user credentials can be obtained from NNNCo by getting in touch with one of our sales rep or emailing n2n-dl-support@nnnco.com.au.
In the following examples we assume that the following test API key: 8a0892e3aedbe2f2ade4bd727d4725e0c639d021 - which is no longer valid - is linked to an enterprise called nnn.client1.
More information on authentication is available in the API structure page
N2N DL in a nutshell
In N2N DL devices are enrolled and owned by enterprises (aka clients) and send raw data and network metadata to our platform (LoRaWAN only).
Our platform parses the data (optionally) to generate readings with a normalised data model and (optionally) stores the raw data and the readings (if any).
Clients can create data subscriptions to receive raw data, readings and network metadata in their application.
Enrol a new LoRaWAN device
Let’s start by enrolling a OTAA device:
curl -X POST \
https://www.nnnco.io/v3/api/core/devices \
-u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021 \
-H 'Content-Type: application/json' \
-d '{
"deviceId": "477b41f200300034",
"enterpriseId": "nnn.client1",
"name": "test-device-otaa",
"enrolment": {
"class": "A",
"mode": "otaa",
"otaa": {
"appEui": "0000000000000000",
"appKey": "2b7e151628aed2a6abf7158809cf4f3c"
}
}
}'which should return something like
{
"deviceId": "477B41F200300034",
"enterpriseId": "nnn.client1",
"name": "test-device-otaa",
"groupIdList": [
"nnn.client1.master"
]
}ABP devices can be enrolled in a similar way:
curl -X POST \
https://www.nnnco.io/v3/api/core/devices \
-u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021 \
-H 'Content-Type: application/json' \
-d '{
"deviceId": "A81758FFFE0311EF",
"enterpriseId": "nnn.canegrowers",
"name": "test-abp-device",
"enrolment": {
"class": "A",
"mode": "abp",
"abp": {
"nwAddress": "FE0311EF",
"nwKey": "00000000000000000000000000000000",
"appSKey": "00000000000000000000000000000000"
}
}
}'If we specify no AppSKey the payload from ABP devices remains encrypted and needs decryption at an application level.
Otherwise the decryption is carried out by our network server (as mandated by LoRaWAN specifications)
Payload decoding
N2N DL supports multiple device payloads for automatic parsing into readings.
If a device has no device type associated OR a device type for which N2N DL has no parser, no parsing is attempted.
The full list of devices currently supported is available here TODO.
Get a list of devices that belong to your account
Let’s not get a list of devices associated to our account
curl -X GET \
'https://www.nnnco.io/v3/api/core/devices' \
-u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021Here we get 2 devices: 0018B20000002594 for which no device type is specified and 393435376A377906 which is a parametric pcr2 device.
As a consequence device 393435376A377906 also shows the latest values from the parsed readings from the device under channelList.
Instead for device 0018B20000002594 no channelList is present.
[
{
"enterpriseId": "nnn",
"lastOnline": 1580451305156,
"location": {
"latitude": 33.863,
"longitude": 151.208833,
"type": "gps"
},
"deviceId": "0018B20000002594",
"network": {
"type": "loraWan",
"source": "actility",
"loraWan": {
"lrrTs": 1580451305156,
"loraPort": 1,
"uplinkCnt": 174,
"adrBit": null,
"mType": 4,
"downlinkCnt": 1318,
"lrcId": "00000231",
"rssi": -62,
"snr": 13.5,
"spFact": 10,
"subBand": "G0",
"lrrCnt": 2,
"lrrId": "004A1C4A",
"late": false,
"lrrLat": -33.862549,
"lrrLong": 151.209793,
"lrrList": [
{
"lrrId": "004A1C4A",
"chain": 0,
"rssi": -62,
"snr": 13.5,
"esp": -62.189785
},
{
"lrrId": "004A1C22",
"chain": 0,
"rssi": -118,
"snr": -0.75,
"esp": -121.401474
}
]
}
},
"groupIdList": [
"nnn.master"
]
},
{
"lastOnline": 1581487940278,
"deviceType": "parametricPcr2",
"enterpriseId": "nnn",
"network": {
"type": "loraWan",
"source": "actility",
"loraWan": {
"lrrTs": 1581487940278,
"loraPort": 14,
"uplinkCnt": 12133,
"adrBit": 1,
"mType": 4,
"downlinkCnt": 12518,
"lrcId": "00000231",
"rssi": -84,
"snr": 6.75,
"spFact": 7,
"subBand": "G0",
"lrrCnt": 1,
"lrrId": "004A1C4A",
"late": false,
"lrrLat": -33.862549,
"lrrLong": 151.209793,
"lrrList": [
{
"lrrId": "004A1C4A",
"chain": 0,
"rssi": -84,
"snr": 6.75,
"esp": -84.832695
}
]
}
},
"deviceId": "393435376A377906",
"channelList": [
{
"channelId": 0,
"type": "digital",
"value": 0,
"label": "count-left-to-right"
},
{
"channelId": 1,
"type": "digital",
"value": 1,
"label": "count-right-to-left"
},
{
"channelId": 2,
"type": "temperature",
"value": 31,
"unit": "°C"
}
],
"groupIdList": [
"nnn.master"
]
}
]Retrieve some data from a device
Retrieving data from a device is as easy as calling:
curl -X GET \
'https://www.nnnco.io/v3/api/core/devices/393435376A377906/messages' \
-u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021[
{
"hexPayload": "0a000016000001013a",
"type": "uplink",
"deviceId": "393435376A377906",
"port": 14,
"ts": 1581488300304,
"network": {
"type": "loraWan",
"source": "actility",
"loraWan": {
"lrrTs": 1581488300304,
"loraPort": 14,
"uplinkCnt": 12135,
"adrBit": 1,
"mType": 4,
"downlinkCnt": 12520,
"lrcId": "00000231",
"rssi": -89,
"snr": 5.75,
"spFact": 7,
"subBand": "G0",
"lrrCnt": 1,
"lrrId": "004A1C4A",
"late": false,
"lrrLat": -33.862549,
"lrrLong": 151.209793,
"lrrList": [
{
"lrrId": "004A1C4A",
"chain": 0,
"rssi": -89,
"snr": 5.75,
"esp": -90.02459
}
]
}
},
"readingList": [
{
"channelId": 0,
"type": "digital",
"value": 0,
"label": "count-left-to-right"
},
{
"channelId": 1,
"type": "digital",
"value": 0,
"label": "count-right-to-left"
},
{
"channelId": 2,
"type": "temperature",
"value": 31.4,
"unit": "°C"
}
]
}
]The payload includes parsed data, raw data and network metadata.
Accessing only parsed readings
If we are interested in parsed readings only (and no raw data or network metadata) we can call instead:
curl -X GET \
'https://www.nnnco.io/v3/api/core/devices/393435376A377906/readings' \
-u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021[
{
"ts": 1581396315287,
"values": [
{
"channelId": 0,
"type": "digital",
"value": 2,
"label": "count-left-to-right"
},
{
"channelId": 1,
"type": "digital",
"value": 0,
"label": "count-right-to-left"
},
{
"channelId": 2,
"type": "temperature",
"value": 30.4,
"unit": "°C"
}
]
},
{
"ts": 1581396495290,
"values": [
{
"channelId": 0,
"type": "digital",
"value": 0,
"label": "count-left-to-right"
},
{
"channelId": 1,
"type": "digital",
"value": 0,
"label": "count-right-to-left"
},
{
"channelId": 2,
"type": "temperature",
"value": 30.7,
"unit": "°C"
}
]
}
]Create a data 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
}
]