rclnodejs 1.8.2 → 1.9.0-alpha.0

package/tools/jsdoc/tmpl/tutorial.tmpl

@@ -0,0 +1,19 @@
+<section class="doc-section prose-section tutorial-section">
+
+<header class="doc-page-header">
+    <?js if (children.length > 0) { ?>
+    <ul class="tutorial-children"><?js
+        var self = this;
+        children.forEach(function(t) { ?>
+        <li><?js= self.tutoriallink(t.name) ?></li>
+    <?js }); ?></ul>
+    <?js } ?>
+
+    <h2 class="doc-heading"><?js= header ?></h2>
+</header>
+
+<article class="prose-card">
+    <?js= content ?>
+</article>
+
+</section>

package/tools/jsdoc/tmpl/type.tmpl

@@ -0,0 +1,7 @@
+<?js
+    var data = obj;
+    var self = this;
+    data.forEach(function(name, i) { ?>
+<span class="param-type"><?js= self.linkto(name, self.htmlsafe(name)) ?></span>
+<?js if (i < data.length-1) { ?>|<?js } ?>
+<?js }); ?>

package/types/action_client.d.ts

@@ -142,6 +142,14 @@ declare module 'rclnodejs' {
       options?: Options<ActionQoS> & {
         validateGoals?: boolean;
         validationOptions?: MessageValidationOptions;
+        /**
+         * 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, avoiding reception of
+         * irrelevant feedback messages. An action client can handle up to 6
+         * goals simultaneously with this optimization. Default: false.
+         */
+        enableFeedbackMsgOptimization?: boolean;
       }
     );
 

package/types/index.d.ts

@@ -2,6 +2,8 @@
 /// <reference path="./clock_event.d.ts" />
 /// <reference path="./clock_change.d.ts" />
 /// <reference path="./message_validation.d.ts" />
+/// <reference path="./parameter_event_handler.d.ts" />
+/// <reference path="./message_info.d.ts" />
 
 import { ChildProcess } from 'child_process';
 
@@ -85,6 +87,38 @@ declare module 'rclnodejs' {
    * @deprecated since 0.18.0, Use Node.spinOnce(timeout)*/
   function spinOnce(node: Node, timeout?: number): void;
 
+  /**
+   * Options for waitForMessage.
+   */
+  interface WaitForMessageOptions {
+    /** Timeout in milliseconds. If omitted, waits indefinitely. */
+    timeout?: number;
+    /** QoS profile for the temporary subscription. */
+    qos?: QoS;
+  }
+
+  /**
+   * Wait for a single message on a topic.
+   *
+   * Creates a temporary subscription, waits for the first message to arrive,
+   * and returns it. The node must be spinning before calling this function.
+   *
+   * This is the rclnodejs equivalent of rclpy's `wait_for_message`.
+   *
+   * @param typeClass - The ROS message type class.
+   * @param node - The node to create the temporary subscription on.
+   * @param topic - The topic name to listen on.
+   * @param options - Options including timeout and QoS.
+   * @returns Resolves with the received message.
+   * @throws Error if timeout expires before a message arrives.
+   */
+  function waitForMessage<T extends TypeClass<MessageTypeClassName>>(
+    typeClass: T,
+    node: Node,
+    topic: string,
+    options?: WaitForMessageOptions
+  ): Promise<MessageType<T>>;
+
   /**
    * Stop all activity, destroy all nodes and node components.
    *

package/types/message_info.d.ts

@@ -0,0 +1,72 @@
+// 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.
+
+declare module 'rclnodejs' {
+  /**
+   * Contains metadata about a received message, including timestamps,
+   * sequence numbers, and the publisher's globally unique identifier (GID).
+   *
+   * Passed as the second argument to subscription callbacks when the
+   * callback accepts two parameters.
+   *
+   * @example
+   * ```typescript
+   * node.createSubscription(
+   *   'std_msgs/msg/String',
+   *   'topic',
+   *   (msg: rclnodejs.std_msgs.msg.String, info: MessageInfo) => {
+   *     console.log('Source timestamp:', info.sourceTimestamp);
+   *   }
+   * );
+   * ```
+   */
+  class MessageInfo {
+    /**
+     * The timestamp when the message was published (nanoseconds since epoch).
+     */
+    readonly sourceTimestamp: bigint;
+
+    /**
+     * The timestamp when the message was received by the subscription (nanoseconds since epoch).
+     */
+    readonly receivedTimestamp: bigint;
+
+    /**
+     * The publication sequence number assigned by the publisher.
+     */
+    readonly publicationSequenceNumber: bigint;
+
+    /**
+     * The reception sequence number assigned by the subscriber.
+     */
+    readonly receptionSequenceNumber: bigint;
+
+    /**
+     * The globally unique identifier (GID) of the publisher.
+     * A Buffer containing the raw GID bytes.
+     */
+    readonly publisherGid: Buffer;
+
+    /**
+     * Convert to a plain object representation.
+     */
+    toPlainObject(): {
+      sourceTimestamp: bigint;
+      receivedTimestamp: bigint;
+      publicationSequenceNumber: bigint;
+      receptionSequenceNumber: bigint;
+      publisherGid: Buffer;
+    };
+  }
+}

package/types/node.d.ts

@@ -511,6 +511,27 @@ declare module 'rclnodejs' {
      */
     destroyParameterWatcher(watcher: ParameterWatcher): void;
 
+    /**
+     * Create a ParameterEventHandler that monitors parameter changes on any node.
+     *
+     * Unlike 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 options - Options for the handler.
+     * @returns An instance of ParameterEventHandler.
+     */
+    createParameterEventHandler(
+      options?: ParameterEventHandlerOptions
+    ): ParameterEventHandler;
+
+    /**
+     * Destroy a ParameterEventHandler.
+     *
+     * @param handler - ParameterEventHandler to be destroyed.
+     */
+    destroyParameterEventHandler(handler: ParameterEventHandler): void;
+
     /**
      * Destroy a Timer.
      *

package/types/parameter_event_handler.d.ts

@@ -0,0 +1,139 @@
+// 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.
+
+declare module 'rclnodejs' {
+  /**
+   * Options for ParameterEventHandler constructor.
+   */
+  export interface ParameterEventHandlerOptions {
+    /**
+     * QoS profile for the parameter_events subscription.
+     */
+    qos?: QoS;
+  }
+
+  /**
+   * Opaque handle returned when adding a parameter callback.
+   * Used to remove the callback later via removeParameterCallback().
+   */
+  class ParameterCallbackHandle {
+    readonly parameterName: string;
+    readonly nodeName: string;
+    readonly callback: (parameter: any) => void;
+  }
+
+  /**
+   * Opaque handle returned when adding a parameter event callback.
+   * Used to remove the callback later via removeParameterEventCallback().
+   */
+  class ParameterEventCallbackHandle {
+    readonly callback: (event: any) => void;
+  }
+
+  /**
+   * ParameterEventHandler - Monitors and responds to parameter changes
+   * on any node in the ROS 2 graph.
+   *
+   * Subscribes to `/parameter_events` and dispatches callbacks when
+   * parameters are added, changed, or deleted on any node.
+   *
+   * Two types of callbacks:
+   * - **Parameter callbacks**: for a specific parameter on a specific node
+   * - **Event callbacks**: for every ParameterEvent message received
+   *
+   * @example
+   * ```typescript
+   * const handler = node.createParameterEventHandler();
+   *
+   * const handle = handler.addParameterCallback(
+   *   'my_param', '/my_node',
+   *   (param) => console.log(`Changed: ${param.name}`)
+   * );
+   *
+   * handler.removeParameterCallback(handle);
+   * handler.destroy();
+   * ```
+   */
+  class ParameterEventHandler {
+    /**
+     * Add a callback for a specific parameter on a specific node.
+     *
+     * @param parameterName - Name of the parameter to monitor.
+     * @param nodeName - Fully qualified name of the node (e.g., '/my_node').
+     * @param callback - Called with the parameter message when it changes.
+     * @returns A handle for removing this callback later.
+     */
+    addParameterCallback(
+      parameterName: string,
+      nodeName: string,
+      callback: (parameter: any) => void
+    ): ParameterCallbackHandle;
+
+    /**
+     * Remove a previously added parameter callback.
+     *
+     * @param handle - The handle returned by addParameterCallback.
+     */
+    removeParameterCallback(handle: ParameterCallbackHandle): void;
+
+    /**
+     * Add a callback that is invoked for every parameter event.
+     *
+     * @param callback - Called with the full ParameterEvent message.
+     * @returns A handle for removing this callback later.
+     */
+    addParameterEventCallback(
+      callback: (event: any) => void
+    ): ParameterEventCallbackHandle;
+
+    /**
+     * Remove a previously added parameter event callback.
+     *
+     * @param handle - The handle returned by addParameterEventCallback.
+     */
+    removeParameterEventCallback(handle: ParameterEventCallbackHandle): void;
+
+    /**
+     * Check if the handler has been destroyed.
+     */
+    isDestroyed(): boolean;
+
+    /**
+     * Destroy the handler and clean up resources.
+     */
+    destroy(): void;
+
+    /**
+     * Get a specific parameter from a ParameterEvent message.
+     *
+     * @param event - A ParameterEvent message.
+     * @param parameterName - The parameter name to look for.
+     * @param nodeName - The node name to match.
+     * @returns The matching parameter message, or null.
+     */
+    static getParameterFromEvent(
+      event: any,
+      parameterName: string,
+      nodeName: string
+    ): any | null;
+
+    /**
+     * Get all parameters from a ParameterEvent message (new + changed).
+     *
+     * @param event - A ParameterEvent message.
+     * @returns Array of parameter messages.
+     */
+    static getParametersFromEvent(event: any): any[];
+  }
+}

package/types/subscription.d.ts

@@ -1,8 +1,11 @@
 declare module 'rclnodejs' {
   /**
    * A callback for receiving published messages.
+   * If the callback accepts two parameters, the second will be a MessageInfo
+   * containing metadata about the received message.
    *
    * @param message - The published message.
+   * @param messageInfo - Optional metadata about the message (timestamps, publisher GID, etc).
    *
    * @remarks
    * See {@link Node#createSubscription | Node.createSubscription}
@@ -13,12 +16,15 @@ declare module 'rclnodejs' {
    */
   type SubscriptionCallback<T extends TypeClass<MessageTypeClassName>> =
     // * @param message - The published message
-    (message: MessageType<T>) => void;
+    (message: MessageType<T>, messageInfo?: MessageInfo) => void;
 
   /**
    * A callback for receiving published raw messages.
+   * If the callback accepts a second parameter, it will receive a MessageInfo
+   * containing metadata about the received message.
    *
    * @param message - The published message.
+   * @param messageInfo - Optional metadata about the message.
    *
    * @remarks
    * See {@link Node#createSubscription | Node.createSubscription}
@@ -29,7 +35,7 @@ declare module 'rclnodejs' {
    */
   type SubscriptionWithRawMessageCallback =
     // * @param message - The published raw message
-    (message: Buffer) => void;
+    (message: Buffer, messageInfo?: MessageInfo) => void;
 
   /**
    * A ROS Subscription for published messages on a topic.
@@ -45,6 +51,12 @@ declare module 'rclnodejs' {
      */
     readonly isRaw: boolean;
 
+    /**
+     * Check if content filtering is supported for this subscription.
+     * @returns True if the subscription instance supports content filtering; otherwise false.
+     */
+    isContentFilterSupported(): boolean;
+
     /**
      * Test if the RMW supports content-filtered topics and that this subscription
      * is configured with a well formed content-filter.

package/rosidl_convertor/README.md

@@ -1,298 +0,0 @@
-# ROS2 IDL to Interface Converter
-
-This Python tool converts ROS2 `.idl` files to corresponding `.msg`, `.srv`, and `.action` files.
-
-## Features
-
-- **Complete IDL Parsing**: Parses ROS2 IDL syntax including modules, structs, sequences, and arrays
-- **Type Mapping**: Automatically maps IDL types to ROS2 types (e.g., `double` → `float64`, `sequence<T>` → `T[]`)
-- **Typedef Support**: Handles both simple and array typedefs for complex type definitions
-- **Constants and Default Values**: Supports constant definitions and field default values with `@default` annotations
-- **Comment Preservation**: Extracts and preserves comments from `@verbatim` blocks
-- **Key Annotation Detection**: Automatically skips IDL files with `@key` annotations (not supported in ROS2)
-- **Multi-Interface Support**: Handles messages, services, and actions in a single IDL file
-- **Namespace Support**: Properly handles namespaced types (e.g., `std_msgs::msg::Header` → `std_msgs/Header`)
-- **Command Line Interface**: Easy to use with command line arguments
-- **Verbose Output**: Optional detailed output showing parsed structures and generated files
-
-## Usage
-
-### Basic Usage
-
-```bash
-python3 idl_convertor.py <idl_file>
-```
-
-### With Options
-
-```bash
-python3 idl_convertor.py <idl_file> [options]
-```
-
-### Options
-
-- `-o, --output DIR`: Output directory name for generated files (default: `ros_interfaces`)
-- `-r, --root PATH`: Root path where the generated files will be located (default: current directory)
-- `-p, --package NAME`: Package name to use for generated files (overrides package name from IDL)
-- `-v, --verbose`: Enable verbose output showing parsed structures and file contents
-- `-h, --help`: Show help message
-
-### Advanced Examples
-
-#### Custom Output Directory
-
-```bash
-python3 idl_convertor.py JointState.idl -o my_interfaces
-```
-
-#### Custom Root Path
-
-```bash
-python3 idl_convertor.py SetCameraInfo.idl -r /path/to/workspace -o sensor_msgs
-# Generates files in: /path/to/workspace/sensor_msgs/srv/SetCameraInfo.srv
-```
-
-#### Custom Package Name
-
-```bash
-python3 idl_convertor.py JointState.idl -p my_package_name
-# Overrides the package name from the IDL file
-```
-
-#### Combined Options
-
-```bash
-python3 idl_convertor.py SetCameraInfo.idl -r ~/ros2_ws/src -o sensor_msgs -p sensor_msgs -v
-# Generates: ~/ros2_ws/src/sensor_msgs/srv/SetCameraInfo.srv with package name "sensor_msgs"
-```
-
-## Examples
-
-### 1. Convert a Message IDL
-
-Input file `JointState.idl`:
-
-```idl
-#include "std_msgs/msg/Header.idl"
-
-module sensor_msgs {
-  module msg {
-    struct JointState {
-      std_msgs::msg::Header header;
-      sequence<string> name;
-      sequence<double> position;
-      sequence<double> velocity;
-      sequence<double> effort;
-    };
-  };
-};
-```
-
-Output `JointState.msg`:
-
-```
-# JointState.msg
-# Generated from IDL file
-
-std_msgs/Header header
-string[] name
-float64[] position
-float64[] velocity
-float64[] effort
-```
-
-### 2. Convert a Service IDL
-
-Input file `SetCameraInfo.idl`:
-
-```idl
-#include "sensor_msgs/msg/CameraInfo.idl"
-
-module sensor_msgs {
-  module srv {
-    struct SetCameraInfo_Request {
-      sensor_msgs::msg::CameraInfo camera_info;
-    };
-    struct SetCameraInfo_Response {
-      boolean success;
-      string status_message;
-    };
-  };
-};
-```
-
-Output `SetCameraInfo.srv`:
-
-```
-# SetCameraInfo.srv
-# Generated from IDL file
-
-# Request
-sensor_msgs/CameraInfo camera_info
----
-# Response
-bool success
-string status_message
-```
-
-### 3. Convert an Action IDL
-
-Input file `Fibonacci.idl`:
-
-```idl
-module example_interfaces {
-  module action {
-    struct FibonacciGoal {
-      int32 order;
-    };
-
-    struct FibonacciResult {
-      sequence<int32> sequence;
-    };
-
-    struct FibonacciFeedback {
-      sequence<int32> partial_sequence;
-    };
-  };
-};
-```
-
-Generates separate message files for goal, result, and feedback components.
-
-## Type Mappings
-
-### Basic Type Mappings
-
-| IDL Type         | ROS2 Type  |
-| ---------------- | ---------- |
-| `boolean`        | `bool`     |
-| `octet`          | `uint8`    |
-| `int8`           | `int8`     |
-| `uint8`          | `uint8`    |
-| `int16`          | `int16`    |
-| `uint16`         | `uint16`   |
-| `int32`          | `int32`    |
-| `uint32`         | `uint32`   |
-| `int64`          | `int64`    |
-| `uint64`         | `uint64`   |
-| `float`          | `float32`  |
-| `double`         | `float64`  |
-| `string`         | `string`   |
-| `wstring`        | `wstring`  |
-| `sequence<T>`    | `T[]`      |
-| `T[N]`           | `T[N]`     |
-| `pkg::msg::Type` | `pkg/Type` |
-
-### Typedef Support
-
-The tool supports both simple and array typedefs:
-
-- **Simple typedef**: `typedef double MyDouble;` → Maps `MyDouble` to `float64`
-- **Array typedef**: `typedef double MyArray[9];` → Maps `MyArray` to `float64[9]`
-- **Namespaced typedef**: `typedef std_msgs::msg::Header HeaderType;` → Maps `HeaderType` to `std_msgs/Header`
-
-## Output Structure
-
-The tool creates the following directory structure:
-
-```
-<root>/<output>/
-├── msg/           # Generated .msg files
-├── srv/           # Generated .srv files
-└── action/        # Generated .action files
-```
-
-### ROS2 Workspace Integration
-
-For proper ROS2 workspace integration, you can use the parameters to match the expected structure:
-
-```bash
-# Generate files for a ROS2 package in a workspace
-python3 idl_convertor.py MyMessage.idl \
-  -r ~/ros2_ws/src \
-  -o my_package_name \
-  -p my_package_name
-
-# This creates:
-# ~/ros2_ws/src/my_package_name/msg/MyMessage.msg
-# ~/ros2_ws/src/my_package_name/srv/MyService.srv
-# ~/ros2_ws/src/my_package_name/action/MyAction.action
-```
-
-The generated files will be compatible with ROS2 build tools like `colcon build`.
-
-## Important Notes
-
-### DDS @key Annotation Handling
-
-The tool automatically detects and skips IDL files that contain:
-
-- Direct `@key` annotations (e.g., `@key string identifier;`)
-- References to types that use `@key` annotations (e.g., `KeyedString`, `KeyedLong`)
-
-This is because `@key` annotations are DDS-specific features that are not supported in ROS2 .msg files. When such files are encountered, the tool will print a warning and skip processing:
-
-```
-Warning: Skipping MyFile.idl - contains @key annotations which are not supported in ROS2 .msg files
-```
-
-or
-
-```
-Warning: Skipping MyFile.idl - references keyed types which are not supported in ROS2 .msg files
-```
-
-## Implementation Details
-
-### Classes
-
-- **`IdlParser`**: Parses IDL files and extracts interface definitions
-- **`RosInterfaceGenerator`**: Generates ROS2 interface files from parsed data
-- **`IdlField`**: Represents a field in an IDL structure (with support for comments and default values)
-- **`IdlConstant`**: Represents a constant definition in an IDL structure
-- **`IdlStructure`**: Represents an IDL structure (message, service part, etc.)
-- **`IdlInterface`**: Represents a complete IDL interface definition
-
-### Key Features
-
-- **Robust Parsing**: Handles comments, nested modules, typedefs, and complex type definitions
-- **Key Annotation Detection**: Automatically detects and skips files with `@key` annotations
-- **Comment Preservation**: Extracts comments from `@verbatim` blocks and associates them with fields
-- **Default Value Support**: Processes `@default` annotations and formats them for ROS2
-- **Error Handling**: Graceful error handling with informative messages
-- **Extensible**: Easy to extend for additional IDL features or output formats
-
-## Testing
-
-The tool has been tested with:
-
-- ✅ Basic message types (JointState)
-- ✅ Service definitions (SetCameraInfo) - generates proper .srv files
-- ✅ Action definitions (Fibonacci) - generates proper .action files
-- ✅ Array and sequence types
-- ✅ Namespaced types
-- ✅ Typedef declarations (simple and array types)
-- ✅ Constants and default values with `@default` annotations
-- ✅ Comment preservation from `@verbatim` blocks
-- ✅ `@key` annotation detection and file skipping
-- ✅ Command line interface with all options
-- ✅ Request/Response combination for services
-- ✅ Goal/Result/Feedback combination for actions
-- ✅ Field order preservation from IDL to generated files
-
-## Future Enhancements
-
-- [ ] Support for nested structures and complex type inheritance
-- [ ] Support for enums and unions
-- [ ] Support for IDL annotations beyond `@verbatim`, `@default`, and `@key`
-- [ ] Validation of generated files against ROS2 interface specifications
-- [ ] Support for composition and inheritance patterns
-- [ ] Batch processing of multiple IDL files
-- [ ] Integration with ROS2 build tools (ament, colcon)
-
-## Requirements
-
-- Python 3.6+
-- No external dependencies (uses only standard library)
-
-This tool provides a robust solution for converting ROS2 IDL files to standard ROS2 interface formats, making it easier to work with interface definitions across different ROS2 tools and languages.