Branch | Linux Build | macOS Build | Windows Build |
---|---|---|---|
develop | |||
master |
rclnodejs
is a Node.js client for the Robot Operating System (ROS 2). It provides a simple and easy JavaScript API for ROS 2 programming. TypeScript declarations are included to support use of rclnodejs in TypeScript projects.
Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
const rclnodejs = require('rclnodejs');
rclnodejs.init().then(() => {
const node = rclnodejs.createNode('publisher_example_node');
const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
publisher.publish(`Hello ROS 2 from rclnodejs`);
rclnodejs.spin(node);
});
Node.js
- Node.js version between 8.12 - 12.x.
ROS 2 SDK
- See the ROS 2 SDK Installation Guide for details.
- DON'T FORGET TO SOURCE THE ROS 2 STARTUP FILES
Install the rclnodejs version that is compatible with your version of ROS 2 (see table below).
Run the following command for the most current version of rclnodejs
npm i rclnodejs
or to install a specific version of rclnodejs use
npm i rclnodejs@x.y.z
RCLNODEJS Version | Compatible ROS 2 Release |
---|---|
0.17.0 (current) (API) | Foxy Fitzroy / Eloquent Elusor |
0.10.3 | Dashing Diademata - Patch 4 |
- Note: to install rclnodejs from GitHub: add
"rclnodejs":"RobotWebTools/rclnodejs#<branch>"
to yourpackage.json
depdendency section.
The API documentation is generated by jsdoc
. To create a local copy run npm run docs
. Alternatively you can use the prebuilt api documentation found in the docs/
folder or view the on-line version in your browser.
TypeScript declaration files (*.d.ts) are included to support developers that wish to use rclnodejs in TypeScript projects.
In your node project, in addition to installing the rclnodejs package, you will need to install the TypeScript compiler and node typings.
npm install typescript @types/node -D
Your tsconfig.json file should include the following compiler options:
{
"compilerOptions": {
"module": "commonjs",
"moduleResolution": "node",
"target": "es6"
// your additional options here
}
}
Here's a simple example implemented in TypeScript.
import * as rclnodejs from 'rclnodejs';
rclnodejs.init().then(() => {
const node = rclnodejs.createNode('publisher_example_node');
const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
publisher.publish(`Hello ROS 2 from rclnodejs`);
rclnodejs.spin(node);
});
The benefits of using TypeScript become evident when working with more complex use-cases. The ROS 2 messages are defined in the types/interfaces.d.ts
module. This module is updated as part of the generate_messages
process. Here's a trivial example of working with a String msg.
const msg: rclnodejs.std_msgs.msg.String = {
data: 'hello ROS2 from rclnodejs',
};
1.Install ROS 2 from binary package.
ROS 2 is a cross-platform system, which covers Linux, macOS and Windows, and the rclnodejs
module is developed against the master
branch of ROS 2. You can download the latest binary packages from ROS 2 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, e.g. crystal-clemmys, please see the section `Running on Stable Release of ROS 2).
2.Build ROS 2 from scratch.
Alternatively, you can build ROS 2 from scratch. Please select the platform you want to work on, then reference the instructions of Linux/macOS/Windows to build ROS 2 (please build wiht flag --merge-install
).
Notice:
rclnodejs
should only be used with node versions between 8.12 - 12.99. The lowest LTS Node.js we used to verify the unit tests is 8.12.0
. And there is a known issue installing rclnodejs with versions of node >= 13.0.
The Node.js
version we selected is the LTS Erbium
(12.x). You can install it:
- Download from Node.js offical website, and install it.
- Use the Node Version Manager (nvm) to install it.
Open a terminal, and input:
git clone https://github.com/RobotWebTools/rclnodejs.git
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%
The test suite is implemented using the mocha JavaScript test framework for node.js. Run the unit tests:
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%
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.
To run with google's AddressSanitizer tool, build with -fsanitize=address
flag,
CXXFLAGS=-fsanitize=address node-gyp build --debug
ASAN needs to be loaded at the start of the process, since rclnodejs is a dynamically loaded library, it will not do so by default. To workaround this, run node with LD_PRELOAD
to force ASAN to be loaded.
LD_PRELOAD=$(g++ -print-file-name=libasan.so) node node_modules/.bin/mocha test/test-publisher.js
Due to v8's garbage collector, there may be false positives in the leak test, to remove them as much as possible, there is a simple helper script to run gc on exit. To use it, the --expose-gc
flag needs to be set in node, then run mocha with -r test/gc-on-exit.js
e.g.
LD_PRELOAD=$(g++ -print-file-name=libasan.so) node --expose-gc node_modules/.bin/mocha -r test/gc-on-exit.js test/test-publisher.js
Note: Tests that forks the current process like test-array.js
will not run gc when they exit. They may report many false positive leaks.
ASAN may report leaks in ref-napi and other modules, there is a suppression file you can use to hide them
LSAN_OPTIONS=suppressions=suppr.txt node --expose-gc node_modules/.bin/mocha -r test/gc-on-exit.js test/test-publisher.js
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.
Special thanks to the people who contribute.
This project abides by Apache License 2.0.