rclnodejs - ROS Client Library for JavaScript language

Branch	Linux Build	macOS Build	Windows Build
develop
master

Build Environment

Get ready for ROS 2

1.Build from scratch.

ROS is a cross-platform system, which covers Linux, macOS and Windows, and the rclnodejs module is developed on the master branch of ROS, so you have to build ROS from scratch at the present stage. Please select the platform you want to work on, then reference the instruction to build ROS (please build wiht flag --merge-install).

• Linux
• macOS
• Windows

2.Get the binary package.

Alternatively, you can download the latest binary package of ROS2 from here and follow the instructions to setup the environment.

• Linux
• macOS
• Windows

Install Node.js

Notice: rclnodejs use some new feature of ECMAScript 6, we recommend using the latest LTS Node.js. The lowest LTS Node.js we used to verify the unit tests is 6.10.0. Your Node.js version should not be lower than this verion.

The Node.js version we selected is the latest LTS Carbon (8.x). You can install it:

• Download from Node.js offical website, and install it.
• Use the Node Version Manager (nvm) to install it.

Get Code

Open a terminal, and input:

git clone https://github.com/RobotWebTools/rclnodejs.git

then enter the folder rclnodejs, and get the submodule:

git submodule update --init --recursive

Build Module

Before you build the module, you should make sure the ROS2 environments were loaded. You can check if the AMENT_PREFIX_PATH environment variable was set:

• For Windows: echo %AMENT_PREFIX_PATH% in the command prompt.

• For Linux and macOS: echo $AMENT_PREFIX_PATH in the terminal.

If the AMENT_PREFIX_PATH is unset, you should load the ROS2 environments:

• For Windows, open the command prompt and run

  call <path\to\ros2>\install\local_setup.bat

• For Linux and macOS, open the terminal and run:

  source <path/to/ros2>/install/local_setup.bash

This Node.js module is built by node-gyp, all you have to do is just to run the following command:

npm install

Windows-specific: make sure Python 2.x interpreter is first searched in your PATH before running the command. You can change it temporarily by:

  set PATH=<path\to\python 2.x>;%PATH%

Install rclnodejs by npm

Install from npmjs

Please run npm i rclnodejs to install the latest version OR npm i rclnodejs@<version> to install a specific version.

Install from GitHub

You can also install rclnodejs from Github to experience the latest features, please add the following line into the dependencies section of your package.json file.

"rclnodejs": "RobotWebTools/rclnodejs"

We don't offer a release of rclnodejs against a specific release of ROS 2, e.g. bouncy-bolson, as the one pubilshed on npmjs is always built against the master branch of ROS 2, but we do have the branch which is against a release of ROS 2 on GitHub. You can checkout the branches we have, then add it to your package.json, e.g. if you want to use ROS 2 Bouncy Bolson:

"rclnodejs": "RobotWebTools/rclnodejs#bouncy-bolson"

Run Unit Test

mocha is a javascript test framework for node.js, simply run the following command to run the unit test under test folder:

npm run test

Windows-specific: the tests requires in a Microsoft Visual Studio Native Tools command prompt, and also make sure Python 3.x interpreter is first searched in your PATH before running te test. You can change it temporarily by:

  set PATH=<path\to\python 3.x>;%PATH%

How To Use

After building this module, you just need to follow the normal way to use it as a Node.js module.

const rclnodejs = require('../index.js');

rclnodejs.init().then(() => {
  let String = rclnodejs.require('std_msgs').msg.String;
  const node = rclnodejs.createNode('publisher_example_node');
  const publisher = node.createPublisher(String, 'topic');
  let msg = new String();

  setInterval(function() {
    const str = 'Hello ROS2.0';
    msg.data = str;
    publisher.publish(msg);
  }, 1000);

  rclnodejs.spin(node);
});

There are also several useful examples under the example folder, which will show you how to use some important features, including timer/subscription/publisher/client/service, in rclnodejs. You are encouraged to try these examples to understand them.

API Specification

The API spec is generated by jsdoc, you can manually run npm run docs to create them by yourself, or just use the existing documents under docs folder. To visit the on-line version, please navigate to http://robotwebtools.org/rclnodejs/docs/index.html in your browser.

Experimental - Deprecated

• actionlib - as the rcl library has implemented the action related functions, we are going to drop this one and we don't garantee the current actionlib can work with rclcpp.

Get Involved

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.

Contributors

Special thanks to the people who contribute.

• martins-mozeiko

License

This project abides by Apache License 2.0.