rclnodejs - ROS2 Client Library for JavaScript

Branch	Linux Build	macOS Build	Windows Build
develop
master

rclnodejs is a Node.js client library for the Robot Operating System
(ROS 2). It provides a JavaScript API
and tooling for ROS 2 programming. TypeScript declarations, i.e., (*.d.ts),
are included to support use 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 = new rclnodejs.Node('publisher_example_node');
  const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
  publisher.publish(`Hello ROS 2 from rclnodejs`);
  node.spin();
});

Documentation

• Installation
• API Documentation
• Using TypeScript
• Examples
• FAQ and Known Issues
• Building from Scratch
• Contributing

Installation

Prerequisites

Before installing rclnodejs please ensure the following softare is installed and configured on your systemd:

• Nodejs version between 10.23.1 - 12.x.

• ROS 2 SDK for details.
  DON'T FORGET TO SOURCE THE ROS 2 SETUP FILE

Installing rclnodejs

Install the rclnodejs version that is compatible with your version of ROS 2 (see table below).

For the most current version of rclnodejs run:

npm i rclnodejs

To install a specific version of rclnodejs use:

npm i rclnodejs@x.y.z

• Note: to install rclnodejs from GitHub: add "rclnodejs":"RobotWebTools/rclnodejs#<branch>" to your package.json depdendency section.

API Documentation

API documentation is generated by jsdoc and can be viewed in the docs/ folder or on-line. To create a local copy of the documentation run npm run docs.

Using rclnodejs with TypeScript

rclnodejs API can be used in TypeScript projects. You can find the TypeScript declaration files (*.d.ts) in the types/ folder.

Your tsconfig.json file should include the following compiler options:

{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node",
    "target": "es6"
    // your additional options here
  }
}

Here's a short rclnodejs TypeScript example:

import * as rclnodejs from 'rclnodejs';
rclnodejs.init().then(() => {
  const node = new rclnodejs.Node('publisher_example_node');
  const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
  publisher.publish(`Hello ROS 2 from rclnodejs`);
  node.spin();
});

The benefits of using TypeScript become evident when working with more complex use-cases. ROS messages are defined in the types/interfaces.d.ts module. This module is updated as part of the generate-messages process described in the next section.

ROS2 Interface Message Generation (important)

ROS components communicate by sending and receiving messages described
by the interface definition language (IDL). ROS client libraries such as
rclnodejs are responsible for converting these IDL message descriptions
into source code of their target language. For this, rclnodejs provides
the generate-messages npm script that reads in the IDL
messages files of a ROS environment and generates corresponding JavaScript
message interface files. Additionally, the tool generates the TypeScript
interface.d.ts file containing declarations for every IDL message file
processed.

Learn more about ROS interfaces and IDL here.

In the following example rclnodejs loads a generated JavaScript message file corresponding to the ROS `std_msgs/msg/String' definition.

import * as rclnodejs from 'rclnodejs';
let stringMsgObject = rclnodejs.createMessageObject('std_msgs/msg/String');
stringMsgObject.data = 'hello world';

Maintaining Generated JavaScript Message Files

Message files are generated as a post-install step of the rclnodejs
installation process. Thereafter, you will need to manually run the
message generation script when new ROS message packages are installed
for which your ROS2-nodejs project has a dependency.

Running generate-messages Utility

To use generate-messages from your Nodejs package, create an npm
script entry in your package.json file as shown:

"scripts": {
  "generate-messages": "generate-messages"
  // your other scripts here
}

To run the script use npm as follows:

npm run generate-messages

The newly generated JavaScript files can be found at
<yourproject>/node_modules/rclnodejs/generated/.

Contributing

Please read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed to rclnodejs!

License

This project abides by the Apache License 2.0.