eProsima Shapes Demo¶

eProsima Shapes Demo is an application in which Publishers and Subscribers are shapes of different colors and sizes moving on a board. Each shape refers to its own topic: Square, Triangle or Circle. A single instance of the eProsima Shapes Demo can publish on or subscribe to several topics at a time.

It demonstrates the capabilities of eProsima Fast DDS or as a proof of interoperability with other RTPS-compliant implementations.

Windows installation from binaries¶

To install eProsima Shapes Demo from binaries just go to the eProsima website and download the desired version of eProsima Shapes Demo. Download links can be found by following the link below.

https://www.eprosima.com/index.php/products-all/eprosima-shapes-demo

After downloading, unzip the content in the directory of preference and execute the file ShapesDemo.exe located in the bin directory.

Linux installation from sources¶

For simplicity, the eProsima Shapes Demo installation manual follows the Colcon installation, since eProsima Fast DDS and Fast CDR dependencies are downloaded and installed at the same time that eProsima Shapes Demo is built. However, the user must assure that Qt 5 is installed. On Ubuntu Jammy (22.04) installations, Qt 5 development packages are distributed by Canonical as an APT package and can be downloaded by running the following on a terminal:

apt update
apt install -y qtbase5-dev

Table of Contents

Colcon installation
ROS 2 features compilation

Colcon installation¶

To install eProsima Shapes Demo using colcon, please follow the steps below:

Install the eProsima Fast DDS dependencies and verify that the system meets the installation requirements. The complete list of requirements and dependencies can be found in the Fast DDS Linux Installation Manual. Specifically, follow the steps outlined in sections Requirements and Dependencies.
Install the ROS 2 development tools (Colcon and Vcstool) by executing the following command:
```
pip install -U colcon-common-extensions vcstool
```
Note

If this fails due to an Environment Error, add the --user flag to the pip installation command.

Create a ShapesDemo directory and download the repos file that will be used to install eProsima Shapes Demo and its dependencies:

mkdir -p ShapesDemo/src && cd ShapesDemo
wget https://raw.githubusercontent.com/eProsima/ShapesDemo/master/shapes-demo.repos
vcs import src < shapes-demo.repos

Build the packages:
```
colcon build
```
Link the application executable to make it accessible from the current directory:
```
source install/setup.bash
```
Run eProsima Shapes Demo:
```
ShapesDemo
```

ROS 2 features compilation¶

By default eProsima Shapes Demo can be built and used on a ROS 2 installation as long as an installation of Fast DDS version 2.5.1 or higher is available and a Qt 5 installation is available.

The build process will try to locate the Shapes Demo TypeSupport and, if present, will automatically enable ROS 2 compilation flags.

To download Shapes Demo and its dependencies, including the Shapes Demo TypeSupport, a different repos file, shapes-demo-ros2.repos, can be used. To build eProsima Shapes Demo with ROS 2 features enabled, follow these steps within a sourced ROS 2 Humble installation:

Install the required eProsima Fast DDS dependencies and verify that the system meets the installation requirements. The complete list of requirements and dependencies can be found in the Fast DDS Linux Installation Manual. Specifically, follow the steps outlined in sections Requirements and Dependencies.
Install the ROS 2 development tools (Colcon and Vcstool) by executing the following command:
```
apt update
apt install -y python3-pip wget
pip install -U colcon-common-extensions vcstool
```
Note

If this fails due to an Environment Error, add the --user flag to the pip installation command.

Create a shapes_demo_ws directory and download the ROS 2 version of the repos file that will be used to install eProsima Shapes Demo and its dependencies:

mkdir -p ~/shapes_demo_ws/src
cd ~/shapes_demo_ws
wget https://raw.githubusercontent.com/eProsima/ShapesDemo/master/shapes-demo-ros2.repos
vcs import src < shapes-demo-ros2.repos

Build the packages:
```
cd ~/shapes_demo_ws
colcon build
```
Link the application executable to make it accessible from the current directory:
```
source ~/shapes_demo_ws/install/setup.bash
```
Run eProsima Shapes Demo:
```
ShapesDemo
```

Note

When eProsima Shapes Demo is compiled with ROS 2, the Shapes Demo TypeSupport (see ROS 2 features compilation compilation section) and the ROS 2 Shapes Demo executable is launched in a context with a valid ROS 2 installation sourced, the default value of the “Use ROS 2 Topics” checkbox will be set to true. Otherwise, the checkbox will remain disabled.

Docker Image¶

eProsima provides a Shapes Demo Docker image for those who want a quick demonstration of Fast DDS capabilities and interoperability. This image, based on Ubuntu 22.04, can be downloaded from eProsima’s downloads page.

To run this container you need Docker installed. From a terminal, run:

sudo apt install docker.io

Since Shapes Demo is a graphical application, allowing root to use the graphical interface is required:

xhost local:root

Then, load the Docker image by running:

docker load -i ubuntu-fastdds-shapes-demo\ <version>.tar

Finally, run the Shapes Demo Docker image:

docker run \
    -it \
    --privileged \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    ubuntu-fastdds-shapes-demo:<version>

Using eProsima Shapes Demo¶

This section serves as a guide to the main menus of eProsima Shapes Demo application. After the executable is launched, a window similar to the one presented in the following image should be displayed.

Publishing a Topic (Shape)¶

The Publish button allow the users to define the Shape (topic) and Quality of Service (QoS) for their publication. The following image shows an example of the Publication menu.

There are multiple parameters that the user can define in this menu:

Shape: This parameter defines the topic where the publication is going to occur. Three different shapes can be published: Square, Circle and Triangle (see Fast DDS Topic Documentation).
Color: The user can define the color of the shape. This parameter will be used as key; that is, a way to distinguish between multiple instances of the same shape (see Fast DDS Topics with key documentation).
Size: This parameter allows to control the size of the shape. The size can vary between 1 and 99.
Partition: The user can select different partitions to differentiate groups of publishers and subscribers. The user can select between four partitions (A, B, C and D). Additionally the user can select the * partition, that will be matched against all other partitions (see Fast DDS Partitions Documentation).

Note

Using the wildcard (*) partition is not the same as not using any partition. A publisher that uses the wildcard partition will not be matched with a subscriber that do not defines any partitions.
Reliable: The user can select to disable the Reliable check-box to use a Best-Effort publisher (see Fast DDS ReliabilityQosPolicy Documentation).
History and Durability: The publishers’s History is set to KEEP_LAST. The user can select the number of samples that the publisher is going to save and whether this History is going to be VOLATILE or TRANSIENT_LOCAL. The latter will send that last stored values to subscribers joining after the publisher has been created. (see Fast DDS DurabilityQosPolicy Documentation).
Liveliness: The user can select the Liveliness QoS of the publisher from three different values: AUTOMATIC, MANUAL_BY_PARTICIPANT and MANUAL_BY_TOPIC. The Lease Duration value and Announcement Period can also be configured. The latter only applies if Liveliness is set to AUTOMATIC or MANUAL_BY_PARTICIPANT (see Fast DDS LivelinessQosPolicy Documentation).
Ownership: The Ownership QoS determines whether the key (color) of a Topic (Shape) is owned by a single publisher. If the selected ownership is EXCLUSIVE the publisher will use the Ownership strength value as the strength of its publication. Only the publisher with the highest strength can publish in the same Topic with the same Key (see Fast DDS OwnershipQosPolicy Documentation).
Deadline: The Deadline QoS determines the maximum expected amount of time between samples. When the deadline is missed the application will be notified and a message will be printed on the console (see Fast DDS DeadlineQosPolicy Documentation).
Lifespan: The Lifespan QoS determines the duration while the sample is still valid. When a sample’s lifespan expires, it will be removed from publisher and subscriber histories. (see Fast DDS LifespanQosPolicy Documentation).

Note

Using Lifespan QoS will not have any visual effect.

Subscribing to a Topic (Shape)¶

When the Subscriber button is pressed, a new window appear to allow the user to define the Shape (topic) and Quality of Service (QoS) for its subscription. The following image shows an example of the Subscribe menu.

This menu is highly similar to the Publication menu but the user cannot change the color and size of the Shape, and it has additional elements:

Liveliness: This QoS policy is applied in the same way as in the publisher except for the Announcement Period, which does not apply for the Subscriber (see Fast DDS LivelinessQosPolicy Documentation).
Time Based Filter: This value can be used by the user to specify the minimum amount of time (in milliseconds) that the subscriber wants between updates. (see Fast DDS TimeBasedFilterQosPolicy Documentation).
Content Based Filter: This filter draws a rectangle in the instances window. Only the shapes that are included in this rectangle are accepted while the rest of them are ignored. The user can dynamically resize and move this content filter.

Note

Using Lifespan QoS will not have any visual effect.

Participant configuration¶

The eProsima Shapes Demo application allows the user to define Participant policies. To see the Options window, please go to Options->Participant Configuration in the main bar. The following image shows the Options Menu.

Transport Protocol: You can select between UDP protocol, TCP LAN Server, TCP WAN Server or TCP Client, and Shared Memory protocol.
- UDP: With UDP Protocol the application will work sending multicast packets to communicate with other apps. (See Fast DDS UDP Transport Documentation).
- TCP: TCP protocol needs a minimal configuration to create the connection between the machines: (See Fast DDS TCP Transport Documentation).
  - If the application is going to run as a LAN server, it only needs to set the listening port where it is going to accept connections (note that firewall must be configured to allow inbound traffic).
  - If the application is going to run as a WAN server, it needs to set the listening port where it is going to accept connections and the server WAN address (note that firewall must be configured to allow inbound traffic and router must relay listening port traffic to server machine).
  - If the application is going to run as a client it needs to know the IP address of the server (or its WAN address if both instances don’t share network) and the port where the server is listening for connections.
- Shared Memory (SHM): Activating Shared Memory protocol will use the Shared Memory Transport, a Fast DDS feature that allows a faster and more efficient communication for Participants running in the same host. (See Fast DDS Shared Memory Transport Documentation).
- Default In case no transport has been activated, Fast DDS default transports will be used (UDP + SHM) (See Fast DDS Transports Documentation).
Same host delivery: Fast DDS has some features that allow Participants running in the same host or process to share resources in order to improve the communication:
- Intraprocess: Allow using Intraprocess delivery when both Endpoints are running in the same process. (See Fast DDS Intraprocess Documentation).
- Data Sharing: Allow using Data Sharing delivery when both Endpoints are running in the same host. (See Fast DDS Data Sharing Documentation).
Domain: The user can select different Domain IDs. Shapes Demo instances using different Domain IDs will not communicate. To modify the Domain ID the user needs to stop the participant (thus removing all existing publishers and subscribers) and start a new one with the new Domain ID. (See Fast DDS Domain Documentation).
Statistics: The user can activate Fast DDS Statistics module so different instrumentation data could be collected and analyzed by the Fast DDS Statistics Backend, or be represented by Fast DDS Monitor. This module requires to have compiled Fast DDS with Statistics Module ON. (See Fast DDS Statistics Module Documentation).

In case that the Participant is already running, it should be stopped in order to change its configuration. This will drop every endpoint already created.

Preferences¶

The eProsima Shapes Demo application allows the user to define additional options. To see the Options window, please go to Options->Preferences in the main bar. The following image shows the Options Menu.

The user can customize several aspects of Shapes Demo operation:

Update interval: This value changes the publication period for all the publishers.
Speed: This scroll bar allows the user to change how much the Shape moves between two write calls.

Endpoints and Output tabs¶

A table including all created endpoints is also provided. An example of this legend is shown in the following figure.

This table can be used to remove endpoints. Two methods are provided:

Right click in an endpoint: An option to remove the endpoint is shown.
Pressing the delete button when the endpoint is selected.

The output tab shows the output log messages. An example of the output tab is shown in the figure below.

Discovery and basic connectivity¶

In Fast DDS, the discovery task is automatic. Fast DDS performs the task of finding the relevant information and distributing it to its destination. It means that new nodes are automatically discovered by any other in the network. Please refer to the Fast DDS Discovery Documentation for more information on the various Fast DDS discovery mechanisms.

In this test, three Publishers and three Subscribers are launched. At the end, two additional squares will be displayed in each window, reflecting the movements of the original square in real time. That is, subscribers subscribing to the “Square” topics are matched with the publishers of the other instances.

Step-by-step example implementation¶

First, three publishers must be created.

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance1).
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
Create a blue square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance2).
- Click on Publish.
- Select SQUARE option for Shape and BLUE for Color.
Create a black square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance3).
- Click on Publish.
- Select SQUARE option for Shape and BLACK for Color.

The current setting should be similar to that shown in the figure below.

Then, three subscribers must be created.

Click Subscribe on Instance1.
- Select SQUARE option for Shape.
- Change the History field from 6 to 1.
Click Subscribe on Instance2.
- Select SQUARE option for Shape.
- Change the History field from 6 to 1.
Click Subscribe on Instance3.
- Select SQUARE option for Shape.
- Change the History field from 6 to 1.

The eProsima Shapes Demo windows should look similar to the following image.

History and Durability¶

A publisher can send messages throughout a Topic even if there are no DataReaders on the network. Moreover, a DataReader that joins to the Topic after some data has been written could be interested in accessing that information. The durability defines how the system will behave regarding those samples that existed on the Topic before the subscriber joins. Please refer to Fast DDS DurabilityQosPolicy Documentation for more information on Durability QoS.

In the following example, the publishers’ history is set to KEEP_LAST, and there are two options for the durability configuration which are VOLATILE and TRANSIENT_LOCAL. If VOLATILE is selected, the previous data samples will not be sent. However, if TRANSIENT_LOCAL is selected, the \(n^{th}\) previous data samples will be sent to the late-joining subscriber.

In this example, one hundred red squares will be displayed in Instance2 and Instance3, reflecting the movements of the red square of the publisher from Instance1. The leading square indicates the current position of the published square.

Step-by-step example implementation¶

First, three instances are launched and a publisher is created in each of them:

1 - Create a red square publisher:

Start eProsima Shapes Demo (this instance will be referred to as Instance1).

Click on Publish.

Select SQUARE option for Shape and RED for Color.

Change the History field from 6 to 100.

Select TRANSIENT_LOCAL.

2 - Create an orange square publisher:

Start eProsima Shapes Demo (this instance will be referred to as Instance2).

Click on Publish.

Select SQUARE option for Shape and ORANGE for Color.

Change the History field from 6 to 100.

Select TRANSIENT_LOCAL.

3 - Create a black square publisher:

Start eProsima Shapes Demo (this instance will be referred to as Instance3).

Click on Publish.

Select SQUARE option for Shape and BLACK for Color.

Change the History field from 6 to 100.

Select TRANSIENT_LOCAL.

The eProsima Shapes Demo environment should look similar to the following figure.

Then, subscriber in each instance is created.

Click Subscribe on Instance1.
- Select SQUARE option for Shape.
- Change the History field from 6 to 100.
Click Subscribe on Instance2.
- Select SQUARE option for Shape.
- Change the History field from 6 to 100.
Click Subscribe on Instance3.
- Select SQUARE option for Shape.
- Change the History field from 6 to 100.

The eProsima Shapes Demo environment should look similar to the following figure.

Partition¶

In Fast DDS, Partitions can be used to group subscribers and publishers. If a publisher with a partition is deployed, only the subscriber with the same partition will receive data from it. In this demo, there are four partitions (A, B, C and D). Additionally, you can select the * partition, which refers to all partitions. Please refer to Fast DDS Partitions Documentation for more information on partitions.

In this test, three publishers (Square in Partition A, Circle in Partition B, and Triangle in Partition *), and three subscribers per instance, all of them in Partition A, will be created. Finally, red squares and black triangles in Partition A are set. Therefore, all instances are able to find triangles and squares. However, orange circles are published in partition B and they are only visible in the Instance2.

Step-by-step example implementation¶

First, we must create three publishers.

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance1).
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
- Change the History field from 6 to 1.
- Check Partition A.
Create an orange circle publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance2).
- Click on Publish.
- Select CIRCLE option for Shape and ORANGE for Color.
- Change the History field from 6 to 1.
- Check Partition B.
Create a black triangle publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance3).
- Click on Publish.
- Select TRIANGLE option for Shape and BLACK for Color.
- Change the History field from 6 to 1.
- Check Partition *.

Instance1 will publish red squares in the partition A, Instance2 will publish orange circles in the partition B, and Instance3 will publish black triangles in all partitions.

Then, create three subscribers per Instance with the following characteristics.

Shape	Partition	History (Reliable)	Durability	Ownership
`Square`	`A`	`1` (ON)	`VOLATILE`	`SHARED`
`Circle`	`A`	`1` (ON)	`VOLATILE`	`SHARED`
`Triangle`	`A`	`1` (ON)	`VOLATILE`	`SHARED`

Redundancy and Fault Tolerance¶

Fast DDS allows more than one publisher to write data on the same Topic. All publishers may have the same relevance, or one publisher can be set as the primary publisher and keep the rest as secondary publishers. In that case, only the main publisher can send data to the subscribers. Please refer to Fast DDS OwnershipQosPolicy Documentation for more information on Ownership QoS.

The Ownership QoS determines if the Topic (Shape) is owned by a single publisher or not. There are two ownership options: SHARE or EXLUSIVE ownership. The value of a publisher’s strength can be set using the EXCLUSIVE configuration. Therefore, only the publisher with the highest strength can send data on this Topic. If SHARE is selected, all the publishers can write data at the same time.

In this test, two publishers with EXCLUSIVE ownership in SQUARE Shape, and one subscriber with EXCLUSIVE ownership at the same Shape, will be created.

Step-by-step example implementation¶

First, launch two instances and create a publisher in each of them:

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance1).
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
- Change the History field from 6 to 1.
- Select EXCLUSIVE.
- Set Strength to 1.
- Set Size to 15.

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance2).
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
- Change the History field from 6 to 1.
- Select EXCLUSIVE.
- Set Strength 2.
- Set Size to 30.

A small red square on Instance1 and a big red square on Instance2 should be displayed.

Note

The Instance3 shown in the image below creates a square subscriber. Its creation will be explained later.

Then, create a subscriber.

Create a square subscriber:
- Start eProsima Shapes Demo (this instance will be referred to as Instance3).
- Click on Subscribe.
- Select SQUARE option for Shape.
- Select EXCLUSIVE.

A big square on Instance3 should be seen, since Instance2 has a higher strength than Instance1.

Response to a failure of the main publisher¶

To see how the roles of the publishers change, Instance2 will be stopped. Initially, Instance2 had higher strength and a big red square on Instance2 was observed. However, a small red square is displayed on Instance3 since Instance1 has higher strength now.

Repeating the creation of a publisher with higher strength (2. Create a red square publisher), a small red square replicating the big red square from Instance2 can be seen again.

Liveliness¶

The Liveliness QoS can be used to ensure whether specific entities are alive or not. There are three values to specify the liveliness’ kind: AUTOMATIC, MANUAL_BY_PARTICIPANT or MANUAL_BY_TOPIC liveliness. If any of the first two is selected, a value for the lease duration and announcement period can be set. However, if MANUAL_BY_TOPIC is selected, only the lease duration can be configured, as the announcement period is not used with this configuration. With the AUTOMATIC liveliness kind, the service takes the responsibility for renewing the timer associated to the lease duration, and as long as the remote participant keeps running and remains connected, all the entities within that participant will be considered alive. The other two kinds (MANUAL_BY_PARTICIPANT and MANUAL_BY_TOPIC) need a periodic assertion to consider the remote participants as alive. Please refer to Fast DDS LivelinessQosPolicy Documentation for more information on Liveliness QoS.

In this test, a publisher and subscriber using AUTOMATIC liveliness will be created, and a lease duration value higher than the write rate of the publisher will be set.

Step-by-step example implementation¶

First, launch two instances and create a publisher and a subscriber:

Create a red square publisher:
- Start eProsima Shapes Demo. (We will refer to this instance as Instance1)
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
- Select AUTOMATIC for liveliness kind.
- Set Lease Duration to 150. (The default write rate is 75 ms)
Create a square subscriber:
- Start eProsima Shapes Demo. (We will refer to this instance as Instance2)
- Click on Subscribe.
- Select SQUARE option for Shape.
- Select AUTOMATIC for liveliness kind.
- Set a value for the Lease Duration higher or equal to the one stated for the publisher. (If the value of subscriber lease duration is lower the entities do not match)

The Output Tab of Instance2 shows that the subscriber has recovered the liveliness once it matches with the publisher.

Then, kill the process corresponding to the publisher (Instance1). As a result, the subscriber reported that liveliness was lost, as the publisher did not terminate cleanly.

Deadline¶

The Deadline QoS raises an alarm when the frequency of new samples falls below a predefined threshold. This policy can be useful for those cases which need periodical updates. There exists a distinction between publisher and subscriber deadline period. On the publisher side, that period defines the maximum interval between writes, while on the subscriber’s, it establishes the maximum interval in which the reader expects to receive a new sample. Please refer to Fast DDS LivelinessQosPolicy Documentation for more information on Liveliness QoS.

In this test, a publisher and a subscriber with a deadline period higher than the write rate of the publisher will be created. That shows the normal behavior of the system. Then the write rate will be increased to illustrate the effects of non-compliance with the deadline.

Step-by-step example implementation¶

First, launch two instances and create a publisher and a subscriber:

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance1).
- Click on Publish.
- Select SQUARE option for Shape.
- Select RED for Color.
- Set Deadline Duration to 100. (The default write rate is 75 ms)
Create a square subscriber:
- Start eProsima Shapes Demo (this instance will be referred to as Instance2).
- Click on Subscribe.
- Select SQUARE option for Shape.
- Set a value for the Deadline Duration higher or equal to the one stated for the publisher.
Warning

If the value of the subscriber Deadline Duration is lower than the value stated for the publisher the entities will not match.

In the following figure, the normal behavior of the system can be seen, where the publisher is sending new samples and the subscriber is receiving them before the deadline expires.

Now, increase the write rate:

On Instance1:
- Click on Options.
- Select Preferences.
- Set the update interval to 200.

On the Output Tab can be observed that both publisher and subscriber are continuously missing the deadline, as the value established for the deadline period is lower than the publishing rate.

Lifespan¶

The Lifespan QoS establishes the maximum validity period of the samples saved on an entity’s history. When the lifespan period elapses, the corresponding sample is automatically removed.

Unlike other QoS, such as Deadline or Liveliness, this test does not provide the means to inform the user that the sample is being removed, which makes this test more complicated to illustrate. For this reason, two publishers and two subscribers will be created, and making only one of them use Lifespan, the effect of using this QoS can be graphically seen.

Step-by-step example implementation¶

First, launch an instance and create the two publishers:

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance1).
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
- Select TRANSIENT_LOCAL option for the Durability.
- Make sure that RELIABLE checkbox is marked.
- Set History to 100.
- Leave the Lifespan Duration to infinite.
Create an orange triangle publisher on the previous Shapes Demo instance:
- Click on Publish.
- Select TRIANGLE option for Shape and ORANGE for Color.
- Select TRANSIENT_LOCAL option for the Durability.
- Make sure that RELIABLE checkbox is marked.
- Set History to 100.
- Set Lifespan Duration to 50.

After that, change the write rate to 1000:

On Instance1:
- Click on Options.
- Select Preferences.
- Set the update interval to 1000.

Now, create two subscribers:

Create a square subscriber:
- Start eProsima Shapes Demo (this instance will be referred to as Instance2).
- Click on Subscribe.
- Select SQUARE option for Shape.
- Select TRANSIENT_LOCAL option for the Durability.
- Make sure that RELIABLE checkbox is marked.
- Set History to 100.
- Leave the Lifespan Duration to infinite.
Create a triangle subscriber:
- Start eProsima Shapes Demo (this instance will be referred to as Instance3).
- Click on Subscribe.
- Select TRIANGLE option for Shape.
- Select TRANSIENT_LOCAL option for the Durability.
- Make sure that RELIABLE checkbox is marked.
- Set History to 100.
- Set Lifespan Duration to 50.

When a new subscriber matches with the publisher, due to the TRANSIENT_LOCAL durability, all the samples stored on the publisher history are sent automatically to the new subscriber.

Furthermore, on Instance2 and Instance3, the square subscriber history is filled rapidly, while the triangle subscriber is filled at the same speed as the orange triangle publisher sends new samples. This is because in the second case, samples in the orange triangle publisher history were removed by the QoS, and are no longer available to be sent to the subscriber, while the red square publisher history samples were kept.

Content Based Filter¶

In Fast DDS, the data available to the subscriber can be restricted to control network and CPU usage. The Content Based Filter can be checked when a new subscriber is deployed. This filter draws a shaded region in the instance windows. Only the samples that are covered by the shade will be available to the subscriber. This region can be resized and moved dynamically.

In this test, two Publishers and two subscriber will be created, one of the latter with Content Based.

Step-by-step example implementation¶

First, you have to launch two instances and create a Publisher in each of them:

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance1).
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
- Change the History field from 6 to 1.
Create an orange circle publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance2).
- Click on Publish.
- Select CIRCLE option for Shape and ORANGE for Color.
- Change the History field from 6 to 1.

Your windows should look similar to the following image.

Note

The Instance3 shown in the image below creates a circle subscriber. Its creation will be explained later.

Then, create two subscribers:

Create a circle subscriber:
- Start eProsima Shapes Demo (this instance will be referred to as Instance3).
- Click on Subscribe.
- Select CIRCLE option for Shape.
- Change the History field from 6 to 1.
- Check Content Based.
Create a square subscriber:
- Click on Subscribe in Instance3.
- Select SQUARE option for Shape.
- Change the History field from 6 to 1.

In the following figure, a shaded rectangle in Instance3 is shown. This is the filter for the samples of the Circle Shape. If the circle is out of the rectangle, it is not available for the subscriber.

However, if the instance is in the rectangle, it is available for the subscriber..

The rectangle is configurable, i.e. it can be resized and moved dynamically. The following images show examples of the content filter.

Time Based Filter¶

Fast DDS allow the implementation of a time based filter for the subscribers. Thus, the number of data updates in the subscriber can be restricted specifying the minimum separation time (in milliseconds) between updates. Any data received during this interval will be discarded. Please refer to Fast DDS TimeBasedFilterQosPolicy Documentation for more information on Time Based Filter QoS.

In this test, two publishers and two subscribers, one with a time based filter of 2000ms, will be created. You will see that one subscriber updates its position continuously, but the other jumps every two seconds.

Step-by-step example implementation¶

First, launch two instances and create a Publisher in each of them:

Create a red square publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance1).
- Click on Publish.
- Select SQUARE option for Shape and RED for Color.
Create an orange circle publisher:
- Start eProsima Shapes Demo (this instance will be referred to as Instance2).
- Click on Publish.
- Select CIRCLE option for Shape and ORANGE for Color.
- Change the History field from 6 to 1.

Then, create two subscriber:

Create a circle subscriber:
- Start eProsima Shapes Demo (this instance will be referred to as Instance3).
- Click on Subscribe.
- Select CIRCLE option for Shape.
- Check Time Based an set 2000ms.
Create a square subscriber:
- Click on Subscribe in Instance3.
- Select SQUARE option for Shape.

The eProsima Shapes Demo output should look similar to the following image.

TCP Transport¶

Fast DDS transport layer could be adapted to specific network requirements. UDP transport is optimal for local network applications, but in order to interact on a Wide Area Network (WAN), where one or several NAT mappings may be enforced, a TCP transport is more suitable. Please refer to Fast DDS Transports Documentation for more information.

This section describes how Shapes Demo should be set up in order to fit some network specific layouts.

LAN configuration¶

TCP over LAN can be tested in a scenario where several machines share the same LAN network; nevertheless, UDP performs better and is the advisable choice in practical situations. For this configuration example, one of the machines set up eProsima Shapes Demo as a server and all the others as clients. Assume that the server LAN IP address is 192.168.1.75, then all clients instances of eProsima Shapes Demo deployed on other machines must specify this IP Server address. In this case, the 5100 port is selected as TCP port, but any other available TCP port is valid.

Warning

The server firewall must allow inbound traffic on the selected port.

Server TCP side:

Client TCP side:

WAN configuration¶

This is the typical TCP scenario in which the server machine does not share network with its clients but its reachable through a WAN IP address. This may happen if the server and clients are in a different LANs of the same WAN. To test this scenario we used the network architecture shown in the figure below. It contains the following elements:

A Main Router which simulates the WAN network. In this network Router C has address 192.168.1.74 and Router S has address 192.168.1.75.
A client LAN network managed by Router C.
A server LAN network managed by Router S. The Router S NAT settings relay any inbound TCP traffic to port 5100 towards Sever machine. The TCP port 5100 was arbitrarily chosen, any available port will do.
An eProsima Shapes Demo client running in the machine with IPv4 address 192.168.2.17.
An eProsima Shapes Demo server running in the machine with IPv4 address 192.168.3.49. The Server machine firewall settings allow inbound TCP traffic to port 5100.

The previous configuration (see LAN configuration) does not work in this network scenario because server and client are behind a NAT.

The following image shows server and client settings:

On the client side, the server IP field contains the server’s router IP address, i.e. the Router S IP address (192.168.1.75). The client’s router can understand this address and properly lead the outbound traffic.
On the server side, the WAN IP field contains the server’s router IP address, i.e. the Router S IP address (192.168.1.75) since Router S NAT settings relay inbound traffic to server’s TCP port towards Server computer.

Client TCP side:

Server TCP side:

ROS 2 Compatibility¶

As stated in the ROS 2 features compilation section, eProsima Shapes Demo can be built and used on a ROS 2 installation with additional ROS 2 features. With ROS 2 features enabled, an additional “Use ROS2 Topics” checkbox in the Participant configuration dialog will be shown.

Enabling this box will put Shapes Demo in ROS 2 mode. ROS 2 Shapes Demo main window changes to reflect this by showing a different title and the Vulcanexus logo.

Note

When eProsima Shapes Demo is compiled with ROS 2, the Shapes Demo TypeSupport (see ROS 2 features compilation compilation section) and the ROS 2 Shapes Demo executable is launched in a context with a valid ROS 2 installation sourced, the default value of the “Use ROS 2 Topics” checkbox will be set to true. Otherwise, the checkbox will remain disabled.

When using eProsima Shapes Demo in this mode, ROS 2 will be aware of the Topics transmitted. All topics currently known by ROS can be listed as follows:

ros2 topic list -t

A typical output of the previous command with a Square created by Shapes Demo would be:

/Square [shapes_demo_typesupport/idl/KeylessShapeType]
/parameter_events [rcl_interfaces/msg/ParameterEvent]
/rosout [rcl_interfaces/msg/Log]

Since there is a TypeSupport available for these messages, it can be used by ROS 2 to interact with the different ShapesDemo topics. For instance, assuming the Shapes Demo TypeSupport was built along with Shapes Demo and is currently available in the current installation folder, a subscription to a Topic could be made like so:

source ~/shapes_demo_ws/install/setup.bash
ros2 topic echo /Square

The terminal will start showing the data transmitted on the Square topic:

color: RED
x: 175
y: 215
shapesize: 30
---
color: RED
x: 169
y: 210
shapesize: 30
---

Analogously, a publication could be made like this:

source ~/shapes_demo_ws/install/setup.bash
ros2 topic pub /Square shapes_demo_typesupport/idl/KeylessShapeType "{ color: BLUE, x: 155, y: 170, shapesize: 30}"

On successful execution, this is what would be shown on the terminal:

publisher: beginning loop
publishing #1: shapes_demo_typesupport.idl.KeylessShapeType(color='BLUE', x=155, y=170, shapesize=30)

The ROS 2 Shapes Demo will show the blue Square at the specified location.

Note

ROS 2 Topics enablement will disable some QoS that are not supported by ROS 2 at the moment, namely Ownership and Partitions. Their respective checkboxes will be disabled on the Publisher and Subscriber Dialogs.

Troubleshooting¶

This document compiles the known compatibility issues with other Shapes Demo implementations and the possible solutions.

Two instances in the same machine¶

When using eProsima Shapes Demo and RTI Shapes Demo in the same machine, the file

<Shapes Demo installation directory>/resource/xml/RTI_SHAPES_DEMO_QOS_PROFILES.xml

needs to be modified to force RTI to use the UDPv4 transport protocol only. This can be done writing the following lines inside the <qos_profile> element of the RTI_Shapes_Lib::Shapes_Default_Profile.

<qos_library name="RTI_Shapes_Lib">
    <qos_profile name="Shapes_Default_Profile" is_default_qos="true">
        <!-- The following lines are added to change the participant's transport protocol. -->
        <participant_qos>
            <transport_builtin><mask>UDPv4</mask></transport_builtin>
            <discovery_config>
                <builtin_discovery_plugins>SDP</builtin_discovery_plugins>
                <participant_liveliness_lease_duration>
                    <sec>30</sec>
                    <nanosec>0</nanosec>
                </participant_liveliness_lease_duration>
            </discovery_config>
        </participant_qos>
        <!-- ... -->
    </qos_profile>
    <!-- ... -->
</qos_library>

This setting avoids the use of Shared Memory Transport.

Interoperability¶

You can see an example of the interoperability between eProsima Shapes Demo and other RTPS compliant implementations in the following video: https://www.youtube.com/watch?v=e9_oAJDh-tY

Version 2.10.0¶

This minor release includes the following improvements:

Support for Fast DDS v2.10.0
Enable ROS 2 by default if available
Enable ROS 2 features on runtime if detected a valid ROS 2 installation
Regenerate TypeSupport with Fast DDS-Gen v2.4.0

Also, it includes the following fixes:

Fix Fast DDS version check in CMakeLists
Remove CMake obsolete code

Previous versions¶

Version 2.9.1¶

This patch release includes the following improvements:

Support for Fast DDS v2.9.1.

This patch release includes the following bugfixes:

Added ROS2 name mangling to ROS2 KeylessType.

Version 2.9.0¶

This minor release includes the following improvements:

Support for Fast DDS v2.9.0.
Update type support with Fast DDS-Gen v2.3.0.
Move type support auto-generated files to specific folder to help maintenance.

Version 2.8.1¶

This patch release includes the following improvements:

Ownership QoS Policy enabled when ROS 2 compatible topic option is enabled
Partition QoS Policy enabled when ROS 2 compatible topic option is enabled
Support for Fast DDS v2.8.1

Version 2.8.0¶

This patch release adds the following improvements:

Instances disposals are shown in the GUI
Improvements in the log window
Support for Fast DDS v2.8.0

Version 2.7.1¶

This patch release adds the following improvements:

Support for Fast DDS v2.7.1

Version 2.7.0¶

This patch release adds the following improvements:

Support for Fast DDS v2.7.0
The ShapesDemo’s DomainParticipant acts as TypeLookup server.

Version 2.6.1¶

This patch release adds the following improvements:

Support for Fast DDS v2.6.1
Option to use ROS 2 compatible topics to interact with ROS 2 application

Version 2.6.0¶

The minor release adds the following improvements to support Fast DDS v2.6.0:

Use Fast DDS content filter API to perform content filtering
Update type support with Fast DDS-Gen v2.1.2
Avoid sending type object and type information

Version 2.5.1¶

This release includes the following improvements:

Updated to support Fast DDS v2.5.1

Version 2.5.0¶

This release includes the following improvements:

Updated to support Fast DDS v2.5.0

Version 2.4.1¶

This release includes the following improvements:

Updated to support Fast DDS v2.4.1

Version 2.4.0¶

This release includes the following improvements:

Updated to support Fast DDS v2.4.0
Fixed link to troubleshooting documentation

Version 2.3.4¶

Change log:

Updated to support Fast DDS v2.3.4
Updated to use Fast DDS DDS API
SHM can be selected as transport
Intra-process and datasharing can be enabled/disabled for Shapes Demo DomainParticipants
Fast DDS Statistics module can be enabled for Shapes Demo DomainParticipants
Separate participant configuration from other options
Change License to GNU GPLv3, to be compliant with Qt’s license

Version 2.3.2¶

Change log:

Updated to support Fast DDS 2.3.2.

Version 2.3.1¶

Change log:

Updated to support Fast DDS 2.3.1.

Version 2.3.0¶

Change log:

Updated to support Fast DDS 2.3.0.

Version 2.2.0¶

Change log:

Updated to support Fast DDS 2.2.0.

Version 2.1.3¶

Change log:

Updated to support Fast DDS 2.1.3

Version 2.1.2¶

Change log:

Updated to support Fast DDS 2.1.2

Version 2.1.1¶

Change log:

Updated to support Fast DDS 2.1.1

Version 2.1.0¶

Change log:

Updated to support Fast DDS 2.1.0

Version 2.0.1¶

Change log:

Updated to support Fast DDS 2.0.1

Version 2.0.0¶

Change log:

Updated to support Fast DDS 2.0.0.

Version 1.9.0¶

Change log:

Updated to support Fast RTPS 1.9.0.
Updated to illustrate LivelinessQos.

Version 1.8.1¶

Change log:

Updated to support Fast RTPS 1.8.1.

Version 1.7.1¶

Change log:

Support Fast RTPS 1.7.1.
Bug fixing.

Version 1.7.0¶

Change log:

Updated to support Fast RTPS.
Added support to configure TCP transports in the GUI.