rclnodejs 1.0.0 → 1.2.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
 
@@ -43,9 +43,9 @@ npm i rclnodejs@x.y.z
 
 #### RCLNODEJS - ROS 2 Version Compatibility
 
-|                                     RCLNODEJS Version                                      |                                                             Compatible ROS 2 LTS                                                             |
-| :----------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: |
-| latest version (currently [v1.0.0](https://github.com/RobotWebTools/rclnodejs/tree/1.0.0)) | [Humble](https://github.com/RobotWebTools/rclnodejs/tree/humble-hawksbill)<br>[Jazzy](https://github.com/RobotWebTools/rclnodejs/tree/jazzy) |
+|                                     RCLNODEJS Version                                      |                                                                                               Compatible ROS 2 LTS                                                                                               |
+| :----------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| latest version (currently [v1.2.0](https://github.com/RobotWebTools/rclnodejs/tree/1.2.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

@@ -120,6 +120,9 @@
             'include_dirs': [
               './src/third_party/dlfcn-win32/',
             ],
+            'libraries': [
+              '-lrmw_fastrtps_cpp',
+            ],
             'msvs_settings': {
               'VCCLCompilerTool': {
                 'ExceptionHandling': '2', # /EHsc
@@ -166,6 +169,15 @@
             ]
           }
         ],
+        [
+          # After Humble, e.g., Jazzy, Kilted.
+          'ros_version > 2205', {
+            'sources': [
+              './src/rcl_event_handle_bindings.cpp',
+              './src/rcl_type_description_service_bindings.cpp',
+            ]
+          }
+        ],
         [
           'runtime=="electron"', {
             "defines": ["NODE_RUNTIME_ELECTRON=1"]

package/lib/action/client.js

@@ -19,6 +19,7 @@ const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
 const ClientGoalHandle = require('./client_goal_handle.js');
 const Deferred = require('./deferred.js');
+const DistroUtils = require('../distro.js');
 const Entity = require('../entity.js');
 const loader = require('../interface_loader.js');
 const QoS = require('../qos.js');
@@ -371,6 +372,45 @@ class ActionClient extends Entity {
 
     this._node._destroyEntity(this, this._node._actionClients);
   }
+
+  /**
+   * Get the number of wait set entities that make up an action entity.
+   * @return {object} - An object containing the number of various entities.
+   * @property {number} subscriptionsNumber - The number of subscriptions.
+   * @property {number} guardConditionsNumber - The number of guard conditions.
+   * @property {number} timersNumber - The number of timers.
+   * @property {number} clientsNumber - The number of clients.
+   * @property {number} servicesNumber - The number of services.
+   */
+  getNumEntities() {
+    return rclnodejs.getNumEntities(this.handle);
+  }
+
+  /**
+   * Configure introspection.
+   * @param {Clock} clock - Clock to use for service event timestamps
+   * @param {QoS} qos - QoSProfile for the service event publisher
+   * @param {ServiceIntrospectionState} introspectionState - State to set introspection to
+   */
+  configureIntrospection(clock, qos, introspectionState) {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('jazzy')) {
+      console.warn(
+        'Configure action client introspection is not supported by this version of ROS 2'
+      );
+      return;
+    }
+
+    let type = this.typeClass.type();
+    rclnodejs.configureActionClientIntrospection(
+      this.handle,
+      this._node.handle,
+      clock.handle,
+      type.interfaceName,
+      type.pkgName,
+      qos,
+      introspectionState
+    );
+  }
 }
 
 module.exports = ActionClient;

package/lib/action/server.js

@@ -17,6 +17,7 @@
 const rclnodejs = require('bindings')('rclnodejs');
 const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
+const DistroUtils = require('../distro.js');
 const Entity = require('../entity.js');
 const { CancelResponse, GoalEvent, GoalResponse } = require('./response.js');
 const loader = require('../interface_loader.js');
@@ -454,6 +455,26 @@ class ActionServer extends Entity {
 
     this._node._destroyEntity(this, this._node._actionServers);
   }
+
+  configureIntrospection(clock, qos, introspectionState) {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('jazzy')) {
+      console.warn(
+        'Configure action server introspection is not supported by this version of ROS 2'
+      );
+      return;
+    }
+
+    let type = this.typeClass.type();
+    rclnodejs.configureActionServerIntrospection(
+      this.handle,
+      this._node.handle,
+      clock.handle,
+      type.interfaceName,
+      type.pkgName,
+      qos,
+      introspectionState
+    );
+  }
 }
 
 module.exports = ActionServer;

package/lib/client.js

@@ -141,7 +141,7 @@ class Client extends Entity {
   configureIntrospection(clock, qos, introspectionState) {
     if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
       console.warn(
-        'Service introspection is not supported by this versionof ROS 2'
+        'Service introspection is not supported by this version of ROS 2'
       );
       return;
     }

package/lib/distro.js

@@ -25,6 +25,7 @@ const DistroId = {
   HUMBLE: 2205,
   IRON: 2305,
   JAZZY: 2405,
+  KILTED: 2505,
   ROLLING: 5000,
 };
 
@@ -35,6 +36,7 @@ DistroNameIdMap.set('galactic', DistroId.GALACTIC);
 DistroNameIdMap.set('humble', DistroId.HUMBLE);
 DistroNameIdMap.set('iron', DistroId.IRON);
 DistroNameIdMap.set('jazzy', DistroId.JAZZY);
+DistroNameIdMap.set('kilted', DistroId.KILTED);
 DistroNameIdMap.set('rolling', DistroId.ROLLING);
 
 const DistroUtils = {

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

@@ -591,6 +591,15 @@ class LifecycleNode extends Node {
     return this._changeState(SHUTDOWN_TRANSITION_LABEL, callbackReturnValue);
   }
 
+  /**
+   * Check if state machine is initialized.
+   *
+   * @returns {boolean} true if the state machine is initialized; otherwise false.
+   */
+  get isInitialized() {
+    return rclnodejs.isInitialized(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,