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 v0.28.1) | Humble
Jazzy |

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

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',
};

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

License

Apache License Version 2.0