[Pub] Data ingestion request

Send device data to the platform.

# Request Topic and Payload

Topic

topic

things5-production/v1/devices/<device-id>/data_req

Payload Representation

❗️

Pay attention to data order and timestamp

Never rely on device timestamp. Use a NTP server to get the UTC time. If not possibile, do not sent timestamp at all, things5 will fallback on the time the message is received.
Timestamps need to be incrementally sorted within and across the requests.
For each variable, any timestamp older than one already received will be discarded. Eg.: if you send temperature_core now you can't send temperature_core data for 1 hour ago, but you can still send temperature_room data for 1 hour ago.
Timestamp must be in milliseconds!

JSON

{
  "request_id": "UUID",
  "metrics": [
    {
      "timestamp": 1500000000030,
      "data": [
        {
          "name": "temperature_core",
          "value": "19"
        },
        {
          "name": "temperature_room",
          "value": "22"
        }
      ]
    },
    {
      "timestamp": 1500000000040,
      "data": [
        {
          "name": "temperature_core",
          "value": "23"
        },
        {
          "name": "temperature_room",
          "value": "29"
        }
      ]
    },
    {
      "timestamp": 1500000000070,
      "data": [
        {
          "name": "temperature_core",
          "value": "31"
        },
        {
          "name": "temperature_room",
          "value": "40"
        }
      ]
    }
  ],
  "states": [
    {
      "timestamp": 1500000000020,
      "data": [
        {
          "name": "door",
          "value": "open",
          "metadata": {
            "temperature": "22"
          }
        },
        {
          "name": "status",
          "value": "defrost"
        }
      ]
    }
  ],
  "events": [
    {
      "timestamp": 1500000000010,
      "data": [
        {
          "name": "temperature_alarm"
        },
        {
          "name": "high-pressure-alarm",
          "metadata": {
            "temperature": "22"
          }
        },
        {
          "name": "blackout_alarm",
          "start": true
        }
      ]
    },
    {
      "timestamp": 1712735702000,
      "data": [
        {
          "name": "blackout_alarm",
          "end": true
        }
      ]
    }
  ]
}

Payload Parameters

type	desctiption	example
metrics	Any kind of value that contribute to define a measure. Value must be a string that can can be cast as a double	A measure like "speed" or "temperature".
states	A state is a variable that can assume n different values of type string. A state variable defines the state of a device for a period of time, until the state variable assumes another value.	a "door" state variable can assume the values "open" and "closed". A "compressor_status" state variable can assume the value "on" "off". A "device_status" variable can assume the values “on”|”off”|”stand_by”|”updating_firmware”
events	Define the situation of the device in a specific point in time. The event can optionally have a duration if it's sent with a "start" and later on a "end" is received, like in the example above.	A alarm that triggers without duration like"temperature_alarm". An alarm like "blackout_alarm" that has a duration

Realtime data

There's an option that allows the device to send data that won't be stored in the database by adding "realtime": true in the metric object. Transfered data points will be billed as usual.

javascript

{
    "request_id": "UUID",
    "metrics": [
        {
            "timestamp": 1500000000030,
            "data": [
                {
                    "name": "temperature_core",
                    "value": "19",
                    "realtime": true
                }
            ]
        }
    ]
}