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
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.
To see tools available from rclnodejs-cli run the following command from a terminal using
npx . Alternatively you can install rclnodejs-cli as a global package and run it directly without using npx.
npx rclnodejs-cli -h
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.
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 have
rclnodejs already installed as a dependent package.
npx rclnodejs-cli generate-ros-messages
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.
- Creates a ROS2 ament_cmake package and overlays it with a custom Nodejs package.
--typescriptcommandline option to configure the package for use with TypeScript.
install()rules to install key runtime files to the package share/ folder
To view the
create-package tool arguments and options enter the following command from a terminal:
npx rclnodejs-cli create-package -h
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:
- Compile the example TypeScript src/index.ts file, an example ROS node that publishes a String message.
npm run build
Your package folder will now include the standard ROS2 package directories:
install/ directory includes configuration scripts and if you look deep into the
install/mypkg/share/mypkg folder you will see the
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.
mypkg root folder run:
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
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
src/index.ts for the TypeScript implementation details.
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.
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