ProtobufEncoder
ProtobufEncoder
The ProtobufEncoder is a sequencer block, that allows to encode input events data to Protocol Buffers message encoding.
Protocol Buffers (protobuf) is a method for serializing structured data, developed by Google. It is designed to be a language-agnostic, platform-neutral, and extensible mechanism for serializing structured data. Protocol Buffers is widely used for communication protocols, data storage, and configuration files, among other things.
Protocol Buffers uses an Interface Definition Language (IDL) to define data structures - message types and their fields. Protocol Buffers definitions are usually contained in the files having .proto extension and have to be compiled to the programming language used by the application using protoc compiler. For this block you only need to copy the definitions into the block Proto attribute value instead and the definitions will be runtime-compiled from there.
Events
| Name | Appearance | Description |
|---|---|---|
| Protocol Buffers repeated field name | Any number of user-configurable input events for repeated fields | Data of this input event will be appended to the Protocol Buffers message repeated field named as the event |
| Encode | Predefined input event | Causes gathered data to be encoded. Event Data arguments will be added and encoded as Protocol Buffers message fields. |
| Encoded | Predefined output event | Will be emitted on Encode event and contains encoded Protocol Buffers message in EncodedMessage argument. |
| Init | Predefined input event | Will clear all gathered data and reset the encoder, then will emit Inited |
| Inited | Predefined output event | Will be emitted after Init is done |
Arguments
| Name | Appearance | Description |
|---|---|---|
| Protocol Buffers message field name to encode | Any number of user-configurable input arguments | Argument value will be encoded to output as Protocol Buffers message field |
| EncodedMessage | Predefined output argument | The Protocol Buffers encoded message (binary string). Will be sent out with Encoded events. |
Properties
| Name | Description |
|---|---|
| Proto | Protocol Buffers message definition in Interface Definition Language (IDL). It can be copied here from the .proto file, used for the particular communication definition. |
| Message | Message name to use from the Protocol Buffers definition for the output encoding. There can be several messages described in the Proto definition, but only the one named in Message is used for this block for encoding. |
Note: The encoded message (EncodedMessage argument) may contain non-printable characters, therefore the Command attribute of Encoded event has to be set to any other value than CM_TEXTCOMMAND (`20100_16`) - which will instruct the CDP to send the event data over in binary form. Also, make sure you set the Command attribute to the very same value on the event receiver side. The same applies to the user-configurable input events for repeated fields where encoded messages are sent in from previous blocks.
Example
The following block diagram shows how to cascade two ProtobufEncoder blocks to encode a Protocol Buffers message SensorTempSamples with the definition like this:
syntax = "proto3"; message TempSample { uint64 timestamp = 1; double temperature = 2; } message SensorTempSamples { int32 id = 1; repeated TempSample measurements = 2; }
For that, input arguments temperature and humidity were added to the first ProtobufEncoder, to encode TempSample message. These messages are sent to the cascaded ProtobufEncoder1, into the added input event measurements, that will receive and gather these encoded messages into memory. When Encode event is received the data is encoded with all the gathered measurements repeated elements.
Both ProtobufEncoder's Proto attributes were set to the message definition given above. The ProtobufEncoder Message attribute was set to TempSample and the ProtobufEncoder1 Message attribute was set to SensorTempSamples.
To better understand the data flow, some Sequencer.DebugPrinter blocks were also connected to the blocks to print the time and the data received with events into the application output window. Below is an example output of these debugging blocks for encoding sequence of the SensorTempSamples message for sensor id=101 having 2 TempSamples with temperatures 24.5 and 23.4 (note that the binary values of EncodedMessage argument are logged in hexadecimal form):
14:15:02.524 DEBUG: App.ArrayElementDebug: EventIn: Data arguments: timestamp=1697710843;temperature=24.5 14:15:02.524 DEBUG: App.RepeatedElementDebug: EventIn: EncodedMessage: 00000000 08 fb 85 c4 a9 06 11 00 00 00 00 00 80 38 40 |.............8@| 14:15:04.024 DEBUG: App.ArrayElementDebug: EventIn: Data arguments: timestamp=1697711143;temperature=23.4 14:15:04.024 DEBUG: App.RepeatedElementDebug: EventIn: EncodedMessage: 00000000 08 a7 88 c4 a9 06 11 66 66 66 66 66 66 37 40 |.......ffffff7@| 14:15:05.523 DEBUG: App.EncodeDebug: EventIn: Data arguments: id=101 14:15:05.523 DEBUG: App.EncodedDebug: EventIn: EncodedMessage: 00000000 08 65 12 0f 08 fb 85 c4 a9 06 11 00 00 00 00 00 |.e..............| 14:15:05.523 DEBUG: App.EncodedDebug: EventIn: EncodedMessage: 00000010 80 38 40 12 0f 08 a7 88 c4 a9 06 11 66 66 66 66 |.8@.........ffff| 14:15:05.523 DEBUG: App.EncodedDebug: EventIn: EncodedMessage: 00000020 66 66 37 40 |ff7@|
See also ProtobufDecoder, ProtobufEncode, and Argument.
Get started with CDP Studio today
Let us help you take your great ideas and turn them into the products your customer will love.