MQTT Prototocol

MQTT-Endpoint

General Protocol Details 🔗

Parameter	Value	Note
Protocol	MQTT Version 3.1.1	Standard version.
Direction	Publish (Device to Broker)	Data originates from the device.
QoS (Quality of Service)	QoS 2 (Exactly Once)	Guarantees delivery without duplicates.
Retain Flag	FALSE	The message is not stored by the broker for future subscribers.
Encryption	SST/TLS	Encrypted connection with username and password authentication

Topic Structure 🏷️

The Topic path follows a strict hierarchical structure:

<Environment> / <device_id> / <Data Type> / <encoding>

Topic Level	Placeholder	Possible Values	Description
1st	Environment	test ,public, private	Defines the system (testing vs. production).
2nd	device_id	UUID or Serial Number	Unique identifier of the originating device.
3rd	Data Type	agg_data, event, dataseries, mixed	Defines the content of the payload.
4th	encoding	json, gjson, cbor	Defined the encoding of the payload

Payload Format (Data Types)

Data Type	Object Type	Content Description
agg_data	Aggregated Data Object	Aggregated measurement values.
event	Event Data Object	Single, time-stamped events.
dataseries	Dataseries Object	Collections of time-stamped measurement data points.
mixed	Multiple/Mixed Objects	Container for various object types within a single payload.

Payload Encoding 🗜️

The payload format depends on the Data Type in the topic.

Encoding	Required Encoding	Valid for Format	Content Description
json	JSON Format (UTF-8)	agg_data, event, dataseries	Plain JSON Format, human readable
gjson	GZIP JSON Format (UTF-8)	agg_data, event, dataseries	Compressed (gzip) JSON Format
cbor	CBOR2 Format	mixed	CBOR2 encoded collections of multiple objects

Object Structure

All objects must contain the fields type, measurement_uuid and timestamp (except: mixed)

Aggregated Data Object (Topic: .../agg_data)

Field Name	Data Type	Description	Example
type	String	Fixed Value: aggregated_data	"aggregated_data"
measurement_uuid	UUID String	Unique ID for actual Measurement	"dfa79ef0-7a92-45b9-906d-93650968bf93"
interval_sec	Integer (Sekunden)	Aggregation interval in seconds.	10
timestamp	Float/Double	Unix-Timestamp in seconds (for the End of the Aggretation Interval.	1665227310.000000
data	JSON Object	Measurement values as Key, Value Pairs	{"Freq": 49.999, "U1_rms": 209.733}

{ 
  "type": "aggregated_data"
  "measurement_uuid": "dfa79ef0-7a92-45b9-906d-93650968bf93",
  "interval_sec": 10,
  "timestamp": 1665227310.000000,
  "data": {
    "Freq": 49.999,
    "U1_rms": 209.733
   }
}

Event Data Object (Topic: .../event)

Field Name	Data Type	Description	Example
type	String	Fixed Value: event	"event"
measurement_uuid	UUID String	Unique ID for actual Measurement	"95056a9b-5141-4641-81df-2185f0513b41"
timestamp	Integer/Long	Unix-Timestamp in microseconds of the Start of the event	1665227374430856
event_type	String	Type of Event	"LEVEL_LOW"
chanel	String	Related measurement channel	"U1_1p_rms"
data	JSON Object	event specific data	{"extrem_value": 0.328, "id": "90253c70-3c4d-4912-bbb0-3e1721ad7dba", "duration": 0.12}

{ 
  "type": "event"
  "measurement_uuid": "95056a9b-5141-4641-81df-2185f0513b41", 
  "timestamp": 1665227374430856, 
  "event_type": "LEVEL_LOW",
  "chanel": "U1_1p_rms", 
  "data": {
    "extrem_value": 0.328,     
    "id": "90253c70-3c4d-4912-bbb0-3e1721ad7dba", 
    "duration": 0.12
  }
}

Dataseries Object (Topic: .../dataseries)

Field Name	Data Type	Description	Example
type	String	Fixed value: timeseries_data	"timeseries_data"
measurement_uuid	UUID String	Unique ID for actual Measurement	"384d93c4-b23a-49de-aca7-bc26e433f640"
data	JSON Object	Timeseries for each channel	see details below

Details for data Object in Dataseries:

Each key in the data-Object (e.g. Freq, U1_1p_rms) is a object with two fields:

• data: Array of double/float values for the measurement channel
• ts: Array of integer/long (Unix Timestamp in Microseconds) accordingly

{
  "type": "timeseries_data",
  "measurement_uuid": "384d93c4-b23a-49de-aca7-bc26e433f640",
  "data": {
      "Freq": {
        "data": [
          50.001,
          50.002
        ],
        "ts": [
          1665227296440929,
          1665227296640890
        ]
      },
      "U1_1p_rms": {"data": [...], "ts": [...]}
   }
}

Timestamp Standardization ⏱️

Caution, the time units are NOT standardized across all object types. Implementers must adhere to the specific unit for each field:

Object Type	Field Name	Data Type	Required Time Unit
Aggregated Data	timestamp	Float/Double	Unix Timestamp in Seconds
Event Data	timestamp	Integer/Long	Unix Timestamp in Microseconds
Dataseries	ts (Array)	Integer/Long	Unix Timestamp in Microseconds (per array element)