rclnodejs 1.1.0 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# rclnodejs ![GitHub Workflow Status](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-build-and-test.yml/badge.svg?branch=jazzy)
+# rclnodejs [![Linux](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-x64-build-and-test.yml/badge.svg?branch=develop)](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-x64-build-and-test.yml?query=branch%3Adevelop)[![Linux](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-arm64-build-and-test.yml/badge.svg?branch=develop)](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-arm64-build-and-test.yml?query=branch%3Adevelop)
 
 `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.
 
@@ -22,8 +22,8 @@ rclnodejs.init().then(() => {
 
 **ROS 2 SDK**
 
-- See the ROS 2 SDK [Installation Guide](https://docs.ros.org/en/jazzy/Installation.html) for details.
-- **DON'T FORGET TO [SOURCE THE ROS 2 STARTUP FILES](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)**
+- See the ROS 2 SDK [Installation Guide](https://docs.ros.org/en/kilted/Installation.html) for details.
+- **DON'T FORGET TO [SOURCE THE ROS 2 STARTUP FILES](https://docs.ros.org/en/kilted/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.htmls)**
 
 ## Install rclnodejs
 
@@ -45,7 +45,7 @@ npm i rclnodejs@x.y.z
 
 |                                     RCLNODEJS Version                                      |                                                                                               Compatible ROS 2 LTS                                                                                               |
 | :----------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
-| latest version (currently [v1.1.0](https://github.com/RobotWebTools/rclnodejs/tree/1.1.0)) | [Kilted](https://github.com/RobotWebTools/rclnodejs/tree/kilted)<br>[Jazzy](https://github.com/RobotWebTools/rclnodejs/tree/jazzy)<br>[Humble](https://github.com/RobotWebTools/rclnodejs/tree/humble-hawksbill) |
+| latest version (currently [v1.3.0](https://github.com/RobotWebTools/rclnodejs/tree/1.3.0)) | [Kilted](https://github.com/RobotWebTools/rclnodejs/tree/kilted)<br>[Jazzy](https://github.com/RobotWebTools/rclnodejs/tree/jazzy)<br>[Humble](https://github.com/RobotWebTools/rclnodejs/tree/humble-hawksbill) |
 
 ## Documentation
 

package/binding.gyp

@@ -35,6 +35,7 @@
         './src/rcl_names_bindings.cpp',
         './src/rcl_node_bindings.cpp',
         './src/rcl_publisher_bindings.cpp',
+        './src/rcl_serialization_bindings.cpp',
         './src/rcl_service_bindings.cpp',
         './src/rcl_subscription_bindings.cpp',
         './src/rcl_time_point_bindings.cpp',
@@ -120,6 +121,9 @@
             'include_dirs': [
               './src/third_party/dlfcn-win32/',
             ],
+            'libraries': [
+              '-lrmw_fastrtps_cpp',
+            ],
             'msvs_settings': {
               'VCCLCompilerTool': {
                 'ExceptionHandling': '2', # /EHsc
@@ -170,6 +174,7 @@
           # After Humble, e.g., Jazzy, Kilted.
           'ros_version > 2205', {
             'sources': [
+              './src/rcl_event_handle_bindings.cpp',
               './src/rcl_type_description_service_bindings.cpp',
             ]
           }

package/index.js

@@ -53,6 +53,10 @@ const {
   getActionNamesAndTypes,
 } = require('./lib/action/graph.js');
 const ServiceIntrospectionStates = require('./lib/service_introspection.js');
+const {
+  serializeMessage,
+  deserializeMessage,
+} = require('./lib/serialization.js');
 
 /**
  * Get the version of the generator that was used for the currently present interfaces.
@@ -183,12 +187,22 @@ let rcl = {
   /** {@link getActionNamesAndTypes} function */
   getActionNamesAndTypes: getActionNamesAndTypes,
 
+  /** {@link serializeMessage} function */
+  serializeMessage: serializeMessage,
+
+  /** {@link deserializeMessage} function */
+  deserializeMessage: deserializeMessage,
+
   /**
    * Create and initialize a node.
    * @param {string} nodeName - The name used to register in ROS.
    * @param {string} [namespace=''] - The namespace used in ROS.
    * @param {Context} [context=Context.defaultContext()] - The context to create the node in.
    * @param {NodeOptions} [options=NodeOptions.defaultOptions] - The options to configure the new node behavior.
+   * @param {Array} [args=[]] - The arguments to pass to the node.
+   * @param {boolean} [useGlobalArguments=true] - If true, the node will use the global arguments
+   *                                             from the context, otherwise it will only use the arguments
+   *                                             passed in the args parameter.
    * @return {Node} A new instance of the specified node.
    * @throws {Error} If the given context is not registered.
    * @deprecated since 0.18.0, Use new Node constructor.
@@ -197,9 +211,18 @@ let rcl = {
     nodeName,
     namespace = '',
     context = Context.defaultContext(),
-    options = NodeOptions.defaultOptions
+    options = NodeOptions.defaultOptions,
+    args = [],
+    useGlobalArguments = true
   ) {
-    return new this.Node(nodeName, namespace, context, options);
+    return new this.Node(
+      nodeName,
+      namespace,
+      context,
+      options,
+      args,
+      useGlobalArguments
+    );
   },
 
   /**
@@ -255,7 +278,7 @@ let rcl = {
       throw new TypeError('argv elements must be strings (and not null).');
     }
 
-    rclnodejs.init(context.handle, argv);
+    rclnodejs.init(context.handle, argv, context._domainId);
 
     if (_rosVersionChecked) {
       // no further processing required

package/lib/context.js

@@ -63,11 +63,13 @@ class Context {
    * Call rcl.init(context) to initialize this context state for
    * use in creating nodes, etc.
    * @constructor
+   * @param {bigint} - Optional, The domain ID of this context.
    */
-  constructor() {
+  constructor(domainId) {
     this._handle = rclnodejs.createContext();
     this._isShutdown = false;
     this._nodes = [];
+    this._domainId = domainId;
     Context._instances.push(this);
   }
 
@@ -222,7 +224,7 @@ class Context {
 
   /**
    * Get the domain ID of this context.
-   * @returns {Number} domain ID of this context
+   * @returns {bigint} domain ID of this context
    */
   get domainId() {
     return rclnodejs.getDomainId(this.handle);

package/lib/event_handler.js

@@ -0,0 +1,474 @@
+// Copyright (c) 2025, 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';
+
+const rclnodejs = require('bindings')('rclnodejs');
+const DistroUtils = require('./distro.js');
+const Entity = require('./entity.js');
+
+/**
+ * Enumeration for PublisherEventCallbacks event types.
+ * @enum {number}
+ */
+const PublisherEventType = {
+  /** @member {number} */
+  PUBLISHER_OFFERED_DEADLINE_MISSED: 0,
+  /** @member {number} */
+  PUBLISHER_LIVELINESS_LOST: 1,
+  /** @member {number} */
+  PUBLISHER_OFFERED_INCOMPATIBLE_QOS: 2,
+  /** @member {number} */
+  PUBLISHER_INCOMPATIBLE_TYPE: 3,
+  /** @member {number} */
+  PUBLISHER_MATCHED: 4,
+};
+
+/**
+ * Enumeration for SubscriptionEventCallbacks event types.
+ * @enum {number}
+ */
+const SubscriptionEventType = {
+  /** @member {number} */
+  SUBSCRIPTION_REQUESTED_DEADLINE_MISSED: 0,
+  /** @member {number} */
+  SUBSCRIPTION_LIVELINESS_CHANGED: 1,
+  /** @member {number} */
+  SUBSCRIPTION_REQUESTED_INCOMPATIBLE_QOS: 2,
+  /** @member {number} */
+  SUBSCRIPTION_MESSAGE_LOST: 3,
+  /** @member {number} */
+  SUBSCRIPTION_INCOMPATIBLE_TYPE: 4,
+  /** @member {number} */
+  SUBSCRIPTION_MATCHED: 5,
+};
+
+class EventHandler extends Entity {
+  constructor(handle, callback, eventType, eventTypeName) {
+    super(handle, null, null);
+    this._callback = callback;
+    this._eventType = eventType;
+    this._eventTypeName = eventTypeName;
+  }
+
+  takeData() {
+    const data = rclnodejs.takeEvent(this._handle, {
+      [this._eventTypeName]: this._eventType,
+    });
+    if (this._callback) {
+      this._callback(data);
+    }
+  }
+}
+
+/**
+ * @class - Class representing a ROS 2 PublisherEventCallbacks
+ * @hideconstructor
+ */
+class PublisherEventCallbacks {
+  constructor() {
+    if (DistroUtils.getDistroId() < DistroUtils.getDistroId('jazzy')) {
+      throw new Error(
+        'PublisherEventCallbacks is only available in ROS 2 Jazzy and later.'
+      );
+    }
+    this._deadline = null;
+    this._incompatible_qos = null;
+    this._liveliness = null;
+    this._incompatible_type = null;
+    this._matched = null;
+    this._eventHandlers = [];
+  }
+
+  /**
+   * Set deadline missed callback.
+   * @param {function} callback - The callback function to be called.
+   */
+  set deadline(callback) {
+    this._deadline = callback;
+  }
+
+  /**
+   * Get deadline missed callback.
+   * @return {function} - The callback function.
+   */
+  get deadline() {
+    return this._deadline;
+  }
+
+  /**
+   * Set incompatible QoS callback.
+   * @param {function} callback - The callback function to be called.
+   */
+  set incompatibleQos(callback) {
+    this._incompatible_qos = callback;
+  }
+
+  /**
+   * Get incompatible QoS callback.
+   * @return {function} - The callback function.
+   */
+  get incompatibleQos() {
+    return this._incompatible_qos;
+  }
+
+  /**
+   * Set liveliness lost callback.
+   * @param {function} callback - The callback function to be called.
+   */
+  set liveliness(callback) {
+    this._liveliness = callback;
+  }
+
+  /**
+   * Get liveliness lost callback.
+   * @return {function} - The callback function.
+   */
+  get liveliness() {
+    return this._liveliness;
+  }
+
+  /**
+   * Set incompatible type callback.
+   * @param {function} callback - The callback function to be called.
+   */
+  set incompatibleType(callback) {
+    this._incompatible_type = callback;
+  }
+
+  /**
+   * Get incompatible type callback.
+   * @return {function} - The callback function.
+   */
+  get incompatibleType() {
+    return this._incompatible_type;
+  }
+
+  /**
+   * Set matched callback.
+   * @param {function} callback - The callback function to be called.
+   */
+  set matched(callback) {
+    this._matched = callback;
+  }
+
+  /**
+   * Get matched callback.
+   * @return {function} - The callback function.
+   */
+  get matched() {
+    return this._matched;
+  }
+
+  createEventHandlers(publisherHandle) {
+    if (this._deadline) {
+      const deadlineHandle = rclnodejs.createPublisherEventHandle(
+        publisherHandle,
+        PublisherEventType.PUBLISHER_OFFERED_DEADLINE_MISSED
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          deadlineHandle,
+          this._deadline,
+          PublisherEventType.PUBLISHER_OFFERED_DEADLINE_MISSED,
+          'publisher_event_type'
+        )
+      );
+    }
+
+    if (this._incompatible_qos) {
+      const incompatibleQosHandle = rclnodejs.createPublisherEventHandle(
+        publisherHandle,
+        PublisherEventType.PUBLISHER_OFFERED_INCOMPATIBLE_QOS
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          incompatibleQosHandle,
+          this._incompatible_qos,
+          PublisherEventType.PUBLISHER_OFFERED_INCOMPATIBLE_QOS,
+          'publisher_event_type'
+        )
+      );
+    }
+
+    if (this._liveliness) {
+      const livelinessHandle = rclnodejs.createPublisherEventHandle(
+        publisherHandle,
+        PublisherEventType.PUBLISHER_LIVELINESS_LOST
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          livelinessHandle,
+          this._liveliness,
+          PublisherEventType.PUBLISHER_LIVELINESS_LOST,
+          'publisher_event_type'
+        )
+      );
+    }
+
+    if (this._incompatible_type) {
+      const incompatibleTypeHandle = rclnodejs.createPublisherEventHandle(
+        publisherHandle,
+        PublisherEventType.PUBLISHER_INCOMPATIBLE_TYPE
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          incompatibleTypeHandle,
+          this._incompatible_type,
+          PublisherEventType.PUBLISHER_INCOMPATIBLE_TYPE,
+          'publisher_event_type'
+        )
+      );
+    }
+
+    if (this._matched) {
+      const matchedHandle = rclnodejs.createPublisherEventHandle(
+        publisherHandle,
+        PublisherEventType.PUBLISHER_MATCHED
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          matchedHandle,
+          this._matched,
+          PublisherEventType.PUBLISHER_MATCHED,
+          'publisher_event_type'
+        )
+      );
+    }
+
+    return this._eventHandlers;
+  }
+
+  get eventHandlers() {
+    return this._eventHandlers;
+  }
+}
+
+/**
+ * @class - Class representing a ROS 2 SubscriptionEventCallbacks
+ * @hideconstructor
+ */
+class SubscriptionEventCallbacks {
+  constructor() {
+    if (DistroUtils.getDistroId() < DistroUtils.getDistroId('jazzy')) {
+      throw new Error(
+        'SubscriptionEventCallbacks is only available in ROS 2 Jazzy and later.'
+      );
+    }
+    this._deadline = null;
+    this._incompatible_qos = null;
+    this._liveliness = null;
+    this._message_lost = null;
+    this._incompatible_type = null;
+    this._matched = null;
+    this._eventHandlers = [];
+  }
+
+  /**
+   * Set the callback for deadline missed event.
+   * @param {function} callback - The callback function to be called.
+   */
+  set deadline(callback) {
+    this._deadline = callback;
+  }
+
+  /**
+   * Get the callback for deadline missed event.
+   * @return {function} - The callback function.
+   */
+  get deadline() {
+    return this._deadline;
+  }
+
+  /**
+   * Set the callback for incompatible QoS event.
+   * @param {function} callback - The callback function to be called.
+   */
+  set incompatibleQos(callback) {
+    this._incompatible_qos = callback;
+  }
+
+  /**
+   * Get the callback for incompatible QoS event.
+   * @return {function} - The callback function.
+   */
+  get incompatibleQos() {
+    return this._incompatible_qos;
+  }
+
+  /**
+   * Set the callback for liveliness changed event.
+   * @param {function} callback - The callback function to be called.
+   */
+  set liveliness(callback) {
+    this._liveliness = callback;
+  }
+
+  /**
+   * Get the callback for liveliness changed event.
+   * @return {function} - The callback function.
+   */
+  get liveliness() {
+    return this._liveliness;
+  }
+
+  /**
+   * Set the callback for message lost event.
+   * @param {function} callback - The callback function to be called.
+   */
+  set messageLost(callback) {
+    this._message_lost = callback;
+  }
+
+  /**
+   * Get the callback for message lost event.
+   * @return {function} - The callback function.
+   */
+  get messageLost() {
+    return this._message_lost;
+  }
+
+  /**
+   * Set the callback for incompatible type event.
+   * @param {function} callback - The callback function to be called.
+   */
+  set incompatibleType(callback) {
+    this._incompatible_type = callback;
+  }
+
+  /**
+   * Get the callback for incompatible type event.
+   * @return {function} - The callback function.
+   */
+  get incompatibleType() {
+    return this._incompatible_type;
+  }
+
+  /**
+   * Set the callback for matched event.
+   * @param {function} callback - The callback function to be called.
+   */
+  set matched(callback) {
+    this._matched = callback;
+  }
+
+  /**
+   * Get the callback for matched event.
+   * @return {function} - The callback function.
+   */
+  get matched() {
+    return this._matched;
+  }
+
+  createEventHandlers(subscriptionHandle) {
+    if (this._deadline) {
+      const deadlineHandle = rclnodejs.createSubscriptionEventHandle(
+        subscriptionHandle,
+        SubscriptionEventType.SUBSCRIPTION_REQUESTED_DEADLINE_MISSED
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          deadlineHandle,
+          this._deadline,
+          SubscriptionEventType.SUBSCRIPTION_REQUESTED_DEADLINE_MISSED,
+          'subscription_event_type'
+        )
+      );
+    }
+
+    if (this._incompatible_qos) {
+      const incompatibleQosHandle = rclnodejs.createSubscriptionEventHandle(
+        subscriptionHandle,
+        SubscriptionEventType.SUBSCRIPTION_REQUESTED_INCOMPATIBLE_QOS
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          incompatibleQosHandle,
+          this._incompatible_qos,
+          SubscriptionEventType.SUBSCRIPTION_REQUESTED_INCOMPATIBLE_QOS,
+          'subscription_event_type'
+        )
+      );
+    }
+
+    if (this._liveliness) {
+      const livelinessHandle = rclnodejs.createSubscriptionEventHandle(
+        subscriptionHandle,
+        SubscriptionEventType.SUBSCRIPTION_LIVELINESS_CHANGED
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          livelinessHandle,
+          this._liveliness,
+          SubscriptionEventType.SUBSCRIPTION_LIVELINESS_CHANGED,
+          'subscription_event_type'
+        )
+      );
+    }
+
+    if (this._message_lost) {
+      const messageLostHandle = rclnodejs.createSubscriptionEventHandle(
+        subscriptionHandle,
+        SubscriptionEventType.SUBSCRIPTION_MESSAGE_LOST
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          messageLostHandle,
+          this._message_lost,
+          SubscriptionEventType.SUBSCRIPTION_MESSAGE_LOST,
+          'subscription_event_type'
+        )
+      );
+    }
+
+    if (this._incompatible_type) {
+      const incompatibleTypeHandle = rclnodejs.createSubscriptionEventHandle(
+        subscriptionHandle,
+        SubscriptionEventType.SUBSCRIPTION_INCOMPATIBLE_TYPE
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          incompatibleTypeHandle,
+          this._incompatible_type,
+          SubscriptionEventType.SUBSCRIPTION_INCOMPATIBLE_TYPE,
+          'subscription_event_type'
+        )
+      );
+    }
+
+    if (this._matched) {
+      const matchedHandle = rclnodejs.createSubscriptionEventHandle(
+        subscriptionHandle,
+        SubscriptionEventType.SUBSCRIPTION_MATCHED
+      );
+      this._eventHandlers.push(
+        new EventHandler(
+          matchedHandle,
+          this._matched,
+          SubscriptionEventType.SUBSCRIPTION_MATCHED,
+          'subscription_event_type'
+        )
+      );
+    }
+
+    return this._eventHandlers;
+  }
+}
+
+module.exports = {
+  PublisherEventCallbacks,
+  PublisherEventType,
+  SubscriptionEventCallbacks,
+  SubscriptionEventType,
+};

package/lib/lifecycle.js

@@ -600,6 +600,15 @@ class LifecycleNode extends Node {
     return rclnodejs.isInitialized(this._stateMachineHandle);
   }
 
+  /**
+   * Log the state machine data.
+   *
+   * @returns {undefined} void.
+   */
+  print() {
+    rclnodejs.print(this._stateMachineHandle);
+  }
+
   /**
    * The GetState service handler.
    * @param {Object} request - The GetState service request.

package/lib/lifecycle_publisher.js

@@ -93,10 +93,10 @@ class LifecyclePublisher extends Publisher {
     this.deactivate();
   }
 
-  static createPublisher(nodeHandle, typeClass, topic, options) {
+  static createPublisher(node, typeClass, topic, options) {
     let type = typeClass.type();
     let handle = rclnodejs.createPublisher(
-      nodeHandle,
+      node.handle,
       type.pkgName,
       type.subFolder,
       type.interfaceName,