eProsima Integration Service is a Linux tool that enables communication among an arbitrary number of protocols that speak different languages.
This project was born as a joint effort between Open Robotics and eProsima, which nowadays is in charge of maintaining it.
It works by translating the languages of the systems involved to a common representation language that follows the Extensible and Dynamic Topic Types for DDS (xTypes) standard by the OMG; specifically, Integration Service bases its intercommunication abilities on eProsima's open source implementation for the xTypes protocol, that is, eProsima xTypes.
The translation is mediated by system-specific plugins, or System Handles, allowing to communicate the middlewares involved with the core, that speaks the common xTypes representation language. This is carried out by interfacing each entity in the user application with a complimentary "mirror" proxy in the System Handle (SH), able to communicate with the former according to either a pub/sub or service pattern. Namely:
Integration Service can be launched using the command line, as follows:
~/is_ws$ integration-service <filename>.yaml
It is recommended to use colcon to build and install the
Integration Service executable and its associated middleware plugins; for more information, please refer to
the Installation manual
section in the documentation chapter of this document.
Looking for commercial support? Write us to info@eprosima.com
Find more about us at eProsima’s webpage.
Download here the Integration Service docker image that contains pre-installed Fast DDS, ROS 1, ROS 2 and WebSocket System Handles and the documentation examples.
This section provides a list of the dependencies needed in order to compile Integration Service. These requirements will be different depending on the System Handles you want to use.
Boost program options: Library that allows obtaining name-value pairs from the config file.
These libraries can be installed using your Linux distribution package manager with the following command:
sudo apt-get install -y libyaml-cpp-dev libboost-program-options-dev
cURL: Command-line tool for getting or sending data using URL syntax.
These libraries can be installed using your Linux distribution package manager with the following command:
sudo apt-get install -y libcurlpp-dev libasio-dev libcurl4-openssl-dev
WebSocket++: WebSocket Protocol C++ library implementation.
These libraries can be installed using your Linux distribution package manager with the following command:
sudo apt-get install -y libssl-dev libwebsocketpp-dev
The Integration Service can be configured during runtime by means of a dedicated YAML file. This configuration file must follow a specific syntax, meaning that it is required that a number of compulsory section are opportunely filled for it to successfully configure and launch an Integration Service instance, while others are optional. Both kinds are listed and reviewed below:
types
(optional): It allows to list the IDL
types used by the Integration Service to later define the topics and services types which will
take part in the communication process.
This field can be omitted for certain Integration Service instances where one or more System Handles already include(s) static type definitions and their corresponding transformation libraries (Middleware Interface Extension or mix files).
types:
idls:
- >
#include <GoodbyeWorld.idl>
struct HelloWorld
{
string data;
GoodbyeWorld bye;
};
paths: [ "/home/idl_files/goodbyeworld/" ]
systems
: Specifies which middlewares will be involved in the communication process, allowing
to configure them individually.
Some configuration parameters are common for all the supported middlewares within the
Integration Service ecosystem; while others are specific of each middleware. To see which
parameters are relevant for a certain middleware, please refer to its dedicated README section
in its corresponding GitHub repository, under the name of https://github.com/eProsima/<MW_NAME>-SH
.
systems:
foo: { type: foo }
bar: { type: bar, types-from: foo }
routes
: In this section, a list must be introduced, corresponding to which bridges are needed by
Integration Service in order to fulfill the intercommunication requirements
for a specific use case.
At least one route is required; otherwise, running Integration Service would be useless.
routes:
foo_to_bar: { from: foo, to: bar }
bar_to_foo: { from: bar, to: foo }
foo_server: { server: foo, clients: bar }
bar_server: { server: bar, clients: foo }
topics
: Specifies the topics exchanged over the routes
listed above corresponding to the
publication-subscription paradigm. The topics must be specified in the form of a YAML dictionary,
meaning that two topics can never have the same name.
For each topic, some configuration parameters are common for all the supported middlewares within the
Integration Service ecosystem; while others are specific of each middleware. To see which topic
parameters must/can be configured for a certain middleware, please refer to its dedicated README section
in its corresponding GitHub repository, under the name of https://github.com/eProsima/<MW_NAME>-SH
.
topics:
hello_foo:
type: HelloWorld
route: bar_to_foo
hello_bar:
type: HelloWorld
route: foo_to_bar
remap: { bar: { topic: HelloBar } }
services
: Allows to define the services that Integration Service will be in charge of
bridging, according to the service routes
listed above for the client/server paradigm.
The services must be specified in the form of a YAML dictionary, meaning that two services can
never have the same name.
For each service, some configuration parameters are common for all of the supported middlewares
within the Integration Service ecosystem; while others are specific of each middleware.
To see which parameters must/can be configured for a certain middleware in the context of a service
definition, please refer to its dedicated README section in its corresponding GitHub repository,
under the name of https://github.com/eProsima/<MW_NAME>-SH
.
services:
serve_foo:
request_type: FooRequest
reply_type: FooReply
route: foo_server
serve_bar:
request_type: BarRequest
reply_type: BarReply
route: bar_server
remap: { foo: { request_type: bar_req, reply_type: bar_repl, topic: ServeBar } }
Finally, it is important to remark that both the services
and topics
sections are not mandatory,
meaning that an Integration Service instance can be launched only for publication/subscription
bridging, or solely to perform service type communications. However, they are not exclusive,
and can coexist under the same YAML configuration file.
All of the currently protocols are integrated within Integration Service by means of dedicated plugins or System Handles.
The complete System Handles set for the Integration Service is currently composed of the following protocols:
Additionally, creating a System Handle is a relatively easy task and allows to integrate a new protocol to the Integration System infrastructure, which automatically provides the new protocol with communication capabilities towards all of the aforementioned middlewares and protocols.
For more information, please refer to the System Handle user manual and System Handle API reference sections, available in the official documentation.
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 the 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.
:warning: | To use this flag, all the examples dependencies need to be installed. |
---|
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:
~/is_ws$ colcon build --cmake-args -DBUILD_EXAMPLES=ON
BUILD_FASTDDS_EXAMPLES
: Allows to compile the FastDDS utilities that can be used for several of the
provided usage examples for Integration Service, located under the examples/utils/dds
folder.
:warning: | To compile these examples you need to have FastDDS (v.2.0.0 or superior) installed. |
---|
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:
~/is_ws$ colcon build --cmake-args -DBUILD_FASTDDS_EXAMPLES=ON
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.
:warning: | To compile this example you need to have ROS 1 (Melodic or superior) installed and sourced. |
---|
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:
~/is_ws$ colcon build --cmake-args -DBUILD_ROS1_EXAMPLES=ON
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.
:warning: | To compile this example you need to have OpenSSL and WebSocket++ installed. |
---|
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:
~/is_ws$ colcon build --cmake-args -DBUILD_WEBSOCKET_EXAMPLES=ON
The official documentation for eProsima Integration Service is hosted by Read the Docs, and comprises the following sections:
This repository is open-sourced under the Apache-2.0 license. See the LICENSE file for more details.