3. YAML Configuration

The first part of this section provides a general overview of all the parameters available to configure and launch an Integration Service instance. To get more detailed information on every subsection, please have a look at the list below:

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 sections 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/" ]
    

    Several parameters can be configured within this section:

    • idls: List of IDL type definitions that can be directly embedded within the configuration file. If the types section is defined, this subsection is mandatory. The type can be entirely defined within the YAML file, or can be included from a preexisting IDL file; for the latter, the system path containing where the IDL file is stored must be placed into the paths section described below.

    • paths (optional): Using this parameter, an existing IDL type written in a separate file can be included within the Integration Service types section. If the IDL path is not listed here, the previous subsection #include preprocessor directive will fail.

    For more details on this section, please refer to the Types definition subsection of this page.


  • 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 subsection in the Built-in System Handles page.

    systems:
      foo: { type: foo }
      bar: { type: bar, types-from: foo }
    

    In relation to the common parameters, their behavior is explained in the following section:

    • type: Middleware or protocol kind. To date, the supported middlewares are: fastdds, ros1, ros2, fiware, websocket_server and websocket_client. There is also a mock option, mostly used for testing purposes.

    • types-from (optional): Configures the types inheritance from a given system to another. This allows to use types defined within Middleware Interface Extension files for a certain middleware into another middleware, without the need of duplicating them or writing an equivalent IDL type for the rest of systems.

    For more details on this section, please refer to the Systems definition subsection of this page.


  • 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 }
    

    There are two kinds of routes, corresponding to either a publication/subscription paradigm or a server/client paradigm:

    • from-to: Defines a route from one (or several) system(s) to one (or several) system(s). A from system expects to connect a publisher user application with a subscriber user application in the to system.

    • server-clients: Defines a route for a request/reply architecture in which there are one or several clients which forward request petitions and listen to responses coming from a server, which must be unique for each service route.

    For more details on this section, please refer to the Routes definition subsection of this page.


  • 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 subsection in the Built-in System Handles page.

    topics:
      hello_foo:
        type: HelloWorld
        route: bar_to_foo
      hello_bar:
        type: HelloWorld
        route: foo_to_bar
        remap: { bar: { topic: HelloBar } }
    

    In relation to the common parameters, their behavior is explained below:

    • type: The topic type name. This type must be defined in the types section of the YAML configuration file, or it must be loaded by means of a Middleware Interface Extension file by any of the middleware plugins or System Handles involved in the communication process.

    • route: Communication bridge to be used for this topic. The route must be one among those defined in the routes section described above.

    • remap (optional): Allows to establish equivalences between the topic name and its type, for any of the middlewares defined in the used route. This means that the topic name and type name may vary in each user application endpoint that is being bridged, but, as long as the type definition is equivalent, the communication will still be possible.

    For more details on this section, please refer to the Topics definition subsection of this page.


  • 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 subsection in the Built-in System Handles page.

    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 } }
    

    Regarding the common parameters, they differ slightly from the topics section:

    • type (optional): The service type. As services usually are composed of a request and a reply, this field only makes sense for those services which consist solely of a request action with no reply. Usually, within the services context, it is not used at all.

    • request_type: The service request type. This type must be defined in the types section of the YAML configuration file, or must be loaded by means of a Middleware Interface Extension file by any of the middleware plugins, or System Handles, involved in the communication process.

    • reply_type: The service reply type. This type must be defined in the types section of the YAML configuration file, or must be loaded by means of a Middleware Interface Extension file by any of the middleware plugins, or System Handles, involved in the communication process.

    • route: Communication bridge to be used for this service. The route must be one among those defined in the routes section described above and must be a route composed of a server and one or more clients.

    • remap (optional): Allows to establish equivalences between the service name (topic field) and its request and reply type, for any of the middlewares defined in the used route. This means that the service name and types names may vary in each user application endpoint that is being bridged, but, as long as the type definition is equivalent, the communication will still be possible.

    For more details on this section, please refer to the Services definition subsection of this page.


3.1. Types definition

Some System Handles have the ability to inform Integration Service of the types definition (using xTypes) that they can use. The System Handles of ROS 1 and ROS 2 are examples of this. Nevertheless, there are cases where the System Handle is not able to retrieve the type specification (websocket, mock, dds, fiware, …) that it needs for the communication.

In those cases, there are two ways to pass this information to the System Handle:

  • Using the types-from property, that imports the types specification from another system.

  • Specifying the type yourself by embedding an IDL into the YAML.

Regarding the second option, the IDL content can be provided in the YAML either directly, as follows:

types:
    idls:
        - >
            struct name
            {
                idl_type1 member_1_name;
                idl_type2 member_2_name;
            };

or by inclusion of a paths field, that can be used to provide the preprocessor with a list of paths where to search for IDL files to include into the IDL content. The syntax in this case would be:

types:
    idls:
        - >
            #include <idl_file_to_parse.idl>

        paths: [ idl_file_to_parse_path ]

Notice that these two approaches can be mixed.

The name for each type can be whatever the user wants, with the two following rules:

  1. The name cannot have spaces in it.

  2. The name must be formed only by letters, numbers and underscores.

Note: a minimum of a structure type is required for the communication.

For more details about IDL definition, please refer to the IDL specification documentation.

The following is an example of a full configuration defining a dds-fiware communication using the types definition contained in the idls block.

types:
    idls:
        - >
            struct Stamp
            {
                int32 sec;
                uint32 nanosec;
            };

            struct Header
            {
                string frame_id;
                stamp stamp;
            };

systems:
    dds: { type: dds }
    fiware: { type: fiware, host: 192.168.1.59, port: 1026 }

routes:
    fiware_to_dds: { from: fiware, to: dds }
    dds_to_fiware: { from: dds, to: fiware }

topics:
    hello_dds:
        type: "Header"
        route: fiware_to_dds
    hello_fiware:
        type: "Header"
        route: dds_to_fiware

3.2. Systems definition

A System Handle may need additional configuration that should be defined in its systems entry as a YAML map. Each entry of this section represents a middleware involved in the communication, and corresponds to an instance of a System Handle. All System Handles accept the type and types-from options in their systems entry. If type is omitted, the key of the YAML entry will be used as type.

systems:
    dds:
    ros2_domain5: { type: ros2, domain: 5, node_name: "ros_node_5" }
    fiware: { host: 192.168.1.59, port: 1026 }

The snippet above will create three System Handles instances:

  • A DDS System Handle instance, with default configuration.

  • A ROS 2 System Handle instance, named ros2_domain with domain = 5 and node_name = "is_5".

  • A FIWARE System Handle instance, with host = 192.168.1.59 and port = 1026.

The System Handles currently available for Integration Service are listed in a table that you can find in the Built-in System Handles section of this documentation.

A new System Handle can be created by implementing the desired SystemHandle subclasses to add support to any other protocol or system. For more information consult the System Handle section.

3.3. Routes definition

This section allows enumerating the bridges between the systems that Integration Service must manage. To achieve bidirectional communication, both ways must be specified.

routes definition keywords are specific depending on whether the route is defining a publisher/subscriber path (from-to) or a service/client communication path (server-client). For example:

routes:
    ros2_to_dds: { from: ros2_domain5, to: dds }
    dds_to_ros2: { from: dds, to: ros2_domain5 }
    dds_server: { server: dds, clients: ros2_domain5 }
    fiware_server: { server: fiware, clients: [ dds, ros2_domain5 ] }

This YAML defines the following routes:

../_images/routes.png
  • The route ros2_to_dds defines a ros2_domain5 publisher with a dds subscriber.

  • The route dds_to_ros2 defines a dds publisher with a ros2_domain5 subscriber.

  • Having the routes ros2_to_dds and dds_to_ros2 results in a bidirectional communication between the ros2_domain5 and dds systems.

  • The route dds_server defines a dds server with only one client: ros2_domain5.

  • The route fiware_server defines a fiware server with two clients: ros2_domain5 and dds.

3.4. Topics definition

Each system is able to publish/subscribe to each other’s topics. These publish/subscription policies are set directly in the YAML configuration file by specifying the topic type and its route (which system is the publisher and which is the subscriber) as the main parameters:

topics:
    point_to_ros2:
        type: "geometry_msgs/Point"
        route: dds_to_ros2
    point_to_dds:
        type: "geometry_msgs/Point"
        route: ros2_to_dds
  • The topic point_to_ros2 will create a dds publisher and a ros2_domain5 subscriber.

../_images/point_to_ros2.png
  • The topic point_to_dds will create a ros2_domain5 publisher and a dds subscriber.

../_images/point_to_dds.png

If a custom System Handle needs additional configuration regarding the topics, it can be added to the topic definition as new map entries.

3.5. Services definition

service definition is very similar to topics definition, with the difference that in this case routes can only be chosen among the ones specified with the server/client syntax; also, the type entry for these fields usually follows the request/response model, pairing each of them with the corresponding route, depending on which system acts as the server and which as the client(s).

services:
    get_map:
        type: "nav_msgs/GetMap"
        route: dds_server
    update_position:
        type: "Position"
        route: fiware_server
  • The service get_map will create a dds server and a ros2_domain5 client.

../_images/get_map.png
  • The service update_position will create a fiware server, and dds and ros2_domain5 clients.

../_images/update_position.png

If a custom System Handle needs additional configuration regarding the services, it can be added in the service definition as new map entries.

Note

If the type field is defined, as in the example above, this type will be taken into consideration as the request type. If a certain service needs to distinguish between request and reply types, the fields request_type and reply_type must be used instead.

3.6. Remapping

Sometimes, topics or types from one system are different from those managed by the systems with which it is being bridged. To solve this, Integration Service allows to remap types and topics in the Topics definition and in the Services definition.

services:
    set_destination:
        type: "nav_msgs/Position"
        route: dds_server
        remap:
            dds:
                type: "dds/Destination"
                topic: "command_destination"

In this services entry, the remap section defines the type and the topic that must be used in the dds system, instead of the ones defined by the service definition, which will be used by the ros2_domain5 system.

../_images/remap.png