Data ingestion

Device → Things5: data_req

Send device data to the platform.

# Request Topic and Payload

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

Payload

❗️

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

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
                }
            ]
        }
    ]
}

Rules and errors

• value must be a JSON string: "value": "19", not "value": 19. For metrics the string must contain a number.
• realtime is honoured only on metrics.
• If any part of the message is invalid, the whole message is rejected and nothing is stored. The answer on data_res lists the reason in errors:

Things5 → device: data_res

Response for data ingestion request

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

Payload

{
    "request_id": "UUID",
    "errors": [
      "error",'
      "error"
    ]
}

Payload Parameters

HACCP data

How to send HACCP data to Things5

What is HACCP?

Hazard Analysis Critical Control Points (HACCP) is an internationally recognized method of identifying and managing food safety related risk and, when central to an active food safety program, can provide your customers, the public, and regulatory agencies assurance that a food safety program is well managed.

HACCP is a management system in which food safety is addressed through the analysis and control of biological, chemical, and physical hazards from raw material production, procurement and handling, to manufacturing, distribution and consumption of the finished product.

Manufacturers and vendors use the system as a basis for their food safety management programs and for compliance with GFSI audit schemes.

You can send Haccp logs to Things5 in order to make your Haccp reports available to the cloud.

How to send HACCP logs to Things5?

A Haccp report consists in a list of records. These records can be sent to Things5 like any other event.
Those events can be classified in the T5 portal as HACCP events so they can be automatically available in the HACCP report that can be downloaded from the appropriate HACCP section page.

In order to learn how to send T5 events you can take a look at [Sub] Data ingestion request.

HACCP payload example (timestamp in milliseconds)

{
    "request_id": "UUID",
    "events": [
        {
            "timestamp": 1500000000010,
            "data": [
                {
                    "name": "high-pressure-alarm",
                    "metadata": {
                        "temperature": "22"
                    }
                }
            ]
        },
        {
            "timestamp": 1500000000020,
            "data": [
                {
                    "name": "haccp-program-start",
                    "metadata": {
                      "name": "my chilling program"
                    }
                }
            ]
        }
    ]
}

In this example high-pressure-alarm and haccp-program-start records are sent to Things5.
The metadata field provides additional data for the single record.