Skip to main content

Data Exchange

Apio IoT allows to write and read dynamic data originated by field devices and/or other applications in the form of:

  • Time Series: variable changing over time, like measurements from a sensor
  • Events: data payloads associated with a type and a timestamp, used to describe a real-world event, such as a machine restart.

In both cases, you can either use the HTTP API or the MQTT API, the rule of thumb is to prefer MQTT for continuous streams of data and events, while using the HTTP data for sending non continuous data points and to read data.

Data Points​

A data point represent a value measured in time with optional metadata, for example:

{
    "projectId": "1c571c95-dd6a-4e7c-8876-9a050bf22a86",
    "deviceId": "fe45c580-badf-4d3f-be46-275f7530817c",
    "name": "temperature",
    "value": 21.45,
    "time":"2022-01-01T00:00:00.000Z",
    "metadata": {
        "error":0.01
    }
}

The metadata field can be used to tag the measurement with some additional information, which does not fit any other element in the project, for example in this case the metadata field is used for representing the dynamic uncertainty.

warning

Do not use the metadata field to store additional timeseries, create separate timeseries instead: metadata fields cannot be used as query filters. Also, static information about the source of the measurement should be stored in the corresponding entity, such as the device or the asset.

Events​

An events represent that something happened within a system, for example a threshold was reached or an actuation was made on a physical machine, an example events could be the following:

{
    "projectId": "1c571c95-dd6a-4e7c-8876-9a050bf22a86",
    "source": "/projects/1c571c95-dd6a-4e7c-8876-9a050bf22a86/'devices/fe45c580-badf-4d3f-be46-275f7530817c",
    "type": "myPoject.myMachineType.myAction",
    "eventTime":"2022-01-01T00:00:00.000Z",
    "data": {
      "someParameter":10.5
    }
}

Writing Time Series

To learn how to send time series data through the HTTP api, please visit the API Documentation page

To learn how to send time series data through MQTT, please visit the MQTT Documentation page

Metrics are not written immediatly, they are validated first and then, if valid, written into a write queue. This means that you might experience some minimal lag between writes and reads.

Note that this method will upsert metrics based on the timestamp, so passing two request with the same name,time, deviceId and projectId but different value will result in one write and one update.