Send device data to the platform.
# Request Topic and Payload
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!
{
"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 (see also [Event messages management](## Event messages management)). | A alarm that triggers without duration like"temperature_alarm". An alarm like "blackout_alarm" that has a duration |
Event messages management
Here's how the different situations while handling events are managed:
When a new start event arrives (start):
If there isn't already an ongoing event for the combination of machine and event name, a new event is created. This new event has a start timestamp but no end timestamp because we don't yet know when it will finish.
When a single event arrives:
If there isn't already an ongoing event and the current event is not a start, a new event is created with identical start and end timestamps because the event represents a single moment, not a period.
When another start event arrives while there is already an ongoing event:
The ongoing event is updated with an end timestamp, as we now know when it finished.
A new event is created for the start of the new period.
When an end event arrives:
The ongoing event is updated with an end timestamp, marking the conclusion of the period.
When another type of event arrives while there is already an ongoing event:
The ongoing event is updated with a new end timestamp, reflecting the latest known moment.
A new event is created to represent this update.
When an end event arrives while there's no ongoing event:
The end event message is discarded.
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.
{
"request_id": "UUID",
"metrics": [
{
"timestamp": 1500000000030,
"data": [
{
"name": "temperature_core",
"value": "19",
"realtime": true
}
]
}
]
}