7.2.3. Protobuf: Person

In the last section you learned how to send strings to an eCAL Topic. Using strings is great for simple data that has a textual representation. Quite often however your data will be more complex, so you need some kind of protocol that defines how your data is structured.

Our recommended way is to use Google protobuf to do that, because:

  • It solves the problem of how to serialize and de-serialize data for you

  • You get downward compatibility out of the box (if you follow the guidelines)

  • It is maintained by Google and the API is stable

  • The eCAL Monitor can display a reflection view of the data

Important

It is important to remember, that all your applications must agree on the data format. As protobuf messages are defined in .proto files, all of your applications should share the same files.

eCAL supports protobuf serialization natively for C++, C# and Python.

The usage of protobuf for data exchange in eCAL is very simple. You know already from the “String: Hello World” how to send and receive simple string data. The basic setup will be the same, but instead of using the string publisher, we will use the protobuf publisher and subscriber.

7.2.3.1. Person Protobuf

As the sender and receiver need the same .proto files, we place them in a separate directory next to the source directories for the sender and the receiver.

|fa-folder-open| Person Protobuf File
├─ |fa-file-alt| person.proto
│
├─ |fa-file-alt| animal.proto
│
└─ |fa-file-alt| house.proto

Let’s start with the protobuf/person.proto file!

As you can see, the person.proto file imports also other message definitions: animal.proto and house.proto. So we need them as well. The definitions are straight forward. For more information about protobuf, please refer to the detailed official documentation.

7.2.3.2. Person Publisher

The main differences to the string publisher are:

  • we need to include / import the protobuf specific publishers

  • also we need to include / import the compiled protobuf message definitions for the specific programming language

  • we need to utilize the protobuf message class Person instead of the string class

|fa-folder-open|
├─ |fa-folder-open| C++
│  └─ |fa-file-alt| person_send.cpp
│
├─ |fa-folder-open| C#
│  └─ |fa-file-alt| person_send_csharp.cs
│
├─ |fa-folder-open| Python
|  └─ |fa-file-alt| person_send.py
|
└─ |fa-folder-open| Python (legacy)
   └─ |fa-file-alt| person_send.py

7.2.3.3. Person Subscriber

For the subscriber the same changes apply as for the publisher.

|fa-folder-open|
├─ |fa-folder-open| C++
│  └─ |fa-file-alt| person_receive.cpp
│
├─ |fa-folder-open| C#
│  └─ |fa-file-alt| person_receive_csharp.cs
│
├─ |fa-folder-open| Python
|  └─ |fa-file-alt| person_receive.py
|
└─ |fa-folder-open| Python (legacy)
   └─ |fa-file-alt| person_receive.py

7.2.3.4. Person Dynamic Subscriber

Using eCAL and Protobuf, it is possible to receive data without knowing the structure of the incoming data in advance. Hence you can use a dynamic subscriber to receive Protobuf data, even if you do not have access to the corresponding .proto file. This is useful for generic applications, such as the eCAL Monitor, which can display all data types without knowing them in advance.

The dynamic Protobuf API is unfortunately only available for C++ and Python at the moment. C# does not have the capabilities for dynamic message support in Protocol Buffers at this time. Progress on this feature can be tracked in the following GitHub issue.

|fa-folder-open|
├─ |fa-folder-open| C++
│  └─ |fa-file-alt| person_receive.cpp
│
└─ |fa-folder-open| Python
   └─ |fa-file-alt| person_receive.py