IoT topics & formats

Updated June 03, 2025 07:59

The default data ingress path for sensor data into the Factbird Cloud, is through AWS IoT using MQTT.

To enable data transmission directly to the Factbird cloud, two main requirements needs to be met:

A local OPC server set up to communicate with a public endpoint using MQTT
Support for TLS 1.2 for authentication and data encryption

The data is split into two major groups, "event" & "input" by the following definition:

input is regularly sampled time-series data usually counters or process values. Examples of data types that belongs in the input group of data could be:
- Bottleneck counters of a production line
- Scrap sensors
- Temperature measurements
- Vibration measurements
event are data that happens at a certain time, and usually as a response to some event happening. In the Factbird Cloud, events are not shown on a graph, but are instead use to tie an action to an event. Examples of event data could be:
- Batch started / stopped
- Button pressed
- Stop registered by the line
- Stop split

Both types of data comes with some requirements & limitations on their data structure. For example, for both types it is required to provide a timestamp of when the event happened, or the data point was sampled. All timestamps are in UTC time zone with millisecond resolution.

In order to detect when a line is stopped as opposed to running, we require input data to be sent at a fairly regular interval, even if the value of the sensor has not changed since the last transmission. Usually this means that each time series value (input) should be sampled and sent at least every 30 seconds.

MQTT Topics

Input and Event data is to be sent to two different MQTT topics as described here:

input: <device_type>/input/<uuid>
event: <device_type>/event/<uuid>

where

device_type describes the type of device, usually this should be "plc" for custom integrations
uuid is a unique identifier created by Factbird, that authenticates the communication in combination with an X.509 certificate issued by Factbird. This UUID must also be used as the Client ID in the MQTT client when connecting to AWS IoT.

Quality of Service (QoS)

The Factbird system is designed for a QoS of 1 (The broker/client will deliver the message at least once, with confirmation required). QoS 2 is currently not supported by AWS hence, we do also not support that. If using QoS 0 (The broker/client will deliver the message once, with no confirmation) that might result in data loss and hence strongly disregarded.

MQTT data scheme

When looking at the two types of data from an MQTT JSON side, both types follow the same data scheme, that looks like this:

{
    "values": [
        {
            "id": "sensor_0",
            "v": 0,
            "t": 1621497147542,
            "q": true
        },
        {
            "id": "sensor_1",
            "v": 700,
            "t": 1621497147542,
            "q": true
        }
    ],
    "timestamp": 1621497161597
}

This scheme is used for both input and event data, but with a little different meaning of the fields

Payload size limit: Each payload can at maximum be 128 KB.

Input scheme definition

values is an array of individual sensor readings, that might be from the same sensor, or from multiple sensors, where:
- id is an identifier, that uniquely distinguishes the sensor/tag, when combined with the MQTT Client ID.
- v is the value of the sensor/tag at the time of sampling.
- t is a timestamp describing when the value is sampled in milliseconds since UNIX epoch in UTC.
- q is a boolean value that can be used to describe if the measurement is good or bad. This value is used for example to mark measurements that are out of range and as such not valid, in order to aid faster debugging of wrongly configured sensors. This value is optional and if omitted defaults to True.
timestamp is the time of transmission of the packet in UNIX milliseconds in UTC. If systems are caching or buffering data in case of network outage, this field should be updated before re-sending to reflect the actual time of transmission, opposite to the t timestamps, that should always reflect when the value was sampled. This value is optional and if omitted defaults to the time data is received in the Factbird cloud.

Event scheme definition

values is an array of individual events, that might be from the same source, or from multiple sources, where:
- id is an identifier, that uniquely distinguishes the event source, when combined with the MQTT Client ID.
- v is a value that can be used as part of the corresponding action in the cloud. This could be the batch number started, or a stop code describing why the line has stopped.
- t is a timestamp describing when the event happened.
- q is a boolean value that can be used to describe if the event is good or bad. This value is optional and if omitted defaults to True.
timestamp is the time of transmission of the packet. If systems are caching or buffering data in case of network outage, this field should be updated before re-sending to reflect the actual time of transmission, opposite to the t timestamps, that should always reflect when the event happened. This value is optional and if omitted defaults to the time data is received in the Factbird cloud.

Related to

integration