amikhalev / rclnodejs

Node.js version of ROS 2.0 client

rclnodejs - ROS Client Library for JavaScript language

Branch	Linux Build	macOS Build	Windows Build
develop
master

Match with ROS 2.0 Stable Releases

If you want to select a stable release of ROS 2.0 as your platform, please check the table below.

ROS 2.0 release	NPM version
Dashing Diademata Patch Release 3	0.10.2
Dashing Diademata Patch Release 2	0.10.1
Dashing Diademata Patch Release 1	0.10.0
Crystal Clemmys Patch Release 1/2/3/4	0.9.0
Bouncy Bolson	0.3.5

• Install from npmjs: run npm i rclnodejs@<version> to install a specific version.

• Install from GitHub: add "rclnodejs":"RobotWebTools/rclnodejs#<branch>" to your package.json.

Build from Scratch

Get ready for ROS 2

1.Install ROS 2.0 from binary package.

ROS 2.0 is a cross-platform system, which covers Linux, macOS and Windows, and the rclnodejs module is developed against the master branch of ROS 2.0. You can download the latest binary packages from ROS 2.0 build farm and follow the instructions of Linux/macOS/Windows to setup the environment (If you want to run your apps on a stable release of ROS 2.0, e.g. crystal-clemmys, please see the section Running on Stable Release of ROS 2.0).

2.Build ROS 2.0 from scratch.

Alternatively, you can build ROS 2.0 from scratch. Please select the platform you want to work on, then reference the instructions of Linux/macOS/Windows to build ROS 2.0 (please build wiht flag --merge-install).

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 COLCON_PREFIX_PATH environment variable was set:

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

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

If the COLCON_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%

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/time/node graph. 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.

Troubleshooting

Maximum call stack size exceeded error when running in Jest

When running tests in Jest, you may see an error like this:

RangeError: Maximum call stack size exceeded

      at debug (../node_modules/ref/node_modules/debug/src/debug.js:1:1)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:746:3)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)

This is caused by a bug in ref which happens when you require it multiple times. There is a fix available for ref but it's no longer being maintained and the author has not published it.

If it is required to use Jest, a solution would be to fork ref and use npm shrinkwrap to installed a patched version.

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
• Teo Koon Peng

License

This project abides by Apache License 2.0.