is-web-api
v1.0.1
Websocket interfaces to ROS2 and FIWARE Context Broker
0/weekUpdated 2 years agoMITUnpacked: 61.3 KB
Published by raul_sanchez_mateos
npm install is-web-apiis-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.
$3
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.
1. 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:
``bash`
$ 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
1. Install Node-RED. Follow the official Node-RED installation guide.
The Dockerfile favors the easiest procedure which relies on (default Node.js package manager) which is
available after Node.js installation step:
`bash`
$ npm install -g node-red
1. 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:
`bash
$ 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:
`bash`
$ . /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:
`bash`
$ integration-service --help
$3
Once all the dependencies are available we can deploy the plugin via npm:
+ From npm repo:
`bash`
$ npm install -g is-web-api
+ From sources. allows direct deployment from github repo:
`bash`
$ 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.
`bash
$ 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.
$3
They are accessible using:
`js`
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:
|
| 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:
|
| 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:
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:
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 |
$3
They are accessible using:
`js``
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:
|
| 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:
|
| 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 |
*
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