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.
Important
Before following the installation steps, check that you have all the necessary dependencies installed.
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
Warning
If the ROS 1 and ROS 2 System Handles coexist in your Integration Service workspace, please notice that the building process must be split into two steps, due to incompatibility between ROS distros:
source /opt/ros/$<ROS2_DISTRO>/setup.bash
colcon build --packages-skip-regex is-ros1 <COMPILATION_FLAGS>
source /opt/ros/$<ROS1_DISTRO>/setup.bash
colcon build <COMPILATION_FLAGS>
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 all the 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
Note
To use this flag, all the examples dependencies need to be installed.
BUILD_FASTDDS_EXAMPLES
: Allows to compile the Fast DDS utilities that can be used for several of the provided usage examples for Integration Service, located under the examples/utils/dds folder. 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_FASTDDS_EXAMPLES=ON
Note
To compile these examples you need to have Fast DDS (v.2.0.0 or superior) and its dependencies installed.
To date, the following Fast DDS user application examples and utility packages are available:
DDSHelloWorld
: A simple publisher/subscriber C++ application, running under Fast DDS. It publishes or subscribes to a simple string topic, named HelloWorldTopic.The resulting executable will be located inside the
build/is-examples/dds
folder, and namedDDSHelloWorld
. Please executeDDSHelloWorld -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.The resulting executable will be located inside the
build/is-examples/dds
folder, and namedDDSAddTwoInts
. Please executeDDSAddTwoInts -h
to see a full list of supported input parameters.
BUILD_ROS1_EXAMPLES
: Allows to compile the ROS 1 utilities that can be used for several of the provided usage examples for Integration Service, located under the examples/utils/ros1 folder. 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_ROS1_EXAMPLES=ON
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.To date, the following ROS 1 user application examples and utility packages are available:
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 calledadd_two_ints
, which consists of two integer numbers as request type and answers with a single value, indicating the sum of them.The resulting executable will be located inside the
build/devel/lib/add_two_ints_server
folder, and namedadd_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, usingcatkin
:~/is_ws$ cd examples/utils/ros1/catkin_ws/ ~/is_ws/examples/utils/ros1/catkin_ws$ catkin_make -DBUILD_EXAMPLES=ON -DCMAKE_INSTALL_PREFIX=/opt/ros/$<ROS1_DISTRO> install
BUILD_WEBSOCKET_EXAMPLES
: Allows to compile the WebSocket utilities that can be used for several of the provided usage examples for Integration Service, located under the examples/utils/websocket folder. 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_WEBSOCKET_EXAMPLES=ON
Note
In order to compile this example you need to have OpenSSL and WebSocket++ installed.
To date, the following WebSocket user application examples and utility packages are available:
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.The resulting executable will be located inside the
build/is-examples/websocket
folder, and namedDDSAddTwoInts
. Please executeWebSocketAddTwoInts -h
to see a full list of supported input parameters.
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