rclnodejs 1.1.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
 
@@ -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.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
@@ -170,6 +173,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/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_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,

package/lib/node.js

@@ -41,6 +41,8 @@ const TimeSource = require('./time_source.js');
 const Timer = require('./timer.js');
 const TypeDescriptionService = require('./type_description_service.js');
 const Entity = require('./entity.js');
+const { SubscriptionEventCallbacks } = require('../lib/event_handler.js');
+const { PublisherEventCallbacks } = require('../lib/event_handler.js');
 
 // Parameter event publisher constants
 const PARAMETER_EVENT_MSG_TYPE = 'rcl_interfaces/msg/ParameterEvent';
@@ -96,6 +98,7 @@ class Node extends rclnodejs.ShadowNode {
     this._services = [];
     this._timers = [];
     this._guards = [];
+    this._events = [];
     this._actionClients = [];
     this._actionServers = [];
     this._rateTimerServer = null;
@@ -181,6 +184,9 @@ class Node extends rclnodejs.ShadowNode {
     let actionServersReady = this._actionServers.filter((actionServer) =>
       handles.includes(actionServer.handle)
     );
+    let eventsReady = this._events.filter((event) =>
+      handles.includes(event.handle)
+    );
 
     timersReady.forEach((timer) => {
       if (timer.isReady()) {
@@ -189,6 +195,10 @@ class Node extends rclnodejs.ShadowNode {
       }
     });
 
+    eventsReady.forEach((event) => {
+      event.takeData();
+    });
+
     for (const subscription of subscriptionsReady) {
       if (subscription.isDestroyed()) continue;
       if (subscription.isRaw) {
@@ -588,27 +598,39 @@ class Node extends rclnodejs.ShadowNode {
    * @param {object} options - The options argument used to parameterize the publisher.
    * @param {boolean} options.enableTypedArray - The topic will use TypedArray if necessary, default: true.
    * @param {QoS} options.qos - ROS Middleware "quality of service" settings for the publisher, default: QoS.profileDefault.
+   * @param {PublisherEventCallbacks} eventCallbacks - The event callbacks for the publisher.
    * @return {Publisher} - An instance of Publisher.
    */
-  createPublisher(typeClass, topic, options) {
-    return this._createPublisher(typeClass, topic, options, Publisher);
+  createPublisher(typeClass, topic, options, eventCallbacks) {
+    return this._createPublisher(
+      typeClass,
+      topic,
+      options,
+      Publisher,
+      eventCallbacks
+    );
   }
 
-  _createPublisher(typeClass, topic, options, publisherClass) {
+  _createPublisher(typeClass, topic, options, publisherClass, eventCallbacks) {
     if (typeof typeClass === 'string' || typeof typeClass === 'object') {
       typeClass = loader.loadInterface(typeClass);
     }
     options = this._validateOptions(options);
 
-    if (typeof typeClass !== 'function' || typeof topic !== 'string') {
+    if (
+      typeof typeClass !== 'function' ||
+      typeof topic !== 'string' ||
+      (eventCallbacks && !(eventCallbacks instanceof PublisherEventCallbacks))
+    ) {
       throw new TypeError('Invalid argument');
     }
 
     let publisher = publisherClass.createPublisher(
-      this.handle,
+      this,
       typeClass,
       topic,
-      options
+      options,
+      eventCallbacks
     );
     debug('Finish creating publisher, topic = %s.', topic);
     this._publishers.push(publisher);
@@ -643,12 +665,13 @@ class Node extends rclnodejs.ShadowNode {
    *  the ‘parameters’ (i.e., "%n" tokens) in the filter_expression. The number of supplied parameters must
    *  fit with the requested values in the filter_expression (i.e., the number of %n tokens). default: undefined.
    * @param {SubscriptionCallback} callback - The callback to be call when receiving the topic subscribed. The topic will be an instance of null-terminated Buffer when options.isRaw is true.
+   * @param {SubscriptionEventCallbacks} eventCallbacks - The event callbacks for the subscription.
    * @return {Subscription} - An instance of Subscription.
    * @throws {ERROR} - May throw an RMW error if content-filter is malformed. 
    * @see {@link SubscriptionCallback}
    * @see {@link https://www.omg.org/spec/DDS/1.4/PDF|Content-filter details at DDS 1.4 specification, Annex B}
    */
-  createSubscription(typeClass, topic, options, callback) {
+  createSubscription(typeClass, topic, options, callback, eventCallbacks) {
     if (typeof typeClass === 'string' || typeof typeClass === 'object') {
       typeClass = loader.loadInterface(typeClass);
     }
@@ -662,17 +685,20 @@ class Node extends rclnodejs.ShadowNode {
     if (
       typeof typeClass !== 'function' ||
       typeof topic !== 'string' ||
-      typeof callback !== 'function'
+      typeof callback !== 'function' ||
+      (eventCallbacks &&
+        !(eventCallbacks instanceof SubscriptionEventCallbacks))
     ) {
       throw new TypeError('Invalid argument');
     }
 
     let subscription = Subscription.createSubscription(
-      this.handle,
+      this,
       typeClass,
       topic,
       options,
-      callback
+      callback,
+      eventCallbacks
     );
     debug('Finish creating subscription, topic = %s.', topic);
     this._subscriptions.push(subscription);
@@ -836,6 +862,12 @@ class Node extends rclnodejs.ShadowNode {
     if (!(publisher instanceof Publisher)) {
       throw new TypeError('Invalid argument');
     }
+    if (publisher.events) {
+      publisher.events.forEach((event) => {
+        this._destroyEntity(event, this._events);
+      });
+      publisher.events = [];
+    }
     this._destroyEntity(publisher, this._publishers, false);
   }
 
@@ -848,6 +880,13 @@ class Node extends rclnodejs.ShadowNode {
     if (!(subscription instanceof Subscription)) {
       throw new TypeError('Invalid argument');
     }
+    if (subscription.events) {
+      subscription.events.forEach((event) => {
+        this._destroyEntity(event, this._events);
+      });
+      subscription.events = [];
+    }
+
     this._destroyEntity(subscription, this._subscriptions);
   }
 
@@ -1637,6 +1676,14 @@ class Node extends rclnodejs.ShadowNode {
     return rclnodejs.getFullyQualifiedName(this.handle);
   }
 
+  /**
+   * Get the RMW implementation identifier
+   * @returns {string} - The RMW implementation identifier.
+   */
+  getRMWImplementationIdentifier() {
+    return rclnodejs.getRMWImplementationIdentifier();
+  }
+
   // returns on 1st error or result {successful, reason}
   _validateParameters(parameters = [], declareParameterMode = false) {
     for (const parameter of parameters) {