Payload formats based on Google Protocol Buffers 3

There are two payload formats based on Google Protocol Buffers 3 for time series:

  • Format TsChannelsFloatSeriesProto3
  • Format TsChannelsFloatAtTimeProto3

Per request / message, the formats let you include data for one device for one or more of its channels. The device is always denoted outside of the payload (as part of the URL path / MQTT topic). Therefore, a device identifier does not appear within any of the formats.

Using the format TsChannelsFloatSeriesProto3

- format_name: TsChannelsFloatSeriesProto3
- format_id: 16
- format_byte_id: the byte value 0x10 (Binary 00010000)
- Technology: Protocol Buffers 3

Definition

syntax = "proto3";
package com.recogizer.data.timeseries.channels.floatseries.proto3;

message ChannelsFloatSeries {
  map<int32, FloatSeries> data = 1;
}

message FloatSeries {
  repeated FloatSeriesPoint values_float = 1;
}

message FloatSeriesPoint {
  int64 time = 1;
  float value = 2;
}

This protobuf3 data format can be used to send time series to the Cloud.

  • The integer keys in the map are the channel indices, each pointing to a series of floats over time.
  • The field time represents the point in time of a value on a time series. It requires an int64 simply representing EpochMillis (not to be confused with EpochSeconds).
  • The field value represents the amplitude of a value on a time series. It requires a protobuf3 float, which must however at the same time adhere to the further restrictions of the Java float, since this float is interpreted by the Cloud as a Java float. The float may be positive, zero or negative. It must not be lesser or greater than the minimum or maximum float value supported by Java, respectively.
  • You may freely omit channels if there are currently no values to be sent for these. Alternatively, the series of values for these channels may be empty.

Using the format TsChannelsFloatAtTimeProto3

- format_name: TsChannelsFloatAtTimeProto3
- format_id: 18
- format_byte_id: the byte value 0x12 (Binary 00010010)
- Technology: Protocol Buffers 3

Definition

syntax = "proto3";
package com.recogizer.data.timeseries.channels.floatattime.proto3;

message ChannelsFloatAtTime {
  int64 time = 1;
  map<int32, float> data = 2;
}

This protobuf3 data format can be used to send values from one particular point in time to the Cloud.

  • The integer keys in the map are the channel indices, each pointing to one value.
  • The field time represents the point in time of the values. It requires an int64 representing EpochMillis (not to be confused with EpochSeconds).
  • The values in the map represent the amplitude at the point in time in the respective channel. Each of these values requires to be a protobuf3 float, which must however at the same time adhere to the further restrictions of the Java float, since this float is interpreted by the Cloud as a Java float. The float may be positive, zero or negative. It must not be lesser or greater than the minimum or maximum float value supported by Java, respectively.
  • You may freely omit channels if there are currently no values to be sent for these.

An example scenario for using this format is when you wish to publish measurements to the Cloud, in regular intervals, also usually in near time or near real time, in such a way that in each request / message you want to only include values from one particular point in time. In such a scenario, this format reduces overall bandwidth consumption when compared to the format TsChannelsFloatSeriesProto3.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.