Message Format

Some protocols (e.g. MQTT) do not define a standard message format. For such inputs and outputs, the message format must be specified in the configuration. Currently the available message formats are:

• JSON
• Protobuf
• Binary

Each message packs all data that is fetched/received by a Gateway input simultaneously (e.g. all OPC UA nodes that are specified in a OPC UA polling input are polled together and are therefore packed into a single message). In case of data aggregation (multiple inputs are connected to a single output), each input will result in a separate message (data from multiple inputs is not combined).

Both message formats include a timestamp property that is filled by the input at the moment the data enters the Gateway input. The json message format does not include any information about the data types of the variables included while the protobuf format implicitly carries the type information.

JSON

An output that is set to the json message format produce messages according to the following schema (downoad):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9999999999999999999,
      "description": "19-bit Unix timestamp in nanoseconds"
    },
    "variables": {
      "type": "object",
      "patternProperties": {
        "^[a-zA-Z0-9_]+$": {
          "oneOf": [
            { "type": "string" },
            { "type": "boolean" },
            { "type": "integer" },
            { "type": "number" },
            { "type": "integer", "minimum": 0, "maximum": 255 }
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "required": ["timestamp", "variables"]
}

The following is an example of such a message:

 {
  "timestamp": 1234567890123456789,
  "variables": {
    "vara": "test",
    "varb": 1,
    "varc": 0.35,
    "vard": -7
  }
}

Protobuf

An output that is set to the protobuf message format use the following protobuf schema (downoad):

syntax = "proto3";
 
import "google/protobuf/timestamp.proto";
 
message BoolArray {
  repeated bool values = 1;
}
 
message Int16Array {
  repeated int32 values = 1;
}
 
message UInt16Array {
  repeated uint32 values = 1;
}
 
message Int32Array {
  repeated int32 values = 1;
}
 
message UInt32Array {
  repeated uint32 values = 1;
}
 
message Int64Array {
  repeated int64 values = 1;
}
 
message UInt64Array {
  repeated uint64 values = 1;
}
 
message FloatArray {
  repeated float values = 1;
}
 
message DoubleArray {
  repeated double values = 1;
}
 
message StringArray {
  repeated string values = 1;
}
 
message TimestampArray {
  repeated google.protobuf.Timestamp values = 1;
}
 
message Variable {
  string name = 1;
  oneof value {
    bool bool_value = 2;
    int32 int16_value = 3;
    uint32 uint16_value = 4;
    int32 int32_value = 5;
    uint32 uint32_value = 6;
    int64 int64_value = 7;
    uint64 uint64_value = 8;
    float float_value = 9;
    double double_value = 10;
    string string_value = 11;
    google.protobuf.Timestamp datetime_value = 12;
    NestedVariable nested_variable = 13;
    BoolArray bool_array = 14;
    Int16Array int16_array = 15;
    UInt16Array uint16_array = 16;
    Int32Array int32_array = 17;
    UInt32Array uint32_array = 18;
    Int64Array int64_array = 19;
    UInt64Array uint64_array = 20;
    FloatArray float_array = 21;
    DoubleArray double_array = 22;
    StringArray string_array = 23;
    TimestampArray datetime_array = 24;
    NestedVariableArray nested_variable_array = 25;
  }
}
 
message NestedVariable {
  Variable variable = 1;
}
 
message NestedVariableArray {
  repeated NestedVariable values = 1;
}
 
message DataMessage {
  google.protobuf.Timestamp timestamp = 1;
  repeated Variable variables = 2;
}

The same example as in the json section looks as follows in protobuf message format (decoded protobuf displayed as a json object):

{
  "timestamp": {
    "seconds": 1234567890,
    "nanos": 123456789
  },
  "variables": [
    {
      "name": "vara",
      "string_value": "test"
    },
    {
      "name": "varb",
      "uint32_val": 1
    },
    {
      "name": "varc",
      "float_val": 0.35
    },
    {
      "name": "vard",
      "int64_value": -7
    }
  ]
}

Binary

The binary message format is a special case as such, that an input that uses the binary message format does not parse or inspect the incoming data at all. The data is simply forwarded to the connected outputs as is. In the same way, the output just forwards the data to the data sink. For this reason it is important that inputs that use binary message format can only be connected to outputs that use binary message format and vice versa.