2.3. ROS 2 Shapes Demo

ROS 2 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 ROS 2 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 DDS-compliant implementations.



2.3.1. Running ROS 2 Shapes Demo

ROS 2 Shapes Demo application is available in the Vulcaenxus Tools, Vulcanexus Base and Vulcanexus Desktop packages. Regardless of the installation method used, to run ROS 2 Shapes Demo, load the Vulcanexus environment first, and then run shapesdemo.

source /opt/vulcanexus/humble/setup.bash
shapesdemo

Warning

Please verify that you are running the ROS 2 Shapes Demo version. To check this simply verify that the Vulcanexus banner is displayed in the background of the main box. If the eProsima logo appears instead, activate the ROS 2 version in Options > Participant Configuration > Use ROS 2 Topics.

2.3.2. Getting started

After the executable is launched, a window similar to the one presented in the following image should be displayed.

Main Window

2.3.2.1. Publishing a Topic

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

Publish Window

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.

  • 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 no particion or any combination between four partitions (A, B, C and D). Additionally the user can select the * partition, that will be matched against all other partitions (not only the four given here) (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 Deadline and Lifespan QoS will not have any visual effect.

2.3.2.2. Subscribing to a Topic

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

Subscribe Window

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.

2.3.2.3. Participant configuration

The ROS 2 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.

Options Window
  • Transport Protocol: You can select between UDP protocol, TCP LAN Server, TCP WAN Server or TCP Client, and Shared Memory transport. 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:

  • 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).

  • ROS: By activating “Use ROS 2 Topics”, ROS 2 Shapes Demo automatically renames the topic name and the topic data type according to the mangling used in ROS 2.

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.

2.3.2.4. Endpoints and Output tabs

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

Endpoints

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.

Outputs

2.3.3. Next Steps

Visit eProsima Shapes Demo Documentation for more information on how to use this application.