2. Installation

This section provides the user with an easy-to-follow installation guide of both the Integration Service and of the System Handles, and an explanation of how to launch and deploy an Integration Service project.

2.1. Workspace Setup

This section explains step by step the workspace configuration required to use Integration Service. It is divided into two subsections, which describe the configuration of the Integration Service Core and the System Handles respectively.

2.1.1. Core

The Integration Service core consist of many CMake packages which can be configured and built manually, but we recommend to use colcon, as it makes the job much smoother.

The starting point is to create a colcon workspace and clone the Integration-Service repository, containing the core. To do so, follow the next instructions:

mkdir ~/is-workspace
cd ~/is-workspace
git clone https://github.com/eProsima/Integration-Service.git src/Integration-Service --recursive

At this point, you have the Integration Service library correctly cloned into your is-workspace/src/Integration-Service folder.

Note

The --recursive flag is needed to correctly initialize the xTypes library as a submodule.

2.1.2. System Handles

As discussed in the Introduction section, Integration Service allows to bring an arbitrary number of middlewares into communication, each integrated into the core with a dedicated System Handle.

The workflow is thus dependent on the middlewares involved in the desired communication. The up-to-date list of the available System Handles and the repositories hosting them is provided in the Built-in System Handles section.

Depending on the use-case, you might need to have either one, two, or more System Handles installed. In the Examples section, you can find a collection of relevant examples clarifying how to use these plugins according to your needs.

You will have to clone the repositories of the desired System Handles into the previously created is-workspace:

cd ~/is-workspace
git clone https://github.com/eProsima/<middleware_1-SH>.git src/middleware_1-SH
...
git clone https://github.com/eProsima/<middleware_N_SH>.git src/middleware_2-SH

Where <middleware_i-SH>, with i = 1, .., N refers to the i-th System Handle needed for carrying out the integration, chosen among the ones listed in the Built-in System Handles section. Each such System Handle will be cloned in a dedicated src/middleware_i-SH folder inside your is-workspace.

Note

If using a custom System Handle which is not present in the eProsima GitHub organization, clone the dedicated repository into the is-workspace.

2.2. Build

Once all the necessary packages have been cloned, they need to be built. To do so, execute from the is-workspace:

colcon build <COMPILATION_FLAGS>

Note

<COMPILATION_FLAGS> refers to the optional flags used to configure Integration Service. For further details refers to the Global compilation flags section.

Once that’s finished building and before launching your Integration Service project, you need to source the new colcon overlay:

source install/setup.bash

2.2.1. Global compilation flags

Integration Service uses CMake for building and packaging the project. There are several CMake flags, which can be tuned during the configuration step:

  • BUILD_LIBRARY: This compilation flag can be used to completely disable the compilation of the Integration Service set of libraries, that is, the Integration Service Core and all the existing System Handles existing in the colcon workspace. It is enabled by default.

    This flag is useful, for example, to speed up the documentation generation process, when building the API Reference from the Doxygen source code comments.

    ~/is_ws$ colcon build --cmake-args -DBUILD_LIBRARY=OFF
    
  • BUILD_API_REFERENCE: It is used to generate all the necessary files for building the API Reference section of this documentation, starting from the source code comments written using a Doxygen-like format. It is disabled by default; to use it:

    ~/is_ws$ colcon build --cmake-args -DBUILD_API_REFERENCE=ON
    
  • BUILD_TESTS: When compiling Integration Service, use the -DBUILD_TESTS=ON CMake option to compile both the unitary tests for the Integration Service Core and the unitary and integration tests for all the System Handles present in the colcon workspace:

    ~/is_ws$ colcon build --cmake-args -DBUILD_TESTS=ON
    
  • BUILD_EXAMPLES: Allows to compile utilities that can be used for the several provided usage examples for Integration Service, located under the examples/utils folder of the core repository. These applications can be used to test the Integration Service with some of the provided YAML configuration files, which are located under the examples/basic directory of the core repository:

    ~/is_ws$ colcon build --cmake-args -DBUILD_EXAMPLES=ON
    

    To date, the following user application examples and utility packages are available:

    DDS

    • DDSHelloWorld: A simple publisher/subscriber C++ application, running under Fast DDS. It publishes or subscribes to a simple string topic, named HelloWorldTopic. As an alternative to colcon, in order to compile the DDSHelloWorld example, the following commands can be executed:

      ~/is_ws$ cd examples/utils/dds/DDSHelloWorld
      ~/is_ws/examples/utils/dds/DDSHelloWorld$ mkdir build
      ~/is_ws/examples/utils/dds/DDSHelloWorld$ cd build
      ~/is_ws/examples/utils/dds/DDSHelloWorld/build$ cmake .. -DBUILD_EXAMPLES=ON
      ~/is_ws/examples/utils/dds/DDSHelloWorld/build$ make
      

      The resulting executable will be located inside the build folder, and named DDSHelloWorld. Please execute DDSHelloWorld -h to see a full list of supported input parameters.

    • DDSAddTwoInts: A simple server/client C++ application, running under Fast DDS. It allows performing service requests and replies to a service named AddTwoIntsService, which consists of two integer numbers as request type and answers with a single value, indicating the sum of them. As an alternative to colcon, in order to compile the DDSAddTwoInts example, the following commands can be executed:

      ~/is_ws$ cd examples/utils/dds/DDSAddTwoInts
      ~/is_ws/examples/utils/dds/DDSAddTwoInts$ mkdir build
      ~/is_ws/examples/utils/dds/DDSAddTwoInts$ cd build
      ~/is_ws/examples/utils/dds/DDSAddTwoInts/build$ cmake .. -DBUILD_EXAMPLES=ON
      ~/is_ws/examples/utils/dds/DDSAddTwoInts/build$ make
      

      The resulting executable will be located inside the build folder, and named DDSAddTwoInts. Please execute DDSAddTwoInts -h to see a full list of supported input parameters.

      Note

      In order to compile these examples you need to have FastDDS (v.2.0.0 or superior) and its dependencies installed.

    ROS 1

    • add_two_ints_server: A simple C++ server application, running under ROS 1. It listens to requests coming from ROS 1 clients and produces an appropriate answer for them; specifically, it is capable of listening to a ROS 1 service called add_two_ints, which consists of two integer numbers as request type and answers with a single value, indicating the sum of them. As an alternative to colcon, in order to compile the add_two_ints_server example, the following commands can be executed:

      ~/is_ws$ cd examples/utils/ros1/add_two_ints_server
      ~/is_ws/examples/utils/ros1/add_two_ints_server$ mkdir build
      ~/is_ws/examples/utils/ros1/add_two_ints_server$ cd build
      ~/is_ws/examples/utils/ros1/add_two_ints_server/build$ cmake .. -DBUILD_EXAMPLES=ON
      ~/is_ws/examples/utils/ros1/add_two_ints_server/build$ make
      

      The resulting executable will be located inside the build/devel/lib/add_two_ints_server folder, and named add_two_ints_server_node.

    • example_interfaces: ROS 1 package containing the service type definitions for the AddTwoInts services examples, for which the ROS 1 type support files will be automatically generated. As specified in the services examples tutorials, it must be compiled and installed in the system, using catkin:

      ~/is_ws$ cd examples/utils/ros1/
      ~/is_ws/examples/utils/ros1$ catkin_make -DBUILD_EXAMPLES=ON -DCMAKE_INSTALL_PREFIX=/opt/ros/$ROS1_DISTRO install
      

      Note

      In order to compile this example you need to have ROS 1 (Melodic or superior) installed and sourced, and the Integration Service example_interfaces ROS 1 package compiled.

    WebSocket

    • WebSocketAddTwoInts: A simple server/client C++ application, running under WebSocket++. It allows performing service requests and replies to a service named add_two_ints, which consists of two integer numbers as request type and answers with a single value, indicating the sum of them. As an alternative to colcon, in order to compile the WebSocketAddTwoInts example, the following commands can be executed:

      ~/is_ws$ cd examples/utils/websocket/WebSocketAddTwoInts
      ~/is_ws/examples/utils/websocket/WebSocketAddTwoInts$ mkdir build
      ~/is_ws/examples/utils/websocket/WebSocketAddTwoInts$ cd build
      ~/is_ws/examples/utils/websocket/WebSocketAddTwoInts/build$ cmake .. -DBUILD_EXAMPLES=ON
      ~/is_ws/examples/utils/websocket/WebSocketAddTwoInts/build$ make
      

      The resulting executable will be located inside the build folder, and named DDSAddTwoInts. Please execute WebSocketAddTwoInts -h to see a full list of supported input parameters.

      Note

      In order to compile this example you need to have OpenSSL and WebSocket++ installed.

2.3. Deployment

The is-workspace is now prepared for running an Integration Service instance.

The communication can be configured using a YAML file as explained in section YAML Configuration. Once created, it is passed to Integration Service with the following instruction:

integration-service <config.yaml>

As soon as Integration Service is initiated, the desired protocols can be communicated by launching them in independent terminal windows. To get a better taste of how to do so, refer to the Examples section, which provides several examples of how to connect instances of systems that are already integrated into the Integration Service ecosystem.

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 /PATH-TO-YOUR-IS-WORKSPACE/is-workspace/install/setup.bash