rclnodejs 1.8.3 → 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 {
@@ -243,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,
 
@@ -458,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,7 @@ 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(
@@ -205,6 +221,9 @@ class ActionClient extends Entity {
             status === ActionInterfaces.GoalStatus.STATUS_ABORTED
           ) {
             this._goalHandles.delete(uuid);
+            this._feedbackSubFilterRemoveGoalId(
+              statusMessage.goal_info.goal_id
+            );
           }
         }
       } else {
@@ -393,6 +412,8 @@ class ActionClient extends Entity {
       this._removePendingCancelRequest(sequenceNumber)
     );
 
+    this._feedbackSubFilterRemoveGoalId(goalHandle.goalId);
+
     return deferred.promise;
   }
 
@@ -442,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);
 
@@ -464,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/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;

package/lib/node.js

@@ -40,12 +40,14 @@ const {
 const ParameterService = require('./parameter_service.js');
 const ParameterClient = require('./parameter_client.js');
 const ParameterWatcher = require('./parameter_watcher.js');
+const ParameterEventHandler = require('./parameter_event_handler.js');
 const Publisher = require('./publisher.js');
 const QoS = require('./qos.js');
 const Rates = require('./rate.js');
 const Service = require('./service.js');
 const Subscription = require('./subscription.js');
 const ObservableSubscription = require('./observable_subscription.js');
+const MessageInfo = require('./message_info.js');
 const TimeSource = require('./time_source.js');
 const Timer = require('./timer.js');
 const TypeDescriptionService = require('./type_description_service.js');
@@ -148,6 +150,7 @@ class Node extends rclnodejs.ShadowNode {
     this._actionServers = [];
     this._parameterClients = [];
     this._parameterWatchers = [];
+    this._parameterEventHandlers = [];
     this._rateTimerServer = null;
     this._parameterDescriptors = new Map();
     this._parameters = new Map();
@@ -269,9 +272,22 @@ class Node extends rclnodejs.ShadowNode {
       this._runWithMessageType(
         subscription.typeClass,
         (message, deserialize) => {
-          let success = rclnodejs.rclTake(subscription.handle, message);
-          if (success) {
-            subscription.processResponse(deserialize());
+          if (subscription.wantsMessageInfo) {
+            let rawInfo = rclnodejs.rclTakeWithInfo(
+              subscription.handle,
+              message
+            );
+            if (rawInfo) {
+              subscription.processResponse(
+                deserialize(),
+                new MessageInfo(rawInfo)
+              );
+            }
+          } else {
+            let success = rclnodejs.rclTake(subscription.handle, message);
+            if (success) {
+              subscription.processResponse(deserialize());
+            }
           }
         }
       );
@@ -1082,6 +1098,7 @@ class Node extends rclnodejs.ShadowNode {
 
     this._parameterClients.forEach((paramClient) => paramClient.destroy());
     this._parameterWatchers.forEach((watcher) => watcher.destroy());
+    this._parameterEventHandlers.forEach((handler) => handler.destroy());
 
     this.context.onNodeDestroyed(this);
 
@@ -1102,6 +1119,7 @@ class Node extends rclnodejs.ShadowNode {
     this._actionServers = [];
     this._parameterClients = [];
     this._parameterWatchers = [];
+    this._parameterEventHandlers = [];
 
     if (this._rateTimerServer) {
       this._rateTimerServer.shutdown();
@@ -1214,6 +1232,38 @@ class Node extends rclnodejs.ShadowNode {
     watcher.destroy();
   }
 
+  /**
+   * Create a ParameterEventHandler that monitors parameter changes on any node.
+   *
+   * Unlike {@link ParameterWatcher} which watches specific parameters on a single
+   * remote node, ParameterEventHandler can register callbacks for parameters on
+   * any node in the ROS 2 graph by subscribing to /parameter_events.
+   *
+   * @param {object} [options] - Options for the handler
+   * @param {object} [options.qos] - QoS profile for the parameter_events subscription
+   * @return {ParameterEventHandler} - An instance of ParameterEventHandler
+   * @see {@link ParameterEventHandler}
+   */
+  createParameterEventHandler(options = {}) {
+    const handler = new ParameterEventHandler(this, options);
+    debug('Created ParameterEventHandler on node=%s', this.name());
+    this._parameterEventHandlers.push(handler);
+    return handler;
+  }
+
+  /**
+   * Destroy a ParameterEventHandler.
+   * @param {ParameterEventHandler} handler - The handler to be destroyed.
+   * @return {undefined}
+   */
+  destroyParameterEventHandler(handler) {
+    if (!(handler instanceof ParameterEventHandler)) {
+      throw new TypeError('Invalid argument');
+    }
+    this._removeEntityFromArray(handler, this._parameterEventHandlers);
+    handler.destroy();
+  }
+
   /**
    * Destroy a Timer.
    * @param {Timer} timer - The Timer to be destroyed.