Appendix

Publisher data structures

Compact

The compact data structure will only send the tag name for each event once, which in turn reduces the size of the message, and therefore, reduces the bandwidth usage. On the other hand, this data structure is slightly more complicated to parse than the extended data structure. The following code snippet shows an example of this data structure:

{
    "TAGNAME": [{
        "v": "VALUE",
        "q": "QUALITY",
        "ts": "TIMESTAMP"
       },
        {…}
    ],
    "TAGNAME2": […],
}

An example message using this compact data structure can be seen in the below snippet:

{
    "/FOLDER1/TAG1": [{
            "v": 1.56,
            "q": 192,
            "ts": "2018-02-05T10:29:00.815Z"
        }, {
            "v": 2.48,
            "q": 192,
            "ts": "2018-02-05T10:29:10.922Z"
        }, 
        {…}],
    "/FOLDER1/TAG2": [{
            "v": "example string",
            "q": 192,
            "ts": "2018-02-05T10:29:15.132Z"
        },
        {…}]
}

Extended

Extended data structures, as opposed to compact structures, send the tag name in every event, which can result in duplicated tag names if the same tag has two or more events. The advantage here is that it's simpler to parse. The format of this data structure is shown in the below code snippet:

[
    {
        "t": "TAGNAME",
        "v": "VALUE",
        "q": "QUALITY",
        "ts": "TIMESTAMP"
    },
    {…},
]

The following snippet shows an example of the extended data structure using simulated data:

[
    {
        "t": "/Group1 /Tag1",
        "v": 1.56,
        "q": 192,
        "ts": "2020-02-05T10:29:00.815Z"
    }, {
        "t": "/Group1/Tag1",
        "v": 2.48,
        "q": 192,
        "ts": "2020-02-05T10:29:10.922Z"
    }, {
        "t": "/Group1/Tag2",
        "v": "example string",
        "q": 192,
        "ts": "2020-02-05T10:29:15.132Z"
    },
    {…}
]

Compact Protocol Buffers

When serializing to Protocol Buffers, both the compact and extended data structures will vary a little due to Protocol Buffers that require object keys to be known at compile time. As such, the compact data structure will have the following format, using a pseudo-language similar to protobuf:

{
    events:[
        {
            tag:TAGNAME,
            data: [
                {
                    value: oneof valueType;
                    quality: QUALITY;
                    timestamp: oneof timestampFormat;
                    valueType oneof {
                        double numberValue;
                        string stringValue;
                        boolean booleanValue;
                    }
                    timestampFormat oneof {
                        double epoch;
                        string iso;
                        google.protobuf.Timestamp googleTs;
                    }
                },
                {…}
            ]
        }
        {
            tag:TAGNAME2
            data:[…]
        },
        {…}
    ]
}

The following code snippet shows a message with data using a compact protobuf data structure (represented as JSON for clarity, since protobuf is a binary serialization format): 

{
    "events": [
        {
            "tag": "/Group1/TAG1",
            "data": [{
                "valueType": "numberValue";
                "quality": 192;
                "timestampFormat": "iso";
                "numberValue": 12345
                "iso": "2018-02-02T10:00:15.123Z"
            }, {
                "valueType": "numberValue";
                "quality": 192;
                "timestampFormat": "iso";
                "numberValue": 12346
                "iso": "2018-02-02T10:00:25.352Z"
            }, {…}]
        },
        {
            "tag": "/Group1/TAG2",
            "data": [{
                "valueType": "stringValue",
                "quality": 192,
                "timestampFormat": "googleTs",
                "stringValue": "test string",
                "googleTs": {"low": 157182060, "nanos": 859000000}
            }, {…}]
        },{…}
    ]
}

Extended Protocol Buffers

Extended Protocol Buffers, just like their normal counterpart, send the tag name in every message. As such, these messages use more bandwidth, although they are also easier to parse. This structure can be seen in the below snippet, using a pseudo-language similar to protobuf:

{
    events: [
        {
            tag:TAGNAME;
            value: oneof valueType;
            quality: QUALITY;
            timestamp: oneof timestampFormat;
            valueType oneof {
                double numberValue;
                string stringValue;
                boolean booleanValue;
            }
            timestampFormat oneof {
                double epoch;
                string iso;
                google.protobuf.Timestamp googleTs;
            }
        },
        {…},
]}

 The following code snippet shows an example of a message serialized using this data structure (represented as JSON for clarity):

{
    "events": [
        {
            "tag":"/Group1/Tag1",
            "valueType": "numberValue";
            "quality": 192;
            "timestampFormat": "iso";
            "numberValue": 12345
            "iso": "2018-02-02T10:00:15.123Z"
        }, {	
            "tag": "/Group1/Tag1",
            "valueType": "numberValue";
            "quality": 192;
            "timestampFormat": "iso";
            "numberValue": 12346
            "iso": "2018-02-02T10:00:25.352Z"
        }, {
            "tag": "/Group1/Tag2",
            "valueType": "stringValue",
            "quality":192,
            "timestampFormat": "googleTs",
            "stringValue": "test string",
            "googleTs": {"low": 157182060, "nanos": 859000000}
        }
    ]
}

Publisher .proto

Publishers use the following .proto file to encode the message:

syntax = "proto3";
import "google/protobuf/timestamp.proto";

message Extended{
   repeated Event events = 1;
};

message Compact{
   repeated CompactEvents events = 1;
};

message CompactEvents{
   string tag = 1;
   repeated Event data = 2;
}

message Event{
   string tag = 1;
   oneof valueType{
       double numberValue = 2;
       string stringValue = 3;
       bool booleanValue = 4;
   }
   int32 quality = 5;
   oneof timestampFormat {
       double epoch = 6;
       string iso = 7;
       google.protobuf.Timestamp googleTs = 8;
   }
}

Writer data structures:  

Compact

The compact data structure for Writers mimics the one used for Publishers, as it is intended to be used to reduce bandwidth usage as much as possible. This structure can be seen in the following snippet:

{
   "TAGNAME1": "VALUE1",
   "TAGNAME2": "VALUE2",
   ...
}

An example message using this data structure is shown below:

{
   "/Group1/Tag1": 123.56,
   "/Group2/Tag2": "example string",
   ...
}

Extended

This case is similar to compact, as it has the same data structure as a publisher, but with less fields:

[
    {
        "t": "TAGNAME1",
        "v": "VALUE1",
    }, {
        "t": "TAGNAME2"
        "v": "VALUE2"
    },{…}
]

An example of a valid message for this data structure is as follows:

[
    {
         "t": "/FOLDER1/TAG1",
         "v": 1.56,
    }, {
         "t": "/FOLDER1/TAG2"
         "v": true
    }{,...}
]

Protocol Buffers

Writers will only have one data structure when using protobuf serialization. This data structure is shown in the following snippet:

{
    events: [
        {
            tag: TAGNAME,
            valueType oneof {
                double numberValue;
                string stringValue;
                boolean booleanValue;
            }
        },
        {…}
]

An example message with this data structure is shown in the below snippet (Represented as JSON for clarity):

{
   events: [
       {"tag": "/Group1/Tag1", "numberValue": 1},
       {"tag": "/Group1/Tag2", "stringValue": "example string"},
       {"tag": "/Group2/Tag3", "booleanValue": true}
    ]
}

Writer .proto

The writer uses the following .proto file to decode incoming messages:

syntax = "proto3";

message Writes{
   repeated Data events = 1
}

message Data{ 
   string tag = 1;
   oneof valueType{ 
       double numberValue = 2;
       string stringValue = 3;
       bool booleanValue = 4;
   }
}

An example of a valid message using this Protocol Buffer definition is shown in the below snippet (Represented as JSON for clarity)

{
    events:[
        {"tag": "/Group1/Tag1", "numberValue": 1},
        {"tag": "/Group1/Tag2", "stringValue": "example string"},
        {"tag": "/Group2/Tag3", "boolValue": true}
        ]
}

MQTT Client Full Product Details