Ingestion API

The N2N DL Sense APIs allow for ingestion of custom data generated by non LoRaWAN sensors. Any device that has access to internet connection can send data to N2N DL through the ingestion APIs

Device auto enrolment

Unknown devices will be automatically enrolled with the specified enterpriseId and deviceType if they don’t exist already.

If an ingestion requests is linked to a device that doesn’t exist and no enterpriseId or deviceType are specified, no automatic enrolment is possible and the request will fail.

Device Names

In order to preserve scalability and avoid name clashing the device Id of a cellular device should have the following form

<prefix>-<customDeviceId>

And should match the following regex /^[0-9a-f]{5}-[a-z0-9]{3,16}$/i.

Where

  • The prefix should be the first 5 characters of the md5(enterpriseId)
  • the customDeviceId is any custom but not repeated combination of numbers and letters only

All custom deviceIds are automatically lowercased to distingush them from the LoRaWAN DeviceEUIs (which are uppercased)

Example of a correct deviceId is:

  • enterpriseId: nnn.farmlands => 4a817-ks5047298
  • enterpriseId: nnn => a1931-aaBBcc123

If choosing the wrong format the ingestion API will fail suggesting the correct pattern to use.

Device Types

Device types allowed are camelCase minimum 4 characters [a-zA-Z]

Payloads

Payloads can have a variable number of channels from reading to reading.

Although it’s not advisable to change the channel association, each channel can change type across different payloads and no particular structure is enforced.

Channel types must be specified among the ones supported and each value need to be coherent with the type (a boolean type cannot have a value of 100 for example).

Multiple readings from multiple devices can be ingested at once up to a 100kb limit per single HTTP request.

API key TPS and TPD limitations do apply.

Data Ingestion

Timestamps are specified in milliseconds past Epoch (1/1/1970).

To preserve data quality and prevent mistakes, historical data can be ingested with a timestamp greater than 1262217600000 (=> 1st Jan 2010 00:00:00 AEST) only.

Data can be ingested out of order and will be automatically merged and deduped: sending the same single data value more than once will succeed and a Last-Write-Win policy will apply.

Data cannot be deleted once ingested at this stage but can be overwritten.

Authorisation

The same type of API key required to access any of the N2N DL APIs is needed to ingest the data and the same TPS and TPD limitations apply.

Atomicity

Every requests to ingest data either succeeds completely or fails.

No partial data ingestion can occur.

Getting Started

The Ingestion API is part of the Sense APIs and is reachable at https://www.nnnco.io/v3/api/core/devices/ingest-readings like in the following javascript example:

var request = require("request");

var options = { method: 'POST',
  url: 'https://www.nnnco.io/v3/api/core/devices/ingest-readings',
  headers: { 'Content-Type': 'application/json' },
  body: 
   [ { deviceId: 'a1931-aaBBcc123',
       enterpriseId: 'nnn',
       deviceType: 'waspMote',
       ts: 1557808479000,
       readingList: 
        [ { channelId: 0,
            type: 'reactive-power',
            value: 100,
            label: 'hello-World' } ] } ],
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

More information is available in the Ingestion APIs Swagger Link