Next Tutorial: Services Previous Tutorial: Nodes and Topics
Overview
In this tutorial, we are going to create two nodes that are going to communicate via messages. One node will be a publisher that generates the information, whereas the other node will be the subscriber consuming the information. Our nodes will be running on different processes within the same machine.
Publisher
Download the publisher.cc file within the ign_transport_tutorial folder and open it with your favorite editor:
Walkthrough
The line #include <ignition/transport.hh> contains all the Ignition Transport headers for using the transport library.
The next line includes the generated protobuf code that we are going to use for our messages. We are going to publish StringMsg type protobuf messages.
First of all we declare a Node that will offer some of the transport functionality. In our case, we are interested in publishing topic updates, so the first step is to announce our topic name and its type. Once a topic name is advertised, we can start publishing periodic messages using the publisher object.
In this section of the code we create a protobuf message and fill it with content. Next, we iterate in a loop that publishes one message every second. The method Publish() sends a message to all the subscribers.
Subscriber
Download the subscriber.cc file into the ign_transport_tutorial folder and open it with your favorite editor:
Walkthrough
We need to register a function callback that will execute every time we receive a new topic update. The signature of the callback is always similar to the one shown in this example with the only exception of the protobuf message type. You should create a function callback with the appropriate protobuf type depending on the type of the topic advertised. In our case, we know that topic /foo will contain a Protobuf StringMsg type.
After the node creation, the method Subscribe() allows you to subscribe to a given topic name by specifying your subscription callback function.
If you don't have any other tasks to do besides waiting for incoming messages, you can use the call waitForShutdown() that will block your current thread until you hit CTRL-C. Note that this function captures the SIGINT and SIGTERM signals.
Building the code
Download the CMakeLists.txt file within the ign_transport_tutorial folder.
Once you have all your files, go ahead and create a build/ directory within the ign_transport_tutorial directory.
Run cmake and build the code.
Running the examples
Open two new terminals and from your build/ directory run the executables.
From terminal 1:
From terminal 2:
In your subscriber terminal, you should expect an output similar to this one, showing that your subscriber is receiving the topic updates:
Advertise Options
We can specify some options before we publish the messages. One such option is to specify the number of messages published per topic per second. It is optional to use but it can be handy in situations like when we want to control the rate of messages published per topic.
We can declare the throttling option using the following code :
Walkthrough
In this section of code, we declare an AdvertiseMessageOptions object and use it to pass message rate as an argument to SetMsgsPerSec() method. In our case, the object name is opts and the message rate specified is 1 msg/sec.
Next, we advertise the topic with message throttling enabled. To do it, we pass opts as an argument to the Advertise() method.
Subscribe Options
A similar option is also available for the Subscriber node which enables it to control the rate of incoming messages from a specific topic. While subscribing to a topic, we can use this option to control the number of messages received per second from that particular topic.
We can declare the throttling option using the following code :
Walkthrough
In this section of code, we declare a SubscribeOptions object and use it to pass message rate as an argument to the SetMsgsPerSec() method. In our case, the object name is opts and the message rate specified is 1 msg/sec. Then, we subscribe to the topic using the Subscribe() method with opts passed as an argument to it.
Generic subscribers
As you have seen in the examples so far, the callbacks used by the subscribers contain a specific protobuf parameter, such as ignition::msgs::StringMsg. As the name of this section suggests, it is also possible to create a generic subscriber callback that can receive messages of different types. This use case might be interesting if you are building a bridge between Ignition Transport and another protocol or if you want to just print the content of a generic protobuf message using DebugString(), among other use cases.
Download the subscriber_generic.cc file within the ign_transport_tutorial folder and open it with your favorite editor:
Walkthrough
Here, we use the generic callback function signature. Note the use of google::protobuf::Message as the message type in the subscription callback function cb(). It enables us to receive topic updates with different message types, such as Int32 or String from the subscribed topic. Furthermore, we don't need to worry about the type of the topic advertised while specifying the callback function. The parameter ignition::transport::MessageInfo &_info provides some information about the message received (e.g.: the topic name).
Similar to the previous examples, we use the Subscribe() function to subscribe to a given topic name by specifying the callback function. In our example, the topic name subscribed is /foo.
Follow the next instructions to compile and run the generic subscriber example:
Run cmake and build the example:
From terminal 1:
From terminal 2:
Using custom Protobuf messages
We use Ignition Msgs in most of our examples and tests. This decision was made just for convenience but Ignition Transport supports the use of Protobuf messages directly. The most common problem with custom Protobuf messages is often the integration of the message generation into the build system of your project. Next, you can find an example of a publisher and subscriber using a custom Protobuf message integrated with CMake.
Download the publisher_custom_msg.cc and the subscriber_custom_msg.cc files within the ign_transport_tutorial. Then, create a msgs folder and download the stringmsg.proto and the CMakeLists.txt files within the msgs folder. Finally, we'll need the main CMakeLists.txt file. You should have this file from the previous examples. Otherwise, download and place it within the ign_transport_tutorial folder.
Walkthrough
There's nothing new to show in the publisher_custom_msg.cc or subscriber_custom_msg.cc besides the use of your custom Protobuf message instead of Ignition Msgs. The only relevant parts are in the CMakeLists.txt files.
This is how we find the Protobuf CMake config file, to make sure that the macro for Protobuf message generation is available. We also let CMake know that there is a new subdirectory to inspect containing our custom messages.
In the previous snippet we can see how the binaries are generated. The relevant part is to add a new dependency. We're telling CMake that these two binaries depend on the protobuf_compilation target. This will trigger the recompilation of the binaries if there is any change in our Protobuf messages. Also, we have to link our binaries with the generated Protobuf messages. The list of generated messages are contained in the ${PROTO_SRC} variable. Finally, this is the content of the msgs/CMakeLists.txt file:
The macro PROTOBUF_GENERATE_CPP will use protoc to generate the .pb.h and .pb.cc files from your .proto files. Follow the next instructions to compile and run the generic subscriber example:
Run cmake and build the example:
From terminal 1:
From terminal 2:
Topic remapping
It's possible to set some global node options that will affect both publishers and subscribers. One of these options is topic remapping. A topic remap consists of a pair of topic names. The first name is the original topic name to be replaced. The second name is the new topic name to use instead. As an example, imagine that you recorded a collection of messages published over topic /foo. Maybe in the future, you want to play back the log file but remapping the topic /foo to /bar. This way, all messages will be published over the /bar topic without having to modify the publisher and create a new log.
We can declare the topic remapping option using the following code:
You can modify any of the publisher examples to add this option.
From terminal 1:
From terminal 2 (requires Ignition Tools):
And you should receive all the messages coming in terminal 2.
The command ign log playback also supports the notion of topic remapping. Run ign log playback -h in your terminal for further details (requires Ignition Tools).