ProtobufDecoder
ProtobufDecoder
The ProtobufDecoder is a sequencer block, that allows to decode input event data from Protocol Buffers message encoding to output events with decoded data.
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 |
|---|---|---|
| Decode | Predefined input event | Invokes Protocol Buffers message decoding. The event should contain EncodedMessage argument with a message to decode. |
| Protocol Buffers repeated field name | Any number of user-configurable output events for repeated fields | Repeated field to decode from the input message and send its elements one by one via this event (before Decoded event will be emitted). |
| Decoded | Predefined output event | Will be emitted on Decode event and contains values of decoded message fields as arguments, that are attached to the event via the Data property. Data is pre-configured to send the decoded message out in the EncodedMessage argument as this is best suited when you need to forward the event to subsequent ProtobufEncoder block for Protocol Buffers sub-element parse. But Data can be altered to send the decoded message in the other (used added) arguments. |
Arguments
| Name | Appearance | Description |
|---|---|---|
| EncodedMessage | Predefined input argument | The Protocol Buffers encoded message (binary string). Is expected to be included with Decode event. |
| Protocol Buffers message field name to decode | Any number of user-configurable output arguments | The Protocol Buffers message field named like this argument will be decoded and sent as the argument with output 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 Decode 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 output events when repeated field elements are Protocol Buffers encoded sub-messages.
Example
The following block diagram shows how to cascade two ProtobufDecoder blocks to decode 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; }
ProtobufDecoder has argument id added, to instruct the block to decode this field out from incoming message and send it out with Decoded event. Also by adding an output event named measurements to the first ProtobufDecoder, a repeated field named measurements will also be decoded from the input message and all its elements will be emitted with the measurements event to the cascaded ProtobufDecoder1. ProtobufDecoder1 has arguments temp and humidity added, to instruct the block to decode these fields out from incoming message and assign their values as argument values emitted together with Decoded event.
Both ProtobufDecoder's Proto attributes were set to the message definition given above. The ProtobufDecoder Message attribute was set to SensorTempSamples and the ProtobufDecoder1 Message attribute was set to TempSample.
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 decoding 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):
15:58:30.123 DEBUG: App.EncodedInputDebug: EventIn: EncodedMessage: 00000000 08 65 12 0f 08 fb 85 c4 a9 06 11 00 00 00 00 00 |.e..............| 15:58:30.123 DEBUG: App.EncodedInputDebug: EventIn: EncodedMessage: 00000010 80 38 40 12 0f 08 a7 88 c4 a9 06 11 66 66 66 66 |.8@.........ffff| 15:58:30.123 DEBUG: App.EncodedInputDebug: EventIn: EncodedMessage: 00000020 66 66 37 40 |ff7@| 15:58:30.123 DEBUG: App.RepeatedElementDebug: EventIn: EncodedMessage: 00000000 08 fb 85 c4 a9 06 11 00 00 00 00 00 80 38 40 |.............8@| 15:58:30.123 DEBUG: App.RepeatedElementDebug: EventIn: EncodedMessage: 00000000 08 a7 88 c4 a9 06 11 66 66 66 66 66 66 37 40 |.......ffffff7@| 15:58:30.123 DEBUG: App.DecodedMessageDebug: EventIn: Data arguments: id=101 15:58:30.123 DEBUG: App.DecodeMeasurementDebug: EventIn: Data arguments: timestamp=1697710843;temperature=24.5 15:58:30.123 DEBUG: App.DecodeMeasurementDebug: EventIn: Data arguments: timestamp=1697711143;temperature=23.4
See also ProtobufEncoder, ProtobufDecode, 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.