Generic Data Model¶

This page gives a short introduction into GDM and explains how it is used and what features it provides.

Introduction¶

graph LR
D[<strong>Device</strong><br/>Produces data in GDM]
C[<strong>IoT Hub</strong><br/>Read + Process data]
S1[<strong>Service 1</strong><br/>Understands GDM]
S2[<strong>Service <em>n</em></strong><br/>Understands GDM]
D -->|GDM-JSON|C
C --> S1
C --> S2

The generic data model defines a JSON data structure which is understood by all services which process data in Bühler Insights. Sending machine data, plant data, etc. to Bühler Insights Gateway in GDM format allows the services to process this data as they know where to read values, metadata, and more.

A GDM message contains the following pieces of information:

• Header with message type and schema version
• Origin of the data, i.e. device and plant
• Data Values – this is the important bit
• Metadata with both required and custom fields

GDM messages can be of the following type:

• State for sending state data
• Alarm for sending alarms
• Notification - Not supported yet
• File Upload - Not supported yet
• Configuration - Not supported yet

Timestamp Handling¶

Every value and alarm requires a timestamp. The timestamp can be provided by different parties: the device which generates the data, the IoT Agent (Bühler Insights Gateway), and finally the ingestion pipeline (Bühler Insights).

If the device knows the current time, the device timestamp is used as it is the most accurate timestamp. If the device has no knowledge about time, the agent timestamp and finally the ingestion timestamp are used as fall-back.

Timestamps must be in ISO 8601 format; see RFC 3339.

Header Fields¶

Metadata in GDM¶

Metadata adds additional information to a value. This information can later be used to filter data. For example, a value could have a batch number, which later allows to show measurements of only this batch.

Some widgets in the Bühler Insights Portal can also show metadata information.

Some metadata fields are required, and the requirements depend on the type of the message. The plant ID is always required to identify the origin.

In GDM, metadata can be defined both in the data section and on the root level. Metadata on root level is merged into metadata for each data point.

Example GDM State Message¶

{
    "deviceId": "Fast_Baker_42",
    "messageId": "d32779a6-9b8e-4fa0-9941-9a147040f24a",
    "messageType": "state",
    "messageVersion": "1.0",
    "metadata": {
        "plantId": "123123"
    },
    "data": [
        {
            "name": "Temperature_Heater",
            "metadata": {
                "unit": "°C"
            },
            "values": [
                {
                    "deviceTimestamp": "2020-01-16T09:30:02.500Z",
                    "value": 120.3
                },
                {
                    "deviceTimestamp": "2020-01-16T09:31:09.000+01:00",
                    "value": 139.8
                }
            ]
        }
    ]
}

State Messages¶

State messages contain some fields which are soon deprecated as they are replaced by TOM. Topology will in future be defined there to avoid sending redundant data.

Alarm Messages¶

Alarms require additional metadata fields to be set.

If the acknowledged state is unset (null or undefined), the alarm has to be acknowledged on the Bühler Insights Platform. If the state is a boolean value, the alarm will be shown as active until a new alarm message is sent where the alarm is marked as inactive.

The reason field, which is used by WinCos, is treated specially. When multiple alarms with the same name but different reason are sent, they are listed as individual alarms. When one is sent with the active flag set to false, all alarms with this name are set to inactive as well.

More details on the handling of those metadata values can be found in the Bühler Insights Platform documentation.

{"environments":[],"pdf-download":true}