Getting Started

Table of Contents

This section is meant to provide the user with an easy-to-use installation guide, and an explication of how to launch an eProsima Integration-Service instance.

Installation

The eProsima Integration-Service repository consists of many cmake packages which can be configured and built manually, but we recommend to use colcon, as it makes the job much smoother.

Create a colcon workspace and clone the SOSS and the SOSS-DDS repositories:

mkdir ~/is-workspace
cd ~/is-workspace
git clone ssh://git@github.com/eProsima/soss_v2 src/soss --recursive -b feature/xtypes-dds
git clone ssh://git@github.com/eProsima/SOSS-DDS src/soss-dds --recursive -b feature/xtypes-dds

Note

The --recursive flag in the first git clone command is mandatory to download some required third-parties. The --recursive flag in the second command installs eProsima Fast DDS, which is a requirement of eProsima Integration Service. In this way, both eProsima Integration Service and eProsima Fast DDS will be installed in the same ~/is-workspace/install directory. The use of this second --recursive flag can be omitted in case you have eProsima Fast DDS already installed in your system. Note that if your installation is local, you’ll need to source it before running any eProsima Fast DDS application and eProsima Integration-Service instance.

Once eProsima Integration-Service is in the src directory of your colcon workspace, you can build the packages by running:

colcon build

If any package is missing dependencies causing the compilation to fail, you can add the flag --packages-up-to soss-dds-test to make sure that you at least build soss-dds-test:

colcon build --packages-up-to soss-dds-test

Note

colcon build will build the package soss-core and all the built-in System-Handles. If you don’t want to build the built-in System-Handles you can execute colcon build --packages-up-to soss-core. If you only want a to build a sub-set of built-in System-Handles you can use the same directive with the name of the packages, for example:

colcon build --packages-up-to soss-ros2 soss-fiware

The built-in System-Handles packages are:

  • soss-ros2: ROS2 System-Handle.

  • soss-websocket: WebSocket System-Handle.

  • soss-mock: Mock System-Handle for testing purposes.

  • soss-echo: Echo System-Handle for example purposes.

Additional System-Handles can be found in their own repositories:

Most of the System-Handle packages include a -test package for testing purposes.

Once that’s finished building, and before launching an eProsima Integration-Service instance with the soss command, you can source the new colcon overlay:

source install/setup.bash

Deployment

You can now run an eProsima Integration-Service instance it in order to bring an arbitrary number of middlewares into the DDS world.

The workflow is dependent on the specific middlewares involved in the desired communication, given that each is integrated into eProsima Integration-Service via a dedicated System-Handle.

First of all, you will have to clone the repositories of the System-Handles that your use-case requires into your is-workspace. To know which are the System-Handles supported to date, refer to the Related Links section of this documentation.

Once all the necessary packages have been cloned, you need to build them. To do so, run:

colcon build

with the possible addition of flags depending on the specific use-case. Once that’s finished building, you can source the new colcon overlay:

source install/setup.bash

The workspace is now prepared for running an eProsima Integration-Service instance. From the fully overlaid shell, you will have to execute the soss command, followed by the name of the YAML configuration file that describes how messages should be passed among DDS and the middlewares involved:

soss <config.yaml>

Once eProsima Integration-Service is initiated, the user will be able to communicate the desired protocols.

Note

The sourcing of the local colcon overlay is required every time the colcon workspace is opened in a new shell environment. As an alternative, you can copy the source command with the full path of your local installation to your .bashrc file as:

source ~/is-workspace/install/setup.bash

Getting Help

If you need support you can reach us by mail at support@eProsima.com or by phone at +34 91 804 34 48.