is-web-api v1.0.1

is-web-api: Integration Service Web API

This project is part of DIH^2. The main goal is provide WebSocket interoperability with ROS2 and FIWARE.

This library was created to service the Node-RED ROS 2 Plugin that provides Node-RED nodes associated with ROS2 and FIWARE endpoints.

Contents

• Background
• Install
• Interface APIs
  • ROS2 APIs
  • FIWARE APIs

Background

The interoperability between the pluging and the ROS2 and FIWARE Broker environments is achieved using WebSocket bridges to them.

These bridges are generated using Integration-Service an eProsima open-source tool.

Using Integration-Service directly from the plugin was possible, but it was considered a better choice to create this library, to abstract the bridge operation. This way:

• The plugin can rely on any other bridge technology.
• Development is simplified by enforcing separation of concerns.
• Any other Node.js project (besides the plugin) can profit from the bridge library.

The libray is composed of several modules:

logger.js : This module provides common logger interface for the others.

websocket_client.js : This module provides websocket connections for each interface (ROS2/FIWARE) to the integration-service. Each configuration emitter will be trigger by the websocket events to report status and user data.

ros2_configuration.js : This module provides a public API to define types, create ROS2 endpoints and send/receive user data. Internally it sets up the integration-service configuration to manage ROS2 nodes and types.

fiware_configuration.js : This module provides a public API to create FIWARE endpoints and send/receive user data. Internally it sets up the integration-service configuration to manage FIWARE nodes. The type definition relies in the ros2_configuration.js module.

launcher.js : This module: keeps the global integration service configuration and manages integration service operation.

Install

A Dockerfile is available to exemplify the set up on an argument provided ROS2 distro.

Dependencies

Some of the following installation steps can be skipped if the target system already fulfils some of the requirements:

1. ROS2 installation. Follow the official ROS2 installation guide for the distro of choice. The Dockerfile is based on a ROS2 image, so this is not exemplified.

2. Install Node.js. The usual OS package managers (like apt on Ubuntu or winget/chocolatey on windows) provide it. An exhaustive list is available here. Some package managers constrain the user to a specific version of Node.js. The Node.js site hints on how to install specific versions.

   For example, in apt is possible to add via location configuration file a new remote repository where all Node.js versions are available. This is the strategy that the Dockerfile uses:

   $ curl -sL https://deb.nodesource.com/setup_14.x -o nodesource_setup.sh
   $ chmod +x nodesource_setup.sh && sudo sh -c ./nodesource_setup.sh
   $ sudo apt-get install -y nodejs

3. Install Node-RED. Follow the official Node-RED installation guide. The Dockerfile favors the easiest procedure which relies on npm (default Node.js package manager) which is available after Node.js installation step:

   $ npm install -g node-red

4. Install Integration-Service. Follow the Integration-Service installation manual. This is exemplified in the Dockerfile, basically it is build from sources downloaded from github. Dependencies associated with the build and bridge environments are required:

   $ apt-get update
   $ apt-get install -y libyaml-cpp-dev libboost-program-options-dev libwebsocketpp-dev \
                      libboost-system-dev libboost-dev libssl-dev libcurlpp-dev \
                      libasio-dev libcurl4-openssl-dev git
   $ mkdir -p /is_ws/src && cd "$_"
   $ git clone https://github.com/eProsima/Integration-Service.git is
   $ git clone https://github.com/eProsima/WebSocket-SH.git
   $ git clone https://github.com/eProsima/ROS2-SH.git
   $ git clone https://github.com/eProsima/FIWARE-SH.git
   
   $ . /opt/ros/humble/setup.sh # customize the ROS2 distro: foxy, galactic, humble ...
   $ colcon build --cmake-args -DIS_ROS2_SH_MODE=DYNAMIC --install-base /opt/is

   Note that it uses the ROS2 build tool: colcon As ROS2 it is necessary to source and overlay. In order to simplify sourcing /opt/is was chosen as deployment dir. The overlay can be then sourced as:

   $ . /opt/is/setup.bash

   It will automatically load the ROS2 overlay too. After the overlay is sourced it must be possible to access the integration-service help as:

   $ integration-service --help

Library installation

Once all the dependencies are available we can deploy the plugin via npm:

• From npm repo:

  $ npm install -g is-web-api

• From sources. npm allows direct deployment from github repo:

  $ npm install -g https://github.com/eProsima/is-web-api

  Or, as in the Dockerfile, from a local sources directory. The docker favors this approach to allow tampering with the sources.

  $ git clone https://github.com/eProsima/is-web-api.git plugin_sources
  $ npm install -g  ./plugin_sources

Interface APIs

Interfaces are provided for ROS2 and FIWARE endpoints. Type definition APIs are provided by the ROS2 module and are common for the FIWARE module. That is, the FIWARE module uses ROS2 provided types.

In order to be suitable for Node-RED nodes operation APIs are flexible in the calling order. Note that Node-RED nodes initialization order is nondeterministic. For example: Publisher and Subscribers can be defined BEFORE its associated types.

ROS2 APIs

They are accessible using:

    let ros_api = require('is-web-api').ros2;

FIWARE APIs

They are accessible using:

    let fiware = require('is-web-api').fiware;

This project (DIH² - A Pan‐European Network of Robotics DIHs for Agile Production) has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 824964