https://github.com/eprosima/is-web-api
https://github.com/eprosima/is-web-api
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/eprosima/is-web-api
- Owner: eProsima
- Created: 2021-03-31T07:02:27.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-06-15T09:06:02.000Z (about 3 years ago)
- Last Synced: 2025-05-19T20:17:28.109Z (about 1 year ago)
- Language: JavaScript
- Size: 65.4 KB
- Stars: 1
- Watchers: 5
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# is-web-api: Integration Service Web API
This project is part of [DIH^2](http://www.dih-squared.eu/). The main goal is provide WebSocket interoperability with
[ROS2](https://docs.ros.org/) and [FIWARE](https://fiware-orion.readthedocs.io/en/master/).
This library was created to service the [Node-RED ROS 2 Plugin](https://github.com/eProsima/node-red-ros2-plugin.git)
that provides Node-RED nodes associated with ROS2 and FIWARE endpoints.
## Contents
- [Background](#background)
- [Install](#install)
- [Interface APIs](#apis)
+ [ROS2 APIs](#ros2-apis)
+ [FIWARE APIs](#fiware-apis)
## Background
The interoperability between the pluging and the ROS2 and FIWARE Broker environments is achieved using [WebSocket](https://websockets.spec.whatwg.org//) bridges to them.
These bridges are generated using [Integration-Service](https://integration-service.docs.eprosima.com/en/latest/) an
[eProsima](https://www.eprosima.com/) 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](https://raw.githubusercontent.com/eProsima/node-red-ros2-plugin/master/docker/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](https://docs.ros.org/en/humble/Installation.html)
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](https://nodejs.org/en/download/package-manager).
Some package managers constrain the user to a specific version of Node.js. The Node.js [site](https://nodejs.org/en/download)
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](https://nodered.org/docs/getting-started/local).
The Dockerfile favors the easiest procedure which relies on `npm` (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](https://integration-service.docs.eprosima.com/en/latest/installation_manual/installation_manual.html#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](https://colcon.readthedocs.io)
As ROS2 it is necessary to source and
[overlay](https://colcon.readthedocs.io/en/released/developer/environment.html).
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
```
### Library installation
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. `npm` 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.
### ROS2 APIs
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:
- 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:
```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:
- 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
***
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