❤
npm
Sign UpSign In

is-web-api

1.0.1 • Public • Published

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

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;
function get_dds_domain()
returns The actual DDS domain selected
function set_dds_domain(id)
id Sets the DDS domain to use
function get_event_emitter()
returns Event emitter associated to the ROS2 config. It reports:
IS-ERROR
Error on integration-service deployment
ROS2_connected
ROS2 bridge websocket operational
[TOPIC]_data
Data has been received for [TOPIC]. It is delivered as a json argument for the callback
function send_message(topic, data)
topic Topic associate with the data
data Data to deliver as a javascript Object
function stop()
Stops integration-service operation
function launch(node_id)
node_id identifier used to query the error dictionary. If an error is registered the operation is aborted and the error return
returns An Object with the following properties:
color
'red' on error
message
non-null on error
event_emitter
The same value returned by get_event_emitter()
function new_config()
resets the global configuration for integration-service. All types & endpoints are discarded
function add_publisher(pub_id, topic_name, type_name, qos)
pub_id identifier used to fill the error dictionary if there is an error
topic_name Topic associated to the publisher
type_name Type associated to the publisher. May not be registered at the call time
qos a collection of DDS QoS as array of properties. Each property is an Object with:
p
[qos name](.[param])?
v
value of the param if any
Information about each QoS is provided here.
function add_subscriber(sub_id, topic_name, type_name, qos)
sub_id identifier used to fill the error dictionary if there is an error
topic_name Topic associated to the subscriber
type_name Type associated to the subscriber. May not be registered at the call time
qos a collection of DDS QoS as array of properties. Each property is an Object with:
p
[qos name](.[param])?
v
value of the param if any
Information about each QoS is provided here.
function add_ros2_type(package_name, type_name)
package_name name associated to a builtin ROS2 messages package.
type_name name associated to one of messages in the package argument
function add_idl_type(idl, type_name)
idl IDL file associated to the type in a single string
type_name name to associate to the IDL

FIWARE APIs

They are accessible using:

    let fiware = require('is-web-api').fiware;
function get_fiware_port()
returns The actual port selected for the Context Broker
function set_fiware_port(port)
port Sets the port associated to the Context Broker
function get_fiware_host()
returns The actual IPv4 host address selected for the Context Broker
function set_fiware_host(host)
host Sets the IPv4 host address associated to the Context Broker
function get_event_emitter()
returns Event emitter associated to the FIWARE config. It reports:
IS-ERROR
Error on integration-service deployment
FIWARE_connected
FIWARE bridge websocket operational
[TOPIC]_data
Data has been received for [TOPIC]. It is delivered as a json argument for the callback
function send_message(topic, data)
topic Topic associate with the data
data Data to deliver as a javascript Object
function stop()
Stops integration-service operation
function launch(node_id)
node_id identifier used to query the error dictionary. If an error is registered the operation is aborted and the error return
returns An Object with the following properties:
color
'red' on error
message
non-null on error
event_emitter
The same value returned by get_event_emitter()
function new_config()
resets the global configuration for integration-service. All types & endpoints are discarded
function add_publisher(pub_id, topic_name, type_name)
pub_id identifier used to fill the error dictionary if there is an error
topic_name Topic associated to the publisher
type_name Type associated to the publisher. May not be registered at the call time
function add_subscriber(sub_id, topic_name, type_name)
sub_id identifier used to fill the error dictionary if there is an error
topic_name Topic associated to the subscriber
type_name Type associated to the subscriber. May not be registered at the call time

eu_flag

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

Readme

Keywords

Package Sidebar

Install

npm i is-web-api

Repository

github.com/eProsima/is-web-api

Homepage

github.com/eProsima/is-web-api#readme

Weekly Downloads

18

Version

1.0.1

License

MIT

Unpacked Size

61.3 kB

Total Files

11

Last publish

Collaborators

  • raul_sanchez_mateos
Try on RunKit
Report malware