rclnodejs 1.8.2 → 1.9.0-alpha.0

package/README.md

@@ -1,27 +1,33 @@
-# rclnodejs [![Linux](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-x64-push-test.yml/badge.svg?branch=develop)](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-x64-push-test.yml?query=branch%3Adevelop)[![Linux](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-arm64-push-test.yml/badge.svg?branch=develop)](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-arm64-push-test.yml?query=branch%3Adevelop)
+# 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.
+`rclnodejs` is a Node.js client library for ROS 2 that provides JavaScript and TypeScript APIs for building ROS 2 applications.
 
-\* rclnodejs development and maintenance is limited to all active ROS 2 LTS releases and the Rolling development branch
+Supported ROS 2 distributions include Humble, Jazzy, Kilted, and Rolling.
 
-Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
-
-```JavaScript
+```javascript
 const rclnodejs = require('rclnodejs');
 rclnodejs.init().then(() => {
-  const node = rclnodejs.createNode('publisher_example_node');
+  const node = new rclnodejs.Node('publisher_example_node');
   const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
   publisher.publish(`Hello ROS 2 from rclnodejs`);
-  rclnodejs.spin(node);
+  node.spin();
 });
 ```
 
+This example assumes your ROS 2 environment is already sourced.
+
 ## Installation
 
 ### Prerequisites
 
 - [Node.js](https://nodejs.org/en/) version >= 16.13.0
-- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) - **Don't forget to [source the setup file](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)**
+- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html)
+
+Before installing or running rclnodejs, source your ROS 2 environment:
+
+```bash
+source /opt/ros/<distro>/setup.bash
+```
 
 ### Install rclnodejs
 
@@ -29,11 +35,17 @@ rclnodejs.init().then(() => {
 npm i rclnodejs
 ```
 
-- **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
+To install from GitHub instead of npm, run:
+
+```bash
+npm install RobotWebTools/rclnodejs#<branch>
+```
+
+Or add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependencies.
 
 ### Prebuilt Binaries
 
-rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This significantly speeds up installation and reduces dependencies.
+rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing the published npm package.
 
 **Supported Platforms:**
 
@@ -42,26 +54,39 @@ rclnodejs ships with prebuilt native binaries for common Linux configurations si
 - **Architectures:** x64, arm64
 - **Node.js:** >= 16.20.2 (N-API compatible)
 
-**Force Building from Source:**
+Installations outside this prebuilt matrix automatically fall back to building from source.
 
-If you need to build from source even when a prebuilt binary is available, set the environment variable:
+**Force Building from Source:**
 
 ```bash
 export RCLNODEJS_FORCE_BUILD=1
 npm install rclnodejs
 ```
 
-## Documentation
+## Documentation and Examples
 
-API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) is available online.
+- API documentation: [robotwebtools.github.io/rclnodejs/docs](https://robotwebtools.github.io/rclnodejs/docs/index.html)
+- Tutorials: [tutorials/](https://github.com/RobotWebTools/rclnodejs/tree/develop/tutorials)
+- JavaScript examples: [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example)
+- TypeScript demos: [ts_demo/](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo)
+- Electron demos: [electron_demo/](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo)
+- Companion CLI: [rclnodejs-cli](https://github.com/RobotWebTools/rclnodejs-cli/)
 
-## JavaScript Examples
+## Message Generation
 
-Try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started.
+rclnodejs generates JavaScript message interfaces and TypeScript declarations during installation for `rclnodejs > 1.5.0`. If you install additional ROS packages later, rerun the generator in your project:
+
+```bash
+npx generate-ros-messages
+```
+
+Generated files are written to `<your-project>/node_modules/rclnodejs/generated/`.
+
+This step is only needed after adding ROS packages that were not present when rclnodejs was installed.
 
 ## Using rclnodejs with TypeScript
 
-TypeScript declaration files are included in the `types/` folder. Configure your `tsconfig.json`:
+TypeScript declaration files are included in the package. In most projects, configuring your `tsconfig.json` is sufficient:
 
 ```jsonc
 {
@@ -73,33 +98,17 @@ TypeScript declaration files are included in the `types/` folder. Configure your
 }
 ```
 
-TypeScript example:
-
 ```typescript
 import * as rclnodejs from 'rclnodejs';
+
 rclnodejs.init().then(() => {
-  const node = rclnodejs.createNode('publisher_example_node');
+  const node = new rclnodejs.Node('publisher_example_node');
   const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
   publisher.publish(`Hello ROS 2 from rclnodejs`);
-  rclnodejs.spin(node);
+  node.spin();
 });
 ```
 
-See [TypeScript demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo) for more examples.
-
-**Note** that the interface.d.ts file is updated each time the generate_messages.js script is run.
-
-## 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.
-
-|                                                  Demo                                                   |                                                              Description                                                              |                                                           Screenshot                                                            |
-| :-----------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------: |
-|  **🐢 [turtle_tf2](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/turtle_tf2)**  |  Real-time coordinate frame visualization with turtle control. Features TF2 transforms, keyboard control, and dynamic frame updates.  |  ![turtle_tf2](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.png?raw=true)   |
-| **🦾 [manipulator](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/manipulator)** | Interactive two-joint robotic arm simulation. Features 3D joint visualization, manual/automatic control, and visual movement markers. | ![manipulator](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/manipulator/manipulator-demo.png?raw=true) |
-
-Explore more examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
-
 ## License
 
 Apache License Version 2.0

package/index.js

@@ -63,7 +63,10 @@ const {
 const ParameterClient = require('./lib/parameter_client.js');
 const errors = require('./lib/errors.js');
 const ParameterWatcher = require('./lib/parameter_watcher.js');
+const ParameterEventHandler = require('./lib/parameter_event_handler.js');
+const waitForMessage = require('./lib/wait_for_message.js');
 const MessageIntrospector = require('./lib/message_introspector.js');
+const MessageInfo = require('./lib/message_info.js');
 const ObservableSubscription = require('./lib/observable_subscription.js');
 const { spawn } = require('child_process');
 const {
@@ -85,7 +88,7 @@ async function getCurrentGeneratorVersion() {
   const jsonFilePath = path.join(generator.generatedRoot, 'generator.json');
 
   return new Promise((resolve, reject) => {
-    fs.open(jsonFilePath, 'r', (err) => {
+    fs.readFile(jsonFilePath, 'utf8', (err, data) => {
       if (err) {
         if (err.code === 'ENOENT') {
           resolve(null);
@@ -93,13 +96,11 @@ async function getCurrentGeneratorVersion() {
           reject(err);
         }
       } else {
-        fs.readFile(jsonFilePath, 'utf8', (err, data) => {
-          if (err) {
-            reject(err);
-          } else {
-            resolve(JSON.parse(data).version);
-          }
-        });
+        try {
+          resolve(JSON.parse(data).version);
+        } catch (parseErr) {
+          reject(parseErr);
+        }
       }
     });
   });
@@ -245,6 +246,12 @@ let rcl = {
   /** {@link ParameterWatcher} class */
   ParameterWatcher: ParameterWatcher,
 
+  /** {@link ParameterEventHandler} class */
+  ParameterEventHandler: ParameterEventHandler,
+
+  /** {@link MessageInfo} class */
+  MessageInfo: MessageInfo,
+
   /** {@link ObservableSubscription} class */
   ObservableSubscription: ObservableSubscription,
 
@@ -389,23 +396,35 @@ let rcl = {
 
     rclnodejs.init(context.handle, argv, context._domainId);
 
-    if (_rosVersionChecked) {
-      // no further processing required
-      return;
-    }
+    try {
+      if (_rosVersionChecked) {
+        // no further processing required
+        return;
+      }
 
-    const version = await getCurrentGeneratorVersion();
-    const forced =
-      version === null || compareVersions(version, generator.version(), '<');
-    if (forced) {
-      debug(
-        'The generator will begin to create JavaScript code from ROS IDL files...'
-      );
-    }
+      const version = await getCurrentGeneratorVersion();
+      const forced =
+        version === null || compareVersions(version, generator.version(), '<');
+      if (forced) {
+        debug(
+          'The generator will begin to create JavaScript code from ROS IDL files...'
+        );
+      }
 
-    await generator.generateAll(forced);
-    // TODO determine if tsd generateAll() should be here
-    _rosVersionChecked = true;
+      await generator.generateAll(forced);
+      // TODO determine if tsd generateAll() should be here
+      _rosVersionChecked = true;
+    } catch (error) {
+      try {
+        context.tryShutdown();
+      } catch (shutdownError) {
+        const initError =
+          error instanceof Error ? error : new Error(String(error));
+        initError.message += ` (rollback also failed: ${shutdownError.message})`;
+        throw initError;
+      }
+      throw error;
+    }
   },
 
   /**
@@ -448,6 +467,26 @@ let rcl = {
     node.spinOnce(timeout);
   },
 
+  /**
+   * Wait for a single message on a topic.
+   *
+   * Creates a temporary subscription, waits for the first message to arrive,
+   * and returns it. The temporary subscription is always cleaned up, even on
+   * timeout or error. The node must be spinning before calling this function.
+   *
+   * This is the rclnodejs equivalent of rclpy's `wait_for_message`.
+   *
+   * @param {function|string|object} typeClass - The ROS message type class.
+   * @param {Node} node - The node to create the temporary subscription on.
+   * @param {string} topic - The topic name to listen on.
+   * @param {object} [options] - Options.
+   * @param {number} [options.timeout] - Timeout in milliseconds. If omitted, waits indefinitely.
+   * @param {object} [options.qos] - QoS profile for the subscription.
+   * @returns {Promise<object>} - Resolves with the received message.
+   * @throws {Error} If timeout expires before a message arrives.
+   */
+  waitForMessage: waitForMessage,
+
   /**
    * Shutdown an RCL environment identified by a context. The shutdown process will
    * destroy all nodes and related resources in the context. If no context is

package/lib/action/client.js

@@ -51,6 +51,12 @@ class ActionClient extends Entity {
    * @param {QoS} options.qos.feedbackSubQosProfile - Quality of service option for the feedback subscription,
    *                                                  default: new QoS(QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_SYSTEM_DEFAULT, 10).
    * @param {QoS} options.qos.statusSubQosProfile - Quality of service option for the status subscription, default: QoS.profileActionStatusDefault.
+   * @param {boolean} options.enableFeedbackMsgOptimization - Enable feedback subscription content filter to
+   *    optimize the handling of feedback messages. When enabled, the content filter is used to configure
+   *    the goal ID for the subscription, which helps avoid the reception of irrelevant feedback messages.
+   *    An action client can handle up to 6 goals simultaneously with this optimization. If the number
+   *    of goals exceeds the limit or the RMW doesn't support content filter, optimization is automatically
+   *    disabled. Default: false.
    */
   constructor(node, typeClass, actionName, options) {
     super(null, null, options);
@@ -87,6 +93,15 @@ class ActionClient extends Entity {
       checkTypes: true,
     };
 
+    // Enable feedback subscription content filter optimization.
+    // Only supported on ROS2 Rolling and only effective when the native
+    // binding provides the required functions AND the RMW implementation
+    // actually supports content filtering on the feedback subscription.
+    this._enableFeedbackMsgOptimization =
+      this._options.enableFeedbackMsgOptimization === true &&
+      DistroUtils.getDistroId() >= DistroUtils.DistroId.ROLLING &&
+      typeof rclnodejs.actionConfigureFeedbackSubFilterAddGoalId === 'function';
+
     let type = this.typeClass.type();
 
     this._handle = rclnodejs.actionCreateClient(
@@ -126,6 +141,13 @@ class ActionClient extends Entity {
         }
 
         this._goalHandles.set(uuid, goalHandle);
+        this._feedbackSubFilterAddGoalId(goalHandle.goalId);
+      } else {
+        // Clean up feedback callback for rejected goals
+        let uuid = ActionUuid.fromMessage(
+          this._sequenceNumberGoalIdMap.get(sequence)
+        ).toString();
+        this._feedbackCallbacks.delete(uuid);
       }
 
       this._pendingGoalRequests.get(sequence).setResult(goalHandle);
@@ -199,6 +221,9 @@ class ActionClient extends Entity {
             status === ActionInterfaces.GoalStatus.STATUS_ABORTED
           ) {
             this._goalHandles.delete(uuid);
+            this._feedbackSubFilterRemoveGoalId(
+              statusMessage.goal_info.goal_id
+            );
           }
         }
       } else {
@@ -387,6 +412,8 @@ class ActionClient extends Entity {
       this._removePendingCancelRequest(sequenceNumber)
     );
 
+    this._feedbackSubFilterRemoveGoalId(goalHandle.goalId);
+
     return deferred.promise;
   }
 
@@ -436,9 +463,10 @@ class ActionClient extends Entity {
       goalHandle.status = result.status;
       return result.result;
     });
-    deferred.setDoneCallback(() =>
-      this._removePendingResultRequest(sequenceNumber)
-    );
+    deferred.setDoneCallback(() => {
+      this._removePendingResultRequest(sequenceNumber);
+      this._feedbackSubFilterRemoveGoalId(goalHandle.goalId);
+    });
 
     this._pendingResultRequests.set(sequenceNumber, deferred);
 
@@ -458,6 +486,42 @@ class ActionClient extends Entity {
     this._pendingCancelRequests.delete(sequenceNumber);
   }
 
+  /**
+   * Add a goal ID to the feedback subscription content filter.
+   * @ignore
+   * @param {object} goalId - The goal UUID message.
+   */
+  _feedbackSubFilterAddGoalId(goalId) {
+    if (!this._enableFeedbackMsgOptimization) return;
+    try {
+      rclnodejs.actionConfigureFeedbackSubFilterAddGoalId(
+        this.handle,
+        Buffer.from(goalId.uuid)
+      );
+    } catch (e) {
+      this._enableFeedbackMsgOptimization = false;
+      this._node.getLogger().warn(`${e.message}`);
+    }
+  }
+
+  /**
+   * Remove a goal ID from the feedback subscription content filter.
+   * @ignore
+   * @param {object} goalId - The goal UUID message.
+   */
+  _feedbackSubFilterRemoveGoalId(goalId) {
+    if (!this._enableFeedbackMsgOptimization) return;
+    try {
+      rclnodejs.actionConfigureFeedbackSubFilterRemoveGoalId(
+        this.handle,
+        Buffer.from(goalId.uuid)
+      );
+    } catch (e) {
+      this._enableFeedbackMsgOptimization = false;
+      this._node.getLogger().warn(`${e.message}`);
+    }
+  }
+
   /**
    * Destroy the underlying action client handle.
    * @return {undefined}

package/lib/action/server.js

@@ -437,10 +437,8 @@ class ActionServer extends Entity {
 
   _executeExpiredGoals(result, count) {
     for (let i = 0; i < count; i++) {
-      const goal = result.data[i];
-
       const goalInfo = new ActionInterfaces.GoalInfo();
-      goalInfo.deserialize(goal.refObject);
+      goalInfo.deserialize(result._refArray[i]);
 
       let uuid = ActionUuid.fromBytes(goalInfo.goal_id.uuid).toString();
       this._goalHandles.delete(uuid);

package/lib/distro.js

@@ -65,7 +65,8 @@ const DistroUtils = {
       return process.env.ROS_DISTRO;
     }
 
-    return [...DistroNameIdMap].find(([, val]) => val == distroId)[0];
+    const result = [...DistroNameIdMap].find(([, val]) => val == distroId);
+    return result ? result[0] : undefined;
   },
 
   getKnownDistroNames: function () {

package/lib/lifecycle_publisher.js

@@ -30,7 +30,7 @@ class LifecyclePublisher extends Publisher {
     super(handle, typeClass, /*topic=*/ '', options);
 
     this._enabled = false;
-    this._loggger = Logging.getLogger('LifecyclePublisher');
+    this._logger = Logging.getLogger('LifecyclePublisher');
   }
 
   /**
@@ -42,7 +42,7 @@ class LifecyclePublisher extends Publisher {
    */
   publish(message) {
     if (!this._enabled) {
-      this._loggger.warn(
+      this._logger.warn(
         `Trying to publish message on the topic ${this.topic}, but the publisher is not activated`
       );
 

package/lib/message_info.js

@@ -0,0 +1,94 @@
+// Copyright (c) 2026, The Robot Web Tools Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+/**
+ * @class MessageInfo
+ *
+ * Contains metadata about a received message, including timestamps,
+ * sequence numbers, and the publisher's globally unique identifier (GID).
+ *
+ * This is the rclnodejs equivalent of rclpy's MessageInfo.
+ * It is passed as the second argument to subscription callbacks when the
+ * callback accepts two parameters.
+ *
+ * @example
+ * node.createSubscription(
+ *   'std_msgs/msg/String',
+ *   'topic',
+ *   (msg, messageInfo) => {
+ *     console.log('Source timestamp:', messageInfo.sourceTimestamp);
+ *     console.log('Received at:', messageInfo.receivedTimestamp);
+ *     console.log('Publisher GID:', messageInfo.publisherGid);
+ *   }
+ * );
+ */
+class MessageInfo {
+  /**
+   * Create a MessageInfo from a raw info object returned by the native layer.
+   *
+   * @param {object} rawInfo - Raw message info from rclTakeWithInfo
+   * @hideconstructor
+   */
+  constructor(rawInfo) {
+    /**
+     * The timestamp when the message was published (nanoseconds since epoch).
+     * @type {bigint}
+     */
+    this.sourceTimestamp = rawInfo.source_timestamp;
+
+    /**
+     * The timestamp when the message was received by the subscription (nanoseconds since epoch).
+     * @type {bigint}
+     */
+    this.receivedTimestamp = rawInfo.received_timestamp;
+
+    /**
+     * The publication sequence number assigned by the publisher.
+     * @type {bigint}
+     */
+    this.publicationSequenceNumber = rawInfo.publication_sequence_number;
+
+    /**
+     * The reception sequence number assigned by the subscriber.
+     * @type {bigint}
+     */
+    this.receptionSequenceNumber = rawInfo.reception_sequence_number;
+
+    /**
+     * The globally unique identifier (GID) of the publisher.
+     * A Buffer containing the raw GID bytes.
+     * @type {Buffer}
+     */
+    this.publisherGid = rawInfo.publisher_gid;
+  }
+
+  /**
+   * Convert to a plain object representation.
+   *
+   * @returns {object} Plain object with all metadata fields
+   */
+  toPlainObject() {
+    return {
+      sourceTimestamp: this.sourceTimestamp,
+      receivedTimestamp: this.receivedTimestamp,
+      publicationSequenceNumber: this.publicationSequenceNumber,
+      receptionSequenceNumber: this.receptionSequenceNumber,
+      publisherGid: this.publisherGid,
+    };
+  }
+}
+
+module.exports = MessageInfo;