Querying the data

Data format

N2N DL stores data in messages which have roughly 3 components

raw payload (for LoRaWAN devices)
parsed readings (if parsing is enabled)
network metadata

Querying the data

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 parsed readings only

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"
            }
        ]
    }
]

CSV export format

The same readings can be exported in CSV format using the following approach:

curl -X GET \
  'https://www.nnnco.io/v3/api/core/devices/393435376A377906/readings/export' \
  -u api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021

time,gps-0 latitude,gps-0 longitude,in-trip boolean,fix-failed boolean,man-down boolean,ch-4 heading(°),ch-5 speed(km/h),battery voltage(mV)
2020-03-03T23:56:53.466Z,-33.8627853,151.2094712,0,1,1,225,0,3950
2020-03-04T23:57:47.844Z,-33.8627853,151.2094712,0,1,1,225,0,3950

This API call returns the data from the last 2 days from a single device - where decoding is possible and enabled.

This approach is useful for simple integrations where this API is called hourly to get any new data (POLLING).

The API key can also be embedded in the URL as in the following example:

curl -X GET \
  'https://api:8a0892e3aedbe2f2ade4bd727d4725e0c639d021@https://www.nnnco.io/v3/api/core/devices/393435376A377906/readings/export'

This is particularly useful for platforms like Eagle.io that require a per device import URL.

Parsed readings format

Parsed readings are available in a normalised data model described below

Channels

Each device sends readings in channels where each physical sensor is connected to a fixed channel id.

Each reading has the following fields:

Field	Type	Notes	Example
`channelId`	number	the channel identifier (zero based)	`0`
`value`	number or object	the reading value	`23.5`
`type`	string	see supported type values below	`temperature`
`label`	string	an optional reading label (i.e. `battery-voltage`)	`internal`
`unit`	string	an optional unit of measurement in the SI standard	`°C`

Possible reading types are available in the following table:

Channel Type	notes
`analog`	used for float/double/fixed precision readings from custom use channels only
`digital`	used for integer readings from custom use channels only
`boolean`	`1` = true or `0` = false
`light`
`distance`
`voltage`
`humidity`
`temperature`
`sound`
`pitch`
`roll`
`yaw`
`inclination`
`azimuth`
`radius`
`heading`
`flow`
`gps`	values in the form {lat, long, alt}
`pressure`
`concentration`
`current`
`speed`
`frequency`
`percentage`
`altitude`
`weight`
`acidity`	as in pH levels
`power`
`reactive-power`
`energy`
`reactive-energy`
`loraRssi`	LoRaWAN specific - RSSI of the device
`loraSnr`	LoRaWAN specific - SNR of the device
`time`
`acceleration`
`precipitation`

Parsing device support

N2N DL can currently support parsing the following device payloads:

Device	Support type
NSEN	Uplink and time sync
CyplexTocCp1	Uplink and time sync
Dingtek Bin Sensor	Uplink
TBS220 Parking Sensor	Uplink
DM Oyster	Uplink
DM Yabby	Uplink
DM Guppy	Uplink
DM SensorNode/Sensordata	Uplink
Sensoterra Moisture Sensor	Uplink
RisingHF Sensor	Uplink
Polysense	Uplink
Elsys Desk Sensor	Uplink
Polysense	Uplink
Sanmina Food Sensor	Uplink
Netvox R718f/R311a/R311cc/R730f	Uplink
GlobalSat LT 100	Uplink
GlobalSat LW 3610 HR	Uplink
Ellenex Pld2-l	Uplink
Ellenex Pts2-l	Uplink
Arad Gladiator	Uplink
Decentlab Range Finder	Uplink
Goanna GoRainV1	Uplink
Adeunis Field Test	Uplink
FarmoKangaCreek	Uplink
FarmoRainD	Uplink
FarmoWaterDepth604	Uplink
FarmoWaterDepth604es	Uplink
FarmoFuelDepthDiesel	Uplink
DraginoLht65	Uplink
ParametricPcr2	Uplink
IctLevelSensor	Uplink
IctWeatherStation	Uplink
IctSoilMoisture	Uplink

Channel Mappings

Each channel has represents a different reading depending on the device. We call these channel mappings.

The response format from the API is self explicatory.

API Documentation

Open API Swagger documentation is provided here