rclnodejs

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

Prerequisites

Node.js

• Node.js version >= 16.13.0.

ROS 2 SDK

• See the ROS 2 SDK Installation Guide for details.
• DON'T FORGET TO SOURCE THE ROS 2 STARTUP FILES

Install rclnodejs

Install the rclnodejs version that is compatible with your installed 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 - ROS 2 Version Compatibility

| RCLNODEJS Version | Compatible ROS 2 LTS | | :----------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | latest version (currently v1.5.0) | Kilted
Jazzy
Humble |

Documentation

API documentation is available online.

JavaScript Examples

The source for the following examples and many others can be found here.

Use complex message

  const publisher = node.createPublisher('sensor_msgs/msg/JointState', 'topic');
  publisher.publish({
    header: {
      stamp: {
        sec: 123456,
        nanosec: 789,
      },
      frame_id: 'main frame',
    },
    name: ['Tom', 'Jerry'],
    position: [1, 2],
    velocity: [2, 3],
    effort: [4, 5, 6],
  });

Create a subscription

const rclnodejs = require('../index.js');

// Create a ROS node and then print out the string message received from publishers
rclnodejs.init().then(() => {
  const node = rclnodejs.createNode('subscription_example_node');

  node.createSubscription('std_msgs/msg/String', 'topic', (msg) => {
    console.log(`Received message: ${typeof msg}`, msg);
  });

  rclnodejs.spin(node);
});

Create a service

  node.createService('example_interfaces/srv/AddTwoInts', 'add_two_ints', (request, response) => {
    console.log(`Incoming request: ${typeof request}`, request);
    let result = response.template;
    result.sum = request.a + request.b;
    console.log(`Sending response: ${typeof result}`, result, '\n--');
    response.send(result);
  });

Send a request in a client

  const client = node.createClient('example_interfaces/srv/AddTwoInts', 'add_two_ints');
  const request = {
    a: Math.floor(Math.random() * 100),
    b: Math.floor(Math.random() * 100),
  };

  console.log(`Sending: ${typeof request}`, request);
  client.sendRequest(request, (response) => {
    console.log(`Result: ${typeof response}`, response);
  });

Check out more examples.

Using rclnodejs with TypeScript

In your node project install the rclnodejs package as described above. You will also need the TypeScript compiler and node typings installed.

  npm install typescript @types/node -D

In your project's tsconfig.json file include the following compiler options:

{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node",
    "target": "es6",
    ...
  }
}

Here's an earlier JavaScript example reimplemented 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);
});

Type-aliases for the ROS2 messages can be found in the types/interfaces.d.ts file. To use a message type-alias follow the naming pattern <pkg_name>.[msg|srv]., e.g., sensor_msgs.msg.LaserScan or the std_msgs.msg.String as shown below.

const msg: rclnodejs.std_msgs.msg.String = {
  data: 'hello ROS2 from rclnodejs',
};

Check out more TypeScript demos.

Note that the interface.d.ts file is updated each time the generate_messages.js script is run.

Using rclnodejs with Electron

Check out demos.

License

Apache License Version 2.0