Introducing The rclnodejs-cli Tools for ROS 2 JavaScript Coders

For developers interested in implementing ROS 2 solutions using JavaScript or TypeScript, the rclnodejs package (ROS client library nodejs) provides a complete Nodejs JavaScript binding and TypeScript declarations to the ROS 2 API. A companion Nodejs package rclnodejs-cli, was released last year to provide commandline tools to help when using rclnodejs. Let’s take a look at the rclnodejs-cli tools.

Prerequisites

Before we begin you’ll need to following software installed to run the rclnodejs-cli tools:

• Nodejs version between 10.22–17
• ROS 2 Galactic or Foxy (LTS) releases
• optional: ROS 2 colcon build tool required for the create-packagetool

If you lack a ROS 2 installation know that it is pretty simple to setup in a Linux environment. A few months ago I setup Linux Ubuntu 20.04 and ROS 2 galactic distros in WSL2 on my Windows 11 machine for a really convenient development environment. See this youtube demo to see the ROS tools running in WSL. Lastly the screenshots in this article are from this environment using the new Windows Terminal.

Running rclnodejs-cli

To see tools available from rclnodejs-cli run the following command from a terminal usingnpx . Alternatively you can install rclnodejs-cli as a global package and run it directly without using npx.

npx rclnodejs-cli -h

generate-ros-messages Tool

The first tool we will look at is the generate-ros-messages tool. Use this tool when you add new interface packages to your ROS environment for which your Nodejs project uses.

This tool searches your ROS 2 environment for interface definitions files, e.g., *.msg and *.srv. For each interface file the tool generates a similarly named JavaScript file that rclnodejs uses to serialize and deserialize ROS 2 messages it sends and receives in a ROS graph. You can find all of the generated serialization files in your Nodejs project’s node_modules/rclnodejs/generated folder.

Usage

Run the generate-ros-messages command in the root directory of your Nodejs package, i.e., the directory containing the package.json file. The Nodejs package must haverclnodejs already installed as a dependent package.

cd <your-nodejs-package>
npx rclnodejs-cli generate-ros-messages

create-package Tool

The create-package tool creates hybrid ROS2-Nodejs packages that can coexist and participate with other ROS2 packages in a ROS2 workspace. Additionally these packages can be run and orchestrated using the ROS2 launch facility. A ROS2-Nodejs package consist of a traditional ROS2 package, specifically an ament-cmake ROS2 package, overlaid with a Nodejs package.

Key Features

• Creates a ROS2 ament_cmake package and overlays it with a custom Nodejs package.
• --typescript commandline option to configure the package for use with TypeScript.
• Installs the ROS2 JavaScript client library, rclnodejs as a runtime dependency.
• Creates an example JavaScript/TypeScript ROS2 publisher node and ROS2 launch-description.
• Customized CMakeList.txt install() rules to install key runtime files to the package share/ folder

Usage

To view the create-package tool arguments and options enter the following command from a terminal:

npx rclnodejs-cli create-package -h

Now let’s create a simple ROS2-Nodejs package configured to support TypeScript coding. If you do would rather use JavaScript omit the --typescript flag.

npx rclnodejs-cli create-package mypkg --typescript

Note: Package names should conform to the ROS2 Patterns and Conventions, e.g., use _ underscores as separators in a package name instead of '-' dashes.

The new package directory content should be similar to this listing:

mypkg/
  CMakeLists.txt
  __init__.py
  launch/
    mypkg.launch.py
  node_modules/
  package.json
  package.xml
  src/
    index.ts
  tsconfig.json

1. Compile the example TypeScript src/index.ts file, an example ROS node that publishes a String message.

npm run build

2. Use the colcon build utility to install the key JavaScript resources into the ./install/share/ folder.

colcon build

Your package folder will now include the standard ROS2 package directories: build/, install/ and log/. The install/ directory includes configuration scripts and if you look deep into the install/mypkg/share/mypkg folder you will see the install() rules in the CMakeLists.txt have installed the key JavaScript resources from the src/ and launch/ directories.

Tip — Alway run the colcon buildcommand when you are actively developing and using launch files from your project. This will ensure the launch includes your latest code.

3. Add your new ROS2-Nodejs package to your ROS environment.

From your mypkg root folder run:

Linux
source install/setup.bash

Windows
install\setup.bat

4. Verify that the ROS2-Nodejs package is part of your ROS2 environment using the ros2 CLI command.

ros2 pkg list

This command will output a long list of the packages in your ROS2 environment. Scroll through the list and verify it contains the mypkg package.

5. Launch mypkg.launch.py

We can now use the ros2 launch command to run the mypkg.launch.py launch-description. This launch file defines how to startup the example app in our ROS2-Nodejs package. The example app creates a ROS2 node and publisher that sends a std_msgs/msg/Stringmessage every second to the topic named foo. See src/index.ts for the TypeScript implementation details.

Launch example.launch.py as shown below:

ros2 launch mypkg example.launch.py

To view the messages being published to the foo topic, open a separate shell configured with your ROS2 environment and enter:

ros2 topic echo foo

A message should appear every second.

Conclusion

I hope this introduction to rclnodejs-cli is helpful and saves you time and hassle with your ROS 2 development. rclnodejs-cli is an open-source project and can be found here in Github.

Please consider liking this tutorial and following me here and on Twitter @ros2jsguy