7.1.2. 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 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 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.1.2.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.
Person Protobuf File ├─person.proto│ ├─animal.proto│ └─house.proto
Let’s start with the protobuf/person.proto file!
1syntax = "proto3";
2
3// import message definitions from different proto files
4import "animal.proto";
5import "house.proto";
6
7// assign a package name, that will appear as a namespace
8package pb.People;
9
10// create the message "Person" with
11// - base types like int32 and string
12// - individual defined enum SType
13// - imported message types
14message Person
15{
16 enum SType
17 {
18 MALE = 0;
19 FEMALE = 1;
20 }
21
22 int32 id = 1;
23 string name = 2;
24 SType stype = 3;
25 string email = 4;
26
27 Animal.Dog dog = 5;
28 Environment.House house = 6;
29}
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.
1syntax = "proto3";
2
3package pb.Animal;
4
5message Dog
6{
7 string name = 1;
8 string colour = 2;
9}
1syntax = "proto3";
2
3package pb.Environment;
4
5message House
6{
7 int32 rooms = 1;
8}
7.1.2.2. Person Publisher#
- The main differences to the string publisher are:
we need to include the protobuf publisher from
ecal/msg/protobuf/publisher.halso we need the compiled protobuf message header file
person.pb.hand include itwe need to utilize the protobuf message class
Personinstead of the string classstd::string
1// Including the eCAL convenience header
2#include <ecal/ecal.h>
3// In addition we include the msg protobuf publisher
4#include <ecal/msg/protobuf/publisher.h>
5
6#include <iostream>
7
8// Here we include the compiled protobuf header for the message "Person"
9#include "person.pb.h"
10
11int main()
12{
13 std::cout << "--------------------" << std::endl;
14 std::cout << " C++: PERSON SENDER" << std::endl;
15 std::cout << "--------------------" << std::endl;
16
17 /*
18 Initialize eCAL. You always have to initialize eCAL before using its API.
19 The name of our eCAL Process will be "person send".
20 This name will be visible in the eCAL Monitor, once the process is running.
21 */
22 eCAL::Initialize("person send");
23
24 /*
25 Print some eCAL version information.
26 */
27 std::cout << "eCAL " << eCAL::GetVersionString() << " (" << eCAL::GetVersionDateString() << ")" << "\n";
28
29 /*
30 Set the state for the program.
31 You can vary between different states like healthy, warning, critical ...
32 This can be used to communicate the application state to applications like eCAL Monitor/Sys.
33 */
34 eCAL::Process::SetState(eCAL::Process::eSeverity::healthy, eCAL::Process::eSeverityLevel::level1, "I feel good!");
35
36 /*
37 Now we create a new publisher that will publish the topic "person".
38 The data type is "pb.People.Person", generated from the protobuf definition.
39 */
40 eCAL::protobuf::CPublisher<pb::People::Person> publisher("person");
41
42 /*
43 Construct a message. The message is a protobuf struct that will be sent to the subscribers.
44 */
45 pb::People::Person person;
46 person.set_id(0);
47 person.set_name("Max");
48 person.set_stype(pb::People::Person_SType_MALE);
49 person.set_email("max@mail.net");
50 person.mutable_dog()->set_name("Brandy");
51 person.mutable_house()->set_rooms(4);
52
53 /*
54 Creating an infinite publish-loop.
55 eCAL Supports a stop signal; when an eCAL Process is stopped, eCAL_Ok() will return false.
56 */
57 auto loop_count = 0;
58 while(eCAL::Ok())
59 {
60 /*
61 Change in each loop the content of the message to see a difference per message.
62 */
63 person.set_id(loop_count++);
64
65 /*
66 Send the message. The message is sent to all subscribers that are currently connected to the topic "person".
67 */
68 if (publisher.Send(person))
69 {
70 std::cout << "----------------------------------" << "\n";
71 std::cout << "Sent protobuf message in C++: " << "\n";
72 std::cout << "----------------------------------" << "\n";
73 std::cout << "person id : " << person.id() << "\n";
74 std::cout << "person name : " << person.name() << "\n";
75 std::cout << "person stype : " << person.stype() << "\n";
76 std::cout << "person email : " << person.email() << "\n";
77 std::cout << "dog.name : " << person.dog().name() << "\n";
78 std::cout << "house.rooms : " << person.house().rooms() << "\n";
79 std::cout << "----------------------------------" << "\n";
80 std::cout << "\n";
81 }
82 else
83 {
84 std::cout << "Failed to send Protobuf message in C++!" << "\n";
85 }
86
87 /*
88 Sleep for 500ms to send in a frequency of 2 hz.
89 */
90 eCAL::Process::SleepMS(500);
91 }
92
93 /*
94 Finalize eCAL. This will stop all eCAL processes and free all resources.
95 You should always finalize eCAL when you are done using it.
96 */
97 eCAL::Finalize();
98
99 return(0);
100}
1using System;
2// Include the eCAL API namespace
3using Eclipse.eCAL.Core;
4
5public class PersonSend
6{
7 static void Main()
8 {
9 Console.WriteLine("-------------------");
10 Console.WriteLine(" C#: PERSON SENDER");
11 Console.WriteLine("-------------------");
12
13 /*
14 Initialize eCAL. You always have to initialize eCAL before using its API.
15 The name of our eCAL Process will be "person send c#".
16 This name will be visible in the eCAL Monitor, once the process is running.
17 */
18 Core.Initialize("person send c#");
19
20 /*
21 Print version info.
22 */
23 Console.WriteLine(String.Format("eCAL {0} ({1})\n", Core.GetVersionString(), Core.GetVersionDateString()));
24
25 /*
26 Set the state for the program.
27 You can vary between different states like healthy, warning, critical ...
28 This can be used to communicate the application state to applications like eCAL Monitor/Sys.
29 */
30 Process.SetState(eProcessSeverity.Healthy, eProcessSeverityLevel.Level1, "I feel good!");
31
32 /*
33 Now we create a new publisher that will publish the topic "person".
34 The data type is "Pb.People.Person", generated from the protobuf definition.
35 */
36 var publisher = new ProtobufPublisher<Pb.People.Person>("person");
37
38 /*
39 Construct a message. The message is a protobuf struct that will be sent to the subscribers.
40 */
41 var person = new Pb.People.Person
42 {
43 Id = 0,
44 Email = "max@online.de",
45 Name = "Max",
46 Stype = Pb.People.Person.Types.SType.Female,
47 Dog = new Pb.Animal.Dog { Name = "Brandy" },
48 House = new Pb.Environment.House { Rooms = 4 }
49 };
50
51 /*
52 Creating an infinite publish-loop.
53 eCAL Supports a stop signal; when an eCAL Process is stopped, eCAL_Ok() will return false.
54 */
55 int loop_count = 0;
56 while (Core.Ok())
57 {
58 /*
59 Change in each loop the content of the message to see a difference per message.
60 */
61 person.Id = loop_count++;
62
63 /*
64 Send the message. The message is sent to all subscribers that are currently connected to the topic "person".
65 */
66 if (publisher.Send(person))
67 {
68 Console.WriteLine("----------------------------------");
69 Console.WriteLine("Sent protobuf message in C#: ");
70 Console.WriteLine("----------------------------------");
71 Console.WriteLine("person id : {0}", person.Id);
72 Console.WriteLine("person name : {0}", person.Name);
73 Console.WriteLine("person stype : {0}", person.Stype);
74 Console.WriteLine("person email : {0}", person.Email);
75 Console.WriteLine("dog.name : {0}", person.Dog.Name);
76 Console.WriteLine("house.rooms : {0}", person.House.Rooms);
77 Console.WriteLine("----------------------------------");
78 Console.WriteLine("");
79 }
80 else
81 {
82 Console.WriteLine("Sending protobuf message in C# failed!");
83 }
84
85 /*
86 Sleep for 500ms to send in a frequency of 2 hz.
87 */
88 System.Threading.Thread.Sleep(500);
89 }
90
91 /*
92 Cleanup. Dispose the publisher to free resources.
93 */
94 publisher.Dispose();
95
96 /*
97 Terminate eCAL. This will stop all eCAL processes and free all resources.
98 You should always terminate eCAL when you are done using it.
99 */
100 Core.Terminate();
101 }
102}
1import os
2import sys
3import time
4
5# import the eCAL core API
6import ecal.core.core as ecal_core
7# import the eCAL publisher API supporting protobuf
8from ecal.core.publisher import ProtoPublisher
9
10sys.path.insert(1, os.path.join(sys.path[0], '../_protobuf'))
11# import the compiled protobuf message classes
12import person_pb2
13
14def main():
15 print("-----------------------")
16 print(" Python: PERSON SENDER")
17 print("-----------------------")
18
19 # Initialize eCAL. You always have to initialize eCAL before using it.
20 # The name of our eCAL Process will be "person send python".
21 # This name will be visible in the eCAL Monitor, once the process is running.
22 ecal_core.initialize("person send python")
23
24 # Print used eCAL version and date
25 print("eCAL {} ({})\n".format(ecal_core.getversion(), ecal_core.getdate()))
26
27 # Set the state for the program.
28 # You can vary between different states like healthy, warning, critical ...
29 # This can be used to communicate the application state to applications like eCAL Monitor/Sys.
30 ecal_core.set_process_state(1, 1, "I feel good!")
31
32 # Creating the eCAL Publisher. An eCAL Process can create multiple publishers (and subscribers).
33 # The topic we are going to publish is called "person".
34 # Furthermore, we want to tell the publisher that we want to use the protobuf message class "Person" from the file "person.proto".
35 pub = ProtoPublisher("person", person_pb2.Person)
36
37 # Create a new message object of type "Person" and fill it with some data.
38 person = person_pb2.Person()
39 person.name = "Max"
40 person.stype = person_pb2.Person.MALE
41 person.email = "max@mail.net"
42 person.dog.name = "Brandy"
43 person.house.rooms = 4
44
45 # Creating an inifite publish-loop.
46 # eCAL Supports a stop signal; when an eCAL Process is stopped, eCAL::Ok() will return false.
47 loop_count = 0
48 while ecal_core.ok():
49
50 # Change something in the message so we can see that the message is changing, e.g. in eCAL Monitor.
51 loop_count = loop_count + 1
52 person.id = loop_count
53
54 # Send the content to other eCAL Processes that have subscribed to the topic "person".
55 pub.send(person)
56 print("Sending person {}".format(person.id))
57
58 # Sleep for 500 ms so we send with a frequency of 2 Hz.
59 time.sleep(0.5)
60
61 # Finalize eCAL.
62 # You should always do that before your application exits.
63 ecal_core.finalize()
64
65if __name__ == "__main__":
66 main()
7.1.2.3. Person Publisher Files#
├─ C++ │ └─person_send.cpp│ ├─ C# │ └─person_send_csharp.cs│ └─ Python └─person_send.py
7.1.2.4. Person Subscriber#
For the subscriber the same changes apply as for the publisher.
1// Including the eCAL convenience header
2#include <ecal/ecal.h>
3// In addition we include the msg protobuf publisher
4#include <ecal/msg/protobuf/subscriber.h>
5
6#include <iostream>
7
8#include "person.pb.h"
9
10/*
11 Here we create the subscriber callback function that is called everytime,
12 when a new message arrived from a publisher.
13*/
14void OnPerson(const eCAL::STopicId& topic_id_, const pb::People::Person& person_, const long long time_, const long long clock_)
15{
16 std::cout << "------------------------------------------" << "\n";
17 std::cout << " Received Protobuf message in C++ " << "\n";
18 std::cout << "------------------------------------------" << "\n";
19 std::cout << " topic name : " << topic_id_.topic_name << "\n";
20 std::cout << " topic time : " << time_ << "\n";
21 std::cout << " topic clock : " << clock_ << "\n";
22 std::cout << "" << "\n";
23 std::cout << " Content of message type \"" << person_.GetTypeName() << "\"" << "\n";
24 std::cout << "------------------------------------------" << "\n";
25 std::cout << " id : " << person_.id() << "\n";
26 std::cout << " name : " << person_.name() << "\n";
27 std::cout << " stype : " << person_.stype() << "\n";
28 std::cout << " email : " << person_.email() << "\n";
29 std::cout << " dog.name : " << person_.dog().name() << "\n";
30 std::cout << " house.rooms : " << person_.house().rooms() << "\n";
31 std::cout << "------------------------------------------" << "\n";
32 std::cout << "\n";
33}
34
35int main()
36{
37 std::cout << "----------------------" << std::endl;
38 std::cout << " C++: PERSON RECEIVER" << std::endl;
39 std::cout << "----------------------" << std::endl;
40
41 /*
42 Initialize eCAL. You always have to initialize eCAL before using its API.
43 The name of our eCAL Process will be "person receive".
44 This name will be visible in the eCAL Monitor, once the process is running.
45 */
46 eCAL::Initialize("person receive");
47
48 /*
49 Print some eCAL version information.
50 */
51 std::cout << "eCAL " << eCAL::GetVersionString() << " (" << eCAL::GetVersionDateString() << ")" << "\n";
52
53 /*
54 Set the state for the program.
55 You can vary between different states like healthy, warning, critical ...
56 This can be used to communicate the application state to applications like eCAL Monitor/Sys.
57 */
58 eCAL::Process::SetState(eCAL::Process::eSeverity::healthy, eCAL::Process::eSeverityLevel::level1, "I feel good!");
59
60 /*
61 Creating the eCAL Subscriber. An eCAL Process can create multiple subscribers (and publishers).
62 The topic we are going to receive is called "person".
63 The data type is "Pb.People.Person", generated from the protobuf definition.
64 */
65 eCAL::protobuf::CSubscriber<pb::People::Person> subscriber("person");
66
67 /*
68 Create and register a receive callback. The callback will be called whenever a new message is received.
69 */
70 subscriber.SetReceiveCallback(&OnPerson);
71
72 /*
73 Creating an infinite loop.
74 eCAL Supports a stop signal; when an eCAL Process is stopped, eCAL::Ok() will return false.
75 */
76 while(eCAL::Ok())
77 {
78 /*
79 Sleep for 500ms to avoid busy waiting.
80 */
81 eCAL::Process::SleepMS(500);
82 }
83
84 /*
85 Finalize eCAL. This will stop all eCAL processes and free all resources.
86 You should always finalize eCAL before exiting your application.
87 */
88 eCAL::Finalize();
89
90 return(0);
91}
1using System;
2// include ecal core namespace
3using Eclipse.eCAL.Core;
4
5public class PersonReceive
6{
7 public static void Main()
8 {
9 Console.WriteLine("---------------------");
10 Console.WriteLine(" C#: PERSON RECEIVER");
11 Console.WriteLine("---------------------");
12
13 /*
14 Initialize eCAL. You always have to initialize eCAL before using its API.
15 The name of our eCAL Process will be "person receive c#".
16 This name will be visible in the eCAL Monitor, once the process is running.
17 */
18 Core.Initialize("person receive c#");
19
20 /*
21 Print version info.
22 */
23 Console.WriteLine(String.Format("eCAL {0} ({1})\n", Core.GetVersionString(), Core.GetVersionDateString()));
24
25 /*
26 Set the state for the program.
27 You can vary between different states like healthy, warning, critical ...
28 This can be used to communicate the application state to applications like eCAL Monitor/Sys.
29 */
30 Process.SetState(eProcessSeverity.Healthy, eProcessSeverityLevel.Level1, "I feel good!");
31
32 /*
33 Creating the eCAL Subscriber. An eCAL Process can create multiple subscribers (and publishers).
34 The topic we are going to receive is called "person".
35 The data type is "Pb.People.Person", generated from the protobuf definition.
36 */
37 var subscriber = new ProtobufSubscriber<Pb.People.Person>("person");
38
39 /*
40 Create and register a receive callback. The callback will be called whenever a new message is received.
41 */
42 subscriber.SetReceiveCallback((topicId, dataTypeInfo, person) =>
43 {
44 Console.WriteLine("------------------------------------------");
45 Console.WriteLine(" Received Protobuf message in C#");
46 Console.WriteLine("------------------------------------------");
47 Console.WriteLine(" topic name : {0}", topicId.TopicName);
48 Console.WriteLine(" topic time : n/a");
49 Console.WriteLine(" topic clock : n/a");
50 Console.WriteLine("");
51 Console.WriteLine(" Content of message type \"{0}\"", person.Message.GetType());
52 Console.WriteLine("------------------------------------------");
53 Console.WriteLine(" id : {0}", person.Message.Id);
54 Console.WriteLine(" name : {0}", person.Message.Name);
55 Console.WriteLine(" stype : {0}", person.Message.Stype);
56 Console.WriteLine(" email : {0}", person.Message.Email);
57 Console.WriteLine(" dog.name : {0}", person.Message.Dog.Name);
58 Console.WriteLine(" house.rooms : {0}", person.Message.House.Rooms);
59 Console.WriteLine("------------------------------------------");
60 Console.WriteLine("");
61 });
62
63 /*
64 Creating an infinite loop.
65 eCAL Supports a stop signal; when an eCAL Process is stopped, eCAL::Ok() will return false.
66 */
67 while (Core.Ok())
68 {
69 /*
70 Sleep for 500ms to avoid busy waiting.
71 */
72 System.Threading.Thread.Sleep(500);
73 }
74
75 /*
76 Cleanup. Dispose the subscriber to free resources.
77 */
78 subscriber.Dispose();
79
80 /*
81 Terminate eCAL. This will stop all eCAL processes and free all resources.
82 You should always terminate eCAL before exiting your application.
83 */
84 Core.Terminate();
85 }
86}
1import os
2import sys
3import time
4# import the eCAL core API
5import ecal.core.core as ecal_core
6# import the eCAL subscriber API
7from ecal.core.subscriber import ProtoSubscriber
8
9sys.path.insert(1, os.path.join(sys.path[0], '../_protobuf'))
10# import the protobuf generated classes
11import person_pb2
12
13# Create here the eCAL receive callback. This will be called whenever a new message is received.
14def callback(topic_name, person, time):
15 print("")
16 print("Received person ..")
17 print("person id : {}".format(person.id))
18 print("person name : {}".format(person.name))
19 print("person stype : {}".format(person.stype))
20 print("person email : {}".format(person.email))
21 print("dog.name : {}".format(person.dog.name))
22 print("house.rooms : {}".format(person.house.rooms))
23
24def main():
25 print("-------------------------")
26 print(" Python: PERSON RECEIVER")
27 print("-------------------------")
28
29 # Initialize eCAL. You always have to initialize eCAL before using it.
30 # The name of our eCAL Process will be "person receive python".
31 # This name will be visible in the eCAL Monitor, once the process is running.
32 ecal_core.initialize("person receive python")
33
34 # Print used eCAL version and date
35 print("eCAL {} ({})\n".format(ecal_core.getversion(), ecal_core.getdate()))
36
37 # Set the state for the program.
38 # You can vary between different states like healthy, warning, critical ...
39 # This can be used to communicate the application state to applications like eCAL Monitor/Sys.
40 ecal_core.set_process_state(1, 1, "I feel good!")
41
42 # Creating the eCAL Subscriber. An eCAL Process can create multiple subscribers (and publishers).
43 # The topic we are going to receive is called "person".
44 # The topic type is specified by the protobuf message class.
45 sub = ProtoSubscriber("person", person_pb2.Person)
46
47 # Register the callback with the subscriber so it can be called.
48 # The callback will be called whenever a new message is received.
49 sub.set_callback(callback)
50
51 # Creating an infinite loop.
52 # eCAL Supports a stop signal; when an eCAL Process is stopped, eCAL::Ok() will return false.
53 while ecal_core.ok():
54 # Sleep for 500ms to avoid busy waiting.
55 # You can use eCAL::Process::SleepMS() to sleep in milliseconds.
56 time.sleep(0.5)
57
58 # Finalize eCAL.
59 # You should always do that before your application exits.
60 ecal_core.finalize()
61
62if __name__ == "__main__":
63 main()
7.1.2.5. Person Subscriber Files#
├─ C++ │ └─person_receive.cpp│ ├─ C# │ └─person_receive_csharp.cs│ └─ Python └─person_receive.py