Rclnodejs Save

Node.js version of ROS 2.0 client

Project README

rclnodejs - ROS2 Client Library for JavaScript npmCoverage StatusnpmGitHub licensenodenpm type definitionscode style: prettier

BRANCH Linux Windows
develop GitHub Workflow Status GitHub Workflow Status
humble-hawksbill GitHub Workflow Status GitHub Workflow Status (branch)
galactic-geochelone GitHub Workflow Status GitHub Workflow Status (branch)
foxy-fitzroy GitHub Workflow Status GitHub Workflow Status (branch)

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`);




Before installing rclnodejs please ensure the following software is installed and configured on your system:

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 [email protected]
RCLNODEJS Version Compatible ROS 2 Release
0.21.3 (current) (API) Humble Hawksbill
Galactic Geochelone
Foxy Fitzroy
Eloquent Elusor
0.10.3 Dashing Diademata - Patch 4
  • Note: to install rclnodejs from GitHub: add "rclnodejs":"RobotWebTools/rclnodejs#<branch>" to your package.json depdendency section.


rclnodejs-cli is a companion project we recently launched to provide a commandline interface to a set of developer tools for working with this rclnodejs. You may find rclnodejs-cli particularly useful if you plan to create ROS 2 node(s) and launch files for working with multiple node orchestrations.

           _                 _       _
  _ __ ___| |_ __   ___   __| | ___ (_)___
 | '__/ __| | '_ \ / _ \ / _` |/ _ \| / __|
 | | | (__| | | | | (_) | (_| |  __/| \__ \
 |_|  \___|_|_| |_|\___/ \__,_|\___|/ |___/
Usage: rclnodejs [command] [options]

  -h, --help                               display help for command

  create-package [options] <package-name>  Create a ROS2 package for Nodejs development.
  generate-ros-messages                    Generate JavaScript code from ROS2 IDL interfaces
  help [command]                           display help for command

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`);

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-ros-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 npm binarygenerate-ros-messages script that reads the IDL message 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 each IDL message file.

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 rclnodejs message generation script when new ROS message packages are installed for which your ROS2-nodejs project has a dependency.

Running generate-ros-messages Utility

To run the generate-ros-messages script from your Nodejs package, use the npx utility included in your Nodejs installation.

npx generate-ros-messages

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


Please read the Contributing Guide before making a pull request.

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


This project abides by the Apache License 2.0.

Open Source Agenda is not affiliated with "Rclnodejs" Project. README Source: RobotWebTools/rclnodejs
Open Issues
Last Commit
2 weeks ago

Open Source Agenda Badge

Open Source Agenda Rating