Quick start¶
eProsima Micro XRCE-DDS provides a C API which allows the creation of eProsima Micro XRCE-DDS Clients that can either publish/subscribe to topics from the DDS Global Data Space, or act as client-service applications following a request/reply pattern.
In this section, we will guide the user through the deployment of two out-of-the-box examples. In the first one, an eProsima Micro XRCE-DDS Agent bridges two eProsima Micro XRCE-DDS Clients publishing and subscribing to the DDS world. The second example shows instead the deployment of a client-service application using the Requester and Replier entities, also put into communication via an eProsima Micro XRCE-DDS Agent.
The section is organized as follows:
Running an Agent¶
First of all, install the Agent as explained in the Installing the Agent standalone section. On Linux, this would be:
$ git clone https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
$ cd Micro-XRCE-DDS-Agent
$ mkdir build && cd build
$ cmake ..
$ make
$ sudo make install
After having installed the Agent system-wide, it’s possible to launch it.
For this example, the Client-Agent communication will be done through UDP, using the port 2019
and with the XML creation mode, which is the default mode for creating entities:
$ cd /usr/local/bin && MicroXRCEAgent udp4 -p 2019
Running a Publisher-Subscriber example¶
In this section, we guide the user through the configuration and deployment of a simple publish/subscribe example where the communication is mediated by the Agent created above.
Before considering the publisher and subscriber examples, it is useful to briefly summarize how the Publisher and Subscriber entities work, as well as to list the functions related to both entities.
- Publisher
The Publisher will be associated with a Topic and will handle a DDS publisher that publishes topics.
To create a Publisher entity, the
uxr_buffer_create_publisher_xml
oruxr_buffer_create_publisher_ref
shall be used. Once created, topics can be published throughuxr_prepare_output_stream
.- Subscriber
The Subscriber will be associated with a Topic and will handle a DDS subscriber that receives topics.
To create a Subscriber entity, the
uxr_buffer_create_subscriber_xml
oruxr_buffer_create_subscriber_ref
shall be used. Topics can be received by sending a data request to the Agent withuxr_buffer_request_data
, and through the on_topic callback which shall be set by theuxr_set_topic_callback
. This callback has a parameter request_id which identifies the data request.
All the files and the code used in this example can be found in the Micro-XRCE-DDS-Client/examples/PublishHelloWorld and Micro-XRCE-DDS-Client/examples/SubscribeHelloWorld folders.
Publisher application¶
Let’s now install the Client locally, and with the -DUCLIENT_BUILD_EXAMPLES=ON
flag enabled, so as
to activate the compilation of the examples. On Linux, this implies running the following:
$ git clone https://github.com/eProsima/Micro-XRCE-DDS-Client.git
$ cd Micro-XRCE-DDS-Client
$ mkdir build && cd build
$ cmake .. -DUCLIENT_BUILD_EXAMPLES=ON
$ make
At this point, it’s possible to launch the PublishHelloWorldClient
executable
located in the folder Micro-XRCE-DDS-Client/build/examples/PublishHelloWorld
, which’ll make
the Client publish in the DDS World the HelloWorld
topic
(take a look at the IDL defining this topic in the file
Micro-XRCE-DDS-Client/examples/PublishHelloWorld/HelloWorld.idl
).
$ examples/PublishHelloWorld/PublishHelloWorldClient 127.0.0.1 2019
The source code of the PublishHelloWorldClient
can be found in
Micro-XRCE-DDS-Client/examples/PublishHelloWorld/main.c
.
Subscriber application¶
After having executed the publisher app, we can launch the SubscribeHelloWorldClient
executable,
which is located in the folder Micro-XRCE-DDS-Client/build/examples/SubscribeHelloWorld
, which’ll make
this Client subscribe to the same HelloWorld
topic from the DDS World.
$ examples/SubscriberHelloWorld/SubscribeHelloWorldClient 127.0.0.1 2019
The source code of the SubscribeHelloWorldClient
can be found in
Micro-XRCE-DDS-Client/examples/SubscribeHelloWorld/main.c
.
At this point, the subscriber will receive the topics that are being sent by the publisher.
In order to see the messages from the DDS Global Data Space point of view, use the eProsima Fast DDS HelloWorld example running a subscriber. Find more information on how to do so at Fast DDS HelloWorld.
Running a Requester/Replier example¶
This section shows an example of a client-service application using the Requester and Replier entities. This application has two ends, the client (RequestAdder) and the service (ReplyAdder). On the one hand, the client is in charge of sending requests which contain two integers, as well as receiving the responses from the service. On the other hand, the service is in charge of receiving the requests from the client, summing the two integers, and finally of sending the response to the client.
Before considering the client and service examples, it is useful to briefly summarize how the Requester and Replier entities work, as well as to list the functions related to both entities.
- Requester
The Requester entity is composed of a Publisher and a Subscriber associated with a RequestTopic and a ReplyTopic respectively. The Publisher is in charge of sending the request, while the Susbscriber receives the replies.
To create a Requester entity, the
uxr_buffer_create_requester_xml
oruxr_buffer_create_requester_ref
shall be used. Once created, requests can be sent throughuxr_buffer_request
. Replies can be received by sending a data request to the Agent withuxr_buffer_request_data
, and through the on_reply callback which shall be set by theuxr_set_reply_callback
. This callback has a parameterreply_id
which corresponds to the identifier returned by theuxr_buffer_request
call.- Replier
The Reply entity is a mirror of the Requester, that is, it contains a Publisher and a Subscriber as well, but the topic association is reversed, as the Publisher is associated with the ReplyTopic and the Subscriber to the RequestTopic. In this case, the Subscriber is in charge of receiving the request from the Requester, while the Publisher sends the replies.
To create a Replier entity, the
uxr_buffer_create_replier_xml
oruxr_buffer_create_replier_ref
shall be used. Once created, replies can be sent throughuxr_buffer_reply
. Requests can be received by sending a data request to the Agent withuxr_buffer_request_data
, and through the on_request callback which shall be set by theuxr_set_request_callback
. This callback has a parameter sample_id which identifies the request and should be used in theuxr_buffer_reply
.
All the files and the code used in this example can be found in the Micro-XRCE-DDS-Client/examples/RequestAdder and Micro-XRCE-DDS-Client/examples/ReplyAdder folders.
Requester application¶
Let’s now install the Client locally, and with the -DUCLIENT_BUILD_EXAMPLES=ON
flag enabled, so as
to activate the compilation of the examples. On Linux, this implies running the following:
$ git clone https://github.com/eProsima/Micro-XRCE-DDS-Client.git
$ cd Micro-XRCE-DDS-Client
$ mkdir build && cd build
$ cmake .. -DUCLIENT_BUILD_EXAMPLES=ON
$ make
At this point, it’s possible to launch the RequestAdder
executable
located in the folder Micro-XRCE-DDS-Client/build/examples/RequestAdder
, which’ll make
the Client send two integers as a request, and receive the sum of both integers as a response.
$ examples/RequestAdder/RequestAdder 127.0.0.1 2019
The source code of the RequestAdder
can be found in
Micro-XRCE-DDS-Client/examples/RequestAdder/main.c
.
Replier application¶
After having executed the Requester app, we can launch the ReplyAdder
executable,
which is located in the folder Micro-XRCE-DDS-Client/build/examples/ReplyAdder
, which’ll make
this Client receive requests composed by two integers, sum both numbers, and finally send the response.
$ examples/ReplyAdder/ReplyAdder 127.0.0.1 2019
The source code of the ReplyAdder
can be found in
Micro-XRCE-DDS-Client/examples/ReplyAdder/main.c
.
At this point, the Requester and the Replier will start communicating.
Learn More¶
Find a detailed explanation of the code used to write and run these applications in the Getting started section.
Find other relevant material:
- eProsima Fast DDS: eProsima Fast DDS
- To learn how to install eProsima Micro XRCE-DDS read: Installation
- To learn more about eProsima Micro XRCE-DDS read: Overview
- To learn more about eProsima Micro XRCE-DDS Gen read: eProsima Micro XRCE-DDS Gen