7.2. Hello World with protobuf¶
Important
This tutorial will only work with eCAL 5.7.3 and upwards if you are using Windows. It will not work with older versions that were published as .msi installer (it missed some libraries).
Please switch to Ubuntu, if you are using an old eCAL Version.
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.
Of course, you can define your own protocol and pass the raw memory to eCAL (you would use the raw eCAL::CPublisher() to do that). Our recommended way however is to use Google protobuf, 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 nice 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 be compiled with the same files.
7.2.1. Protobuf sender¶
Let’s implement a small application, that lets the user input his name and send a message to an eCAL topic. 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:
├─proto_messages
│ └─hello_world.proto
├─protobuf_snd
└─protobuf_rec
Let’s start with the proto_messages/hello_world.proto
file!
1 2 3 4 5 6 7 8 9 10 | syntax = "proto3";
package proto_messages;
message HelloWorld
{
string name = 1;
uint32 id = 2;
string msg = 3;
}
|
Note
What is happening here?
Line 3 assigns a package name (this will appear as C++ namespace later).
Line 5-10 Creates a message “HelloWorld”, that holds the fields “name”, “id” and “msg”.
Now start implementing the actual sender application. Just as in the last section create the CMakeLists.txt
and main.cpp
in the protobuf_snd
directory and paste the following content:
CMakeLists.txt
:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
cmake_minimum_required(VERSION 3.0) set(CMAKE_FIND_PACKAGE_PREFER_CONFIG ON) project(protobuf_snd) set(CMAKE_CXX_STANDARD 14) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(eCAL REQUIRED) find_package(Protobuf REQUIRED) set(source_files main.cpp ) set(protobuf_files ${CMAKE_CURRENT_SOURCE_DIR}/../proto_messages/hello_world.proto ) add_executable(${PROJECT_NAME} ${source_files}) PROTOBUF_TARGET_CPP(${PROJECT_NAME} ${CMAKE_CURRENT_SOURCE_DIR}/../proto_messages/ ${protobuf_files}) target_link_libraries(${PROJECT_NAME} eCAL::core protobuf::libprotobuf )
Note
What is happening here?
Line 10 adds Protobuf as dependency
Line 16-18 Creates a list of .proto files. We only have one.
Line 22 Compiles the .proto file to a C++ header file (
hello_world.pb.h
). ThePROTOBUF_TARGET_CPP
function is a convenience function from eCAL. If you have already worked with Protobuf and CMake, you may be more familiar with the following code, which basically does the same thing:include_directories(${CMAKE_CURRENT_BINARY_DIR}) protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS ${protobuf_files}) add_executable(${PROJECT_NAME} ${source_files} ${PROTO_SRCS} ${PROTO_HDRS})
Line 26 links the executable against protobuf
main.cpp
:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
#include <ecal/ecal.h> #include <ecal/msg/protobuf/publisher.h> #include <iostream> #include <thread> #include "hello_world.pb.h" int main(int argc, char** argv) { // Initialize eCAL and create a protobuf publisher eCAL::Initialize(argc, argv, "Hello World Protobuf Publisher"); eCAL::protobuf::CPublisher<proto_messages::HelloWorld> publisher("hello_world_protobuf"); // Ask the user to input his name std::cout << "Please enter your name: "; std::string name; std::getline(std::cin, name); unsigned int id = 0; // Infinite loop (using eCAL::Ok() will enable us to gracefully shutdown the // Process from another application) while (eCAL::Ok()) { // Let the user input a message std::cout << "Type the message you want to send: "; std::string message; std::getline(std::cin, message); // Create a protobuf message object proto_messages::HelloWorld hello_world_message; hello_world_message.set_name(name); hello_world_message.set_msg (message); hello_world_message.set_id (id++); // Send the message publisher.Send(hello_world_message); std::cout << "Sent message!" << std::endl << std::endl; } // finalize eCAL API eCAL::Finalize(); }
Note
What is happening here?
Line 2: This time, we include the protobuf publisher.
Line7 includes the generated C++ file from the
hello_world.proto
Line 13 creates a protobuf publisher instance. Note that it is templated to
proto_messages::HelloWorld
, so if you would want to send different messages to different topics, you would create one publisher instance per topic. Sending different messages to the same topic is a bad idea and will break the de-serialization.Line 32-36 creates the message as protobuf object and sets the fields in it.
Line 38 sends the protobuf object out to the topic.
Again, you can already watch the sender doing its work by inspecting the topic in the eCAL Monitor! (Compile the application just as in the last section)

Important
The eCAL Monitor will not start listening to messages, until you open the reflection window. So, you will only see messages that were sent after you have opened the window.
7.2.2. Protobuf receiver¶
CMakeLists.txt
:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
cmake_minimum_required(VERSION 3.0) set(CMAKE_FIND_PACKAGE_PREFER_CONFIG ON) project(protobuf_rec) set(CMAKE_CXX_STANDARD 14) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(eCAL REQUIRED) find_package(Protobuf REQUIRED) set(source_files main.cpp ) set(protobuf_files ${CMAKE_CURRENT_SOURCE_DIR}/../proto_messages/hello_world.proto ) add_executable(${PROJECT_NAME} ${source_files}) PROTOBUF_TARGET_CPP(${PROJECT_NAME} ${CMAKE_CURRENT_SOURCE_DIR}/../proto_messages/ ${protobuf_files}) target_link_libraries(${PROJECT_NAME} eCAL::core protobuf::libprotobuf )
main.cpp
:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
#include <ecal/ecal.h> #include <ecal/msg/protobuf/subscriber.h> #include <iostream> #include <thread> #include "hello_world.pb.h" void HelloWorldCallback(const proto_messages::HelloWorld& hello_world_msg) { std::cout << hello_world_msg.name() << " sent a message with ID " << hello_world_msg.id() << ":" << std::endl << hello_world_msg.msg() << std::endl << std::endl; } int main(int argc, char** argv) { // Initialize eCAL and create a protobuf subscriber eCAL::Initialize(argc, argv, "Hello World Protobuf Subscriber"); eCAL::protobuf::CSubscriber<proto_messages::HelloWorld> subscriber("hello_world_protobuf"); // Set the Callback subscriber.AddReceiveCallback(std::bind(&HelloWorldCallback, std::placeholders::_2)); // Just don't exit while (eCAL::Ok()) { std::this_thread::sleep_for(std::chrono::milliseconds(500)); } // finalize eCAL API eCAL::Finalize(); }
Note
What is happening here?
Line 9 is our subscriber callback (you have already seen a callback in the last Hello World Tutorial). This time however it receives a protobuf object. Line 11-13 use the handy protobuf accessor methods to print the data to the terminal.
Line 20 Creates an eCAL protobuf subscriber. Just like the publisher, it is templated to the
proto_messages::HelloWorld
message.Line 23 Sets the callback, so eCAL can call it whenever a new message is received.
Now compile and start both the sender and the receiver application and send some messages!

Congratulations, you have completed the Getting Started chapter! Now go ahead and use eCAL in your real-world scenario.
If you experience issues, you can create a GitHub issue, to get help.
7.2.3. Files¶
├─ proto_messages │ └─hello_world.proto
│ ├─ protobuf_snd │ ├─CMakeLists.txt
│ └─main.cpp
│ └─ protobuf_rec ├─CMakeLists.txt
└─main.cpp