rclnodejs - The ROS 2 Client Library for JavaScript

ROS Distro*	Status
Rolling Kilted Jazzy Humble

* rclnodejs development and maintenance is limited to the ROS 2 LTS releases and the Rolling development branch

rclnodejs is a Node.js client library for ROS 2 that provides comprehensive JavaScript and TypeScript APIs for developing ROS 2 solutions.

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
• rclnodejs-cli
• API Documentation
• Electron-based Visualization
• Using TypeScript
• ROS2 Interface Message Generation
• Efficient Usage Tips
• FAQ and Known Issues
• Building from Scratch
• Contributing

Installation

Prerequisites

• Node.js version >= 16.13.0
• ROS 2 SDK - Don't forget to source the setup file

Install rclnodejs

npm i rclnodejs

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

Try the examples to get started.

rclnodejs-cli

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]

Options:
  -h, --help                               display help for command

Commands:
  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 available online or generate locally with npm run docs.

Electron-based Visualization

Create rich, interactive desktop applications using Electron and web technologies like Three.js. Build 3D visualizations, monitoring dashboards, and control interfaces that run on Windows, macOS, and Linux.

Try the electron_demo/turtle_tf2 demo for real-time coordinate frame visualization with dynamic transforms and keyboard-controlled turtle movement. More examples in electron_demo.

Using rclnodejs with TypeScript

TypeScript declaration files are included in the types/ folder. Configure your tsconfig.json:

{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node",
    "target": "es2020",
  },
}

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();
});

See TypeScript demos for more examples.

ROS2 Interface Message Generation

ROS client libraries convert IDL message descriptions into target language source code. rclnodejs provides the generate-ros-messages script to generate JavaScript message interface files and TypeScript declarations.

Example usage:

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

Running Message Generation

Run the message generation script when new ROS packages are installed:

npx generate-ros-messages

Generated files are located at <yourproject>/node_modules/rclnodejs/generated/.

IDL Message Generation

In addition to the standard ROS2 message generation (.msg, .srv, and .action), rclnodejs provides advanced support for generating JavaScript message files directly from IDL (Interface Definition Language) files. This feature is particularly useful when working with custom IDL files or when you need more control over the message generation process.

To generate messages from IDL files, use the generate-messages-idl npm script:

npm run generate-messages-idl

Contributing

Please read the Contributing Guide before making a pull request.

Thanks to all contributors!

License

This project abides by the Apache License 2.0.