micro-ROS & FIWARE

Interoperability

This subsection will explain all the design alternatives for the interoperability of FIROS2 with micro-ROS.

Mechanisms for the deserialisation of incoming data in the transformation library

FIROS2 requires transformation libraries to convert ROS 2 messages into FIWARE NGSIv2 messages and the other way around. For each message, one transformation library is required by the integration service (FIROS2).

image

In the implementation of these transformation libraries, the user needs to be able to serialisation/deserialisation ROS 2 messages. Also, an NGSIv2 serialisation/deserialisation mechanism will be used.

The FIROS2 package provides a standard NGSIv2 serialisation/deserialisation mechanisms, but ROS 2 serialisation/deserialisation is not offered due to its dependencies with the message type.

For solving this issue, various methods to get it are proposed:

Use serialisation/deserialisation method provided by the middleware layer

This is currently the method used in micro-ROS - FIROS 2 integration.

In this case, the transformation library will use user selected middleware interface to serialise/deserialise the bridged ROS 2 messages. This method requires to get the message typesupport for the bridged message type. This method is straightforward to implement as it does not require additional source code development. Also, the abstraction from the middleware implementation makes it more compatible with others ROS 2 workspaces.

This is a portion of code used in the transformation library implementation.

    extern "C" void USER_LIB_EXPORT transform(SerializedPayload_t *serialized_input, SerializedPayload_t *serialized_output){

    // Get type support
    const rosidl_message_type_support_t * type_support = rosidl_typesupport_cpp::get_message_type_support_handle<MESAGE_TYPE>();

    // Convert to ROS 2 serialized message
    rmw_serialized_message_t serialized_message;
    serialized_message.buffer = (char*)serialized_input->data;
    serialized_message.buffer_length = serialized_input->length;
    serialized_message.buffer_capacity = serialized_input->max_size;
    serialized_message.allocator = rcutils_get_default_allocator();

    // Deserialise
    MESAGE_TYPE data;
    if (rmw_deserialize(&serialized_message, type_support, (void*)&data) != RMW_RET_OK){
        return;
    }

    // Transformation and NGSIv2 serialisation code here

    }

Note the call to ROS 2 interface rosidl_typesupport_cpp::get_message_type_support_handle

Use serialisation/deserialisation method for an specific type support

In this case, the transformation library will use one specific type support to serialise/deserialise the bridged ROS 2 messages. In micro-ROS case, the implementation to be used will be rosidl_typesupport_microxrcedds. This method is trivial to develop as it does not require additional source code on the micro-ROS side.

In the case of micro-ROS, the transformation library should use the serialisation/deserialisation API exposed by its typesupport, rosidl_typesupport_microxrcedds. This mechanism requires the user to have access to the typesupport API, which sometimes is not always possible.

Used serialisation/deserialisation method generated from IDL file

In this case, transformation library will use generated code to serialise/deserialise the bridged ROS 2 messages. The generated code may be made using an IDL parser tool. In the micro-ROS case, Micro XRCE-DDS provides with Micro XRCE-DDS code generator, which accepts an IDL file as input and generates type code. This IDL files should correspond with those messages types the transformation is wanted. This is the integration service native method. Integration services uses this method, but it makes the development of the library slower as it needs to be generated per each message to be bridged.

image

In the case of ROS 2 / micro-ROS workspaces, there are tools which generate those IDL files. The rosidl_gen package is the package micro-ROS/ROS2 could use to create IDL from ROS 2 interfaces.

Integration proposals

Aside from transformation library implementations possibilities, micro-ROS could be integrated into different levels with FIROS2. This section presents all the integrations possibilities.

Direct integration

In this case, micro-ROS Agent will act as a bridge between DDS-XRCE and NGSIv2.

Selected bridged topics and their corresponding transformations must be configured on the micro-ROS Agent node.

This proposal requires micro-ROS Agent changes, but it is the direct native integration of micro-ROS and FIROS, without relying on DDS global data space.

Architecture

image

Use case

image

Indirect integration with a single FIROS2 node

In this case, micro-ROS nodes will publish the configured topics on DDS, and a FIROS2 node will subscribe to those topics and convert them into NGSIv2 protocol. Selected bridged topics must be configured on that single FIROS2 node. Each ROS 2 topic type should have a corresponding transformation library configured on that FIROS2 node.

This approach is a specialisation of the following one, where all the configuration and transformation libraries are centralised in a single node.

This proposal requires transformation library development, but the integration will be the same as a regular ROS 2 node, so no micro-ROS specific development should be expected.

Architecture

image

Use Case

image

Indirect integration with multiple FIROS2 nodes

In this case, micro-ROS nodes will publish the configured topic on DDS and multiple FIROS2 nodes, one for each set topic, will subscribe to those topics and convert them into NGSIv2 protocol.

This approach would require more nodes on the network and individual configurations.

This approach is the one followed by micro-ROS, and it is limited due to current FIROS 2 implementation.

This proposal requires transformation library development, but the integration will be the same as a regular ROS 2 node, so no micro-ROS specific development should be expected.

Workflow

image

Use Case

image

Demonstration

This section explains how to demonstrate the interoperability of FIROS2 with micro-ROS. The purpose is to demonstrate the interoperability, although the final design is not closed.

To run the demonstration a step by step guide is presented in this document.

Note: The only requirement to run the demonstration is to have docker CE and docker compose installed.

Linux demonstration

  1. Run Micro-ROS Agent node

Download the pre-compiled agent and run it

docker pull microros/agent_linux
docker run  -it --rm  --privileged --net=host microros/agent_linux

Once inside the docker, raise the agent.

uros_agent udp 8888

Note: After this step a micro-ROS Agent will be running at the localhost address and port 8888.

  1. Run a FIWARE Orion broker

To test the communication it is necessary to have a FIWARE Orion server listening. The server will be run locally using a docker compose. The steps have been extracted from the docker hub official FIWARE repository.

For this, execute the following commands in a terminal and leave it open.

(
mkdir orion
cd orion
echo "mongo:
    image: mongo:3.4
    command: --nojournal
orion:
    image: fiware/orion
    links:
        - mongo
    ports:
        - \"1026:1026\"
    command: -dbhost mongo" > docker-compose.yml
sudo docker-compose up
)

Note: After this execution a FIWARE Orion server will be running at the localhost address and port 1026.

  1. Build FIROS2 in a ROS 2 workspace and run it

To compile FIROS2, micro-ROS Agent side set of packages will be used.

For this, execute the following instructions.

(
sudo docker pull microros/linux
sudo docker run  -it --rm  --privileged --net=host microros/linux
)

Once in the Docker, all the necessary repositories should be downloaded and a FIROS2 node built and configured as a gateway of an int32.

(
mkdir -p ws/src
cd ws
wget https://raw.githubusercontent.com/micro-ROS/micro-ROS-doc/feature/RepoListUpdate/Installation/repos/agent_minimum.repos
vcs import src < agent_minimum.repos
git clone -b feature/FIROS2 https://github.com/micro-ROS/micro-ROS-demos.git src/uros/Demos
git clone --recursive -b feature/TCP_DynTypes https://github.com/eProsima/FIROS2.git src/uros/FIROS2
colcon build
. ./install/local_setup.bash
install/firos2/bin/firos2 install/int32_firos2/lib/int32_firos2/config.xml
)
  1. Run Micro-ROS client publisher

Download a pre-compiled client and execute it.

docker pull microros/client_linux
docker run  -it --rm  --privileged --net=host microros/client_linux

Once in the docker run the micro-ROS Client.

int32_publisher_c
  1. Check that data has been uploaded into FIWARE Orion server

In a Linux terminal execute the below sub-shell script

(
    UPDATE_TIME="0.5"

    curl  -v \
        --include \
        --header 'Content-Type: application/json' \
        --request POST \
        --data-binary '{  "id": "Helloworld",
                            "type": "Helloworld",
                            "$ATTRIBUTE": {
                                "value": "0",
                                "type": "Number"
                            }
                        }' \
        'localhost:1026/v2/entities'

    (
        while (( 1 ))
        do
        curl -v "localhost:1026/v2/entities/Helloworld/attrs/count/value?type=Helloworld"
        echo ""
        sleep $UPDATE_TIME
        done
    )
)

For further information please refer to the official FIROS2 documentation: FIROS2 documentation