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@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