Skip to content

Latest commit

 

History

History
114 lines (81 loc) · 6.56 KB

README.md

File metadata and controls

114 lines (81 loc) · 6.56 KB
Raw

ros2-web-bridge Build StatusBuild statusnpmlicense

⚠️ Warning ⚠️

This package is not actively maintained. Please use the rosbridge_suite package instead for your ROS 2 websocket communication needs.

ros2-web-bridge vs rosbridge_suite

  • rosbridge_suite (or rosbridge_server) is recommended for communicating with ROS 2 over websockets. It is written in Python and is actively maintained by the ROS web working group.
  • ros2-web-bridge (this project) is an earlier attempt at enabling ROS 2 communication over websockets. It is written in JavaScript, and requires Node.js to be installed on your robot. It cannot be installed via rosdep or apt like a regular ROS package, and must be cloned and built locally.

Server Implementations of the rosbridge v2 Protocol

ros2-web-bridge, which leverages the rclnodejs client, provides a JSON interface to ROS 2 by adopting the rosbridge v2 protocol. The bridge can process commands through JSON tuneled over WebSockets.

ROS 2 support

The ros2-web-bridge SUPPORTS the latest ROS 2 stable release by default (currently Dashing Patch 2), please visit the relase channel to check out the information.

Any one who wants to run on the nightly build of ROS 2, please change the dependencies section of package.json file to install other version of rclnodejs.

Supported Clients

A client is a program that communicates with ros2-web-bridge using its JSON API. Clients include:

  • roslibjs - A JavaScript API, which communicates with ros2-web-bridge over WebSockets.

Install

  1. Prepare for ROS 2 Please reference the documentation to install ROS 2.
  2. Install Node.js You can install Node.js:
    • Download from Node.js offical website, and install it.
    • Use the Node Version Manager (nvm) to install it.
  3. Clone and install dependencies Note that a ROS 2 installation has to be sourced before installing dependencies. 
    $ git clone https://github.com/RobotWebTools/ros2-web-bridge.git
$ cd ros2-web-bridge
$ source /opt/ros/$DISTRO/setup.sh  # or a source installation
$ npm install

Run Examples

  1. Make sure to source a ROS 2 installation, e.g.: 
    $ source /opt/ros/$DISTRO/setup.sh  # or a source installation
  2. Start ros2-web-bridge module: 
    $ node bin/rosbridge.js
    If you want to start in client mode (i.e. connecting the bridge to an existing websocket server), do this instead: 
    $ node bin/rosbridge.js --address ws://<address>:<port>
  3. Start the express server: 
    $ cd examples && node index.js
  4. Open your browser, and navigate to URL: http://localhost:3000/html/publisher.html

Not supported op

Some experimental operations defined by rosbridge v2.0 protocol specification are not supported by ros2-web-bridge now, please check out the list:

and the authentication

Compability with rosbridge v2.0 protocol

We are trying to obey the rosbridge v2 protocol, but there are still some operation commands which can not follow the spec. The table below lists the differences:

opreations rosbridge v2.0 protocol spec ros2-web-bridge implementation
publish If the msg is a subset of the type of the topic, then a warning status message is sent and the unspecified fields are filled in with defaults. If the subset of the msg is unspecified, then an error status message is sent and this message is dropped.
subscribe The type of the topic is optional. The type of the topic must be offered.

If you use roslibjs as the client running in the browser, please reference the code snippet below:

  • Subscribe to a topic. 
    // Define a topic with its type.
var example = new ROSLIB.Topic({
  ros : ros,
  name : '/example_topic',
  messageType : 'std_msgs/String'
});

// Subscribe to a topic.
example.subscribe(function(message) {
  console.log(`Receive message: ${message}`);
});

Contributing

If you want to contribute code to this project, first you need to fork the project. The next step is to send a pull request (PR) for review. The PR will be reviewed by the project team members. Once you have gained "Look Good To Me (LGTM)", the project maintainers will merge the PR.

License

This project abides by Apache License 2.0.