Through this API the device can send unstructured IoT information to be processed & collected by the platform.

JSON Objects

Table 1. Datapoint Collection object
Attribute Description

version

indicates the version of the structure

device (optional)

Device Identifier in case of be different that the device Identifier that sends information (included in the URI)

path (optional)

Identifier of the gateway or gateways that as been used by the asset for sending the information

trustedBoot (optional)++

In this case you are indicating that is required a validation type trusted_boot, it’s not necessary introduce the field value but if you introduce it all the message received by the platform will compare the trustedBoot value with the provisioned value if are diferent the message will not be collected

datastreams[]

Array of datastreams to be collected. See Datastream object definition

Table 2. Datastream object attributes
Attribute Description

id

Identifier of the datastream

feed (optional)

Feed Identifier

datapoints[]

Array of datapoints data to be collected. See Datapoint object definition

The feeds concept in the JSON object can be used to differentiate:

  • Collected information of a same sensor used by different sources (Example: People using a same eHealth glucometer sensor)

  • Collected information of the multiple sensors at he same type (example: temperature) placed in different locations and connected to the same device. (Example: temperatures of different places of a room)

If no multiples feeds are needed the name "default" of the feed must be used as feed to collect information from sensor

Table 3. Datapoint object attributes
Attribute Description

from (optional)

Number with the time in miliseconds from epoch of the start period of measurement. This indicates that value is the same within this time interval (from -→ at).

This field is necessary if you are using datastream period = pulse, if this field is not incorporated the default value is the same than the value of the field "at". If the value of the field from is greater than the value of the field at, the value of the field from will be changed by the value of the field at, and both of them will have the same value.

at (optional)

Number with the time in miliseconds from epoch of the measurement

If this field is missing, the platform will assign the server current time to the datapoint whe data is received.

It is necessary to observe that in the multiple Datapoints scenario, only a datapoint value can appear without "at" field. If not the platform will take the first datapoint (in JSON object) where the field is missing and drop the others in the same situation. See next valid examples:

  • Single DataPoint

"datapoints":[
    {"at":1431602523123,"value":41}
]
"datapoints":[
    {"value":333}
]
  • Multiple DataPoints

"datapoints":[
    {"at":1431602523123,"value":41},
    {"at":1431602623123,"value":84},
    {"at":1431607623123,"value":41},
    {"value":83}
]

value

This is a polyvalent field that can be any of the JSON supported data types:

"value" : 10
  • String delimited with double-quotation marks. Example:

"value" : "string value"
  • Boolean either of the values true or false. Example:

"value" : true
  • Array of JSON data types. Example:

"value" : [ "text1", "text2" ]
  • Object with JSON format. Example:

"value" : {
    "field1": "text",
    "field2": 12
}
  • Null. Example:

"value" : null

The format of the field is defined in the datastream template. See Templates description section

tags[] (optional)

Array of tags (in string format) to be associated to a datapoint

Collecting information

POST /south/v80/devices/{device.id}/collect/iot

This request allows the device to append or modify information to an existing datastream.

It can be done:

  • Writing datapoints with their respective timestamps in different datastreams in a only request

  • Writing datapoints without timestamp in different datastreams in a only request

The second request type is used when the device hasn’t internal clock. In this case the platform connector puts the associated timestam. It is mainly used to provide latest value of a signal in the sensor or the machine

Using curl to perform the request:

curl --request POST \
     --data-binary @datapoints.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/south/v80/devices/{device.id}/collect/iot \
     -H "Content-type: application/json"

In the response we should see a status code of 200 (created). Let’s look the response.

HTTP/1.1 201 Added

JSON Examples

Let’s see some examples:

Write Multiple Datapoints to Each Datastream (With timestamp)
{
  "version":"1.0.0",
  "datastreams" : [
    {
      "id" : "example",
      "feed" : "feed_1",
      "datapoints":[
        {"at":1431602523123,"value":41},
        {"at":1431602623123,"value":84},
        {"at":1431607623123,"value":41},
        {"at":1431608623123,"value":83}
      ]
    },
    {
      "id" : "key",
      "feed" : "feed_2",
      "datapoints":[
        {"at":1431602523123,"value":"revalue"},
        {"at":1431602623123,"value":"string value"},
        {"at":1431607623123,"value":"any string"},
        {"at":1431608623123,"value":"structured data"}
      ]
    },
    {
      "id" : "datastream",
      "datapoints":[
        {"at":1431602523123,"value":51, "tags":["tag_1","tag_2"]},
        {"at":1431602623123,"value":102, "tags":["tag_2","tag_3"]},
        {"at":1431607623123,"value":32},
        {"at":1431608623123,"value":16, "tags":["tag_3"]}
      ]
    }
  ]
}
Write Latest value with a single Datapoint to Each Datastream (Without timestamp)
{
  "version":"1.0.0",
  "datastreams" : [
    {
      "id" : "example",
      "feed" : "feed_1",
      "datapoints":[
        {"value":333}
      ]
    },
    {
      "id" : "key",
      "feed" : "feed_2",
      "datapoints":[
        {"value":"value"}
      ]
    },
    {
      "id" : "datastream",
      "datapoints":[
        {"value":1337}
      ]
    }
  ]
}
Write Latest value with a single datapoint to one Datastream sended by an asset with trusted boot
{
    "version": "1.0.0",
    "device": "asset1",
    "path": [
        "gateway1"
    ],
    "trustedBoot": "ñasdohfñasjkdfñ",
    "datastreams": [
        {
            "id": "example",
            "datapoints": [
                {
                    "at": 1490092712000,
                    "value": "1"
                }
            ]
        }
    ]
}

To find a list of specific datastream and examples of using it see Default Datamodels