rclnodejs 0.33.0 → 1.1.0

package/README.md

@@ -43,9 +43,9 @@ npm i rclnodejs@x.y.z
 
 #### RCLNODEJS - ROS 2 Version Compatibility
 
-|                                      RCLNODEJS Version                                       |                                                             Compatible ROS 2 LTS                                                             |
-| :------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: |
-| latest version (currently [v0.33.0](https://github.com/RobotWebTools/rclnodejs/tree/0.33.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.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) |
 
 ## Documentation
 

package/binding.gyp

@@ -21,17 +21,31 @@
         './src/addon.cpp',
         './src/executor.cpp',
         './src/handle_manager.cpp',
-        './src/rcl_action_bindings.cpp',
+        './src/rcl_action_client_bindings.cpp',
+        './src/rcl_action_goal_bindings.cpp',
+        './src/rcl_action_server_bindings.cpp',
         './src/rcl_bindings.cpp',
+        './src/rcl_client_bindings.cpp',
+        './src/rcl_context_bindings.cpp',
+        './src/rcl_graph_bindings.cpp',
+        './src/rcl_guard_condition_bindings.cpp',
         './src/rcl_handle.cpp',
         './src/rcl_lifecycle_bindings.cpp',
+        './src/rcl_logging_bindings.cpp',
+        './src/rcl_names_bindings.cpp',
+        './src/rcl_node_bindings.cpp',
+        './src/rcl_publisher_bindings.cpp',
+        './src/rcl_service_bindings.cpp',
+        './src/rcl_subscription_bindings.cpp',
+        './src/rcl_time_point_bindings.cpp',
+        './src/rcl_timer_bindings.cpp',
         './src/rcl_utilities.cpp',
         './src/shadow_node.cpp',
       ],
       'include_dirs': [
         '.',
-        "<!(node -e \"require('nan')\")",
         '<(ros_include_root)',
+        "<!@(node -p \"require('node-addon-api').include\")",
       ],
       'cflags!': [
         '-fno-exceptions'
@@ -51,6 +65,7 @@
         '-lrcl_lifecycle',
         '-lrcutils',
         '-lrcl_yaml_param_parser',
+        '-lrcpputils',
         '-lrmw',
         '-lrosidl_runtime_c',
       ],
@@ -151,6 +166,14 @@
             ]
           }
         ],
+        [
+          # After Humble, e.g., Jazzy, Kilted.
+          'ros_version > 2205', {
+            'sources': [
+              './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,21 +141,20 @@ 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;
     }
 
     let type = this.typeClass.type();
-    rclnodejs.configureServiceIntrospection(
+    rclnodejs.configureClientIntrospection(
       this.handle,
       this._nodeHandle,
       clock.handle,
       type.interfaceName,
       type.pkgName,
       qos,
-      introspectionState,
-      false
+      introspectionState
     );
   }
 }

package/lib/context.js

@@ -219,6 +219,14 @@ class Context {
     }
     return defaultContext;
   }
+
+  /**
+   * Get the domain ID of this context.
+   * @returns {Number} domain ID of this context
+   */
+  get domainId() {
+    return rclnodejs.getDomainId(this.handle);
+  }
 }
 
 Context._instances = [];

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/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/logging.js

@@ -39,14 +39,31 @@ let LoggingSeverity = {
 
 class Caller {
   constructor() {
-    this._info = {};
-    let frame = new Error().stack.split('\n').slice(4, 5)[0];
-    let results = frame.match(/at\s+(.*)\s+\((.*):(\d*):(\d*)\)/i);
-
-    if (results && results.length === 5) {
-      this._info['functionName'] = results[1];
-      this._info['lineNumber'] = results[3];
-      this._info['fileName'] = path.basename(results[2]);
+    this._info = {
+      functionName: 'unknown',
+      fileName: 'unknown',
+      lineNumber: 'unknown',
+    };
+
+    const stackLines = new Error().stack.split('\n');
+
+    // Adjust the index (usually 3 or 4) to correctly point to the caller frame.
+    const callerFrame = stackLines[4] || stackLines[3];
+    // Match both named and anonymous function stack frames.
+    const frameRegex = /^\s*at\s+(?:(.+)\s+\()?(.+):(\d+):(\d+)\)?$/;
+    const match = callerFrame.match(frameRegex);
+    if (match && match.length === 5) {
+      this._info.functionName = match[1] || '(anonymous)';
+      this._info.fileName = path.basename(match[2]);
+      this._info.lineNumber = match[3];
+    } else {
+      // Handle anonymous functions or different stack formats.
+      const altMatch = callerFrame.match(/at\s+(.*):(\d+):(\d+)/i);
+      if (altMatch && altMatch.length >= 4) {
+        this._info.functionName = '(anonymous)';
+        this._info.fileName = path.basename(altMatch[1]);
+        this._info.lineNumber = altMatch[2];
+      }
     }
   }
 
@@ -156,7 +173,7 @@ class Logging {
       severity,
       message,
       caller.functionName,
-      caller.lineNumber,
+      parseInt(caller.lineNumber, 10),
       caller.fileName
     );
   }

package/lib/node.js

@@ -21,6 +21,7 @@ const Client = require('./client.js');
 const Clock = require('./clock.js');
 const Context = require('./context.js');
 const debug = require('debug')('rclnodejs:node');
+const DistroUtils = require('./distro.js');
 const GuardCondition = require('./guard_condition.js');
 const loader = require('./interface_loader.js');
 const Logging = require('./logging.js');
@@ -38,6 +39,7 @@ const Service = require('./service.js');
 const Subscription = require('./subscription.js');
 const TimeSource = require('./time_source.js');
 const Timer = require('./timer.js');
+const TypeDescriptionService = require('./type_description_service.js');
 const Entity = require('./entity.js');
 
 // Parameter event publisher constants
@@ -100,6 +102,7 @@ class Node extends rclnodejs.ShadowNode {
     this._parameterDescriptors = new Map();
     this._parameters = new Map();
     this._parameterService = null;
+    this._typeDescriptionService = null;
     this._parameterEventPublisher = null;
     this._setParametersCallbacks = [];
     this._logger = new Logging(rclnodejs.getNodeLoggerName(this.handle));
@@ -146,6 +149,14 @@ class Node extends rclnodejs.ShadowNode {
       this._parameterService = new ParameterService(this);
       this._parameterService.start();
     }
+
+    if (
+      DistroUtils.getDistroId() >= DistroUtils.getDistroId('jazzy') &&
+      options.startTypeDescriptionService
+    ) {
+      this._typeDescriptionService = new TypeDescriptionService(this);
+      this._typeDescriptionService.start();
+    }
   }
 
   execute(handles) {
@@ -1013,6 +1024,32 @@ class Node extends rclnodejs.ShadowNode {
     return rclnodejs.getServiceNamesAndTypes(this.handle);
   }
 
+  /**
+   * Get a list of publishers on a given topic.
+   * @param {string} topic - the topic name to get the publishers for.
+   * @param {boolean} noDemangle - if `true`, `topic_name` needs to be a valid middleware topic name,
+   *       otherwise it should be a valid ROS topic name.
+   * @returns {Array} - list of publishers
+   */
+  getPublishersInfoByTopic(topic, noDemangle) {
+    return rclnodejs.getPublishersInfoByTopic(this.handle, topic, noDemangle);
+  }
+
+  /**
+   * Get a list of subscriptions on a given topic.
+   * @param {string} topic - the topic name to get the subscriptions for.
+   * @param {boolean} noDemangle - if `true`, `topic_name` needs to be a valid middleware topic name,
+   *       otherwise it should be a valid ROS topic name.
+   * @returns {Array} - list of subscriptions
+   */
+  getSubscriptionsInfoByTopic(topic, noDemangle) {
+    return rclnodejs.getSubscriptionsInfoByTopic(
+      this.handle,
+      topic,
+      noDemangle
+    );
+  }
+
   /**
    * Get the list of nodes discovered by the provided node.
    * @return {Array<string>} - An array of the names.
@@ -1026,7 +1063,15 @@ class Node extends rclnodejs.ShadowNode {
    * @return {Array<{name: string, namespace: string}>} An array of the names and namespaces.
    */
   getNodeNamesAndNamespaces() {
-    return rclnodejs.getNodeNames(this.handle);
+    return rclnodejs.getNodeNames(this.handle, /*getEnclaves=*/ false);
+  }
+
+  /**
+   * Get the list of nodes and their namespaces with enclaves discovered by the provided node.
+   * @return {Array<{name: string, namespace: string, enclave: string}>} An array of the names, namespaces and enclaves.
+   */
+  getNodeNamesAndNamespacesWithEnclaves() {
+    return rclnodejs.getNodeNames(this.handle, /*getEnclaves=*/ true);
   }
 
   /**
@@ -1061,6 +1106,32 @@ class Node extends rclnodejs.ShadowNode {
     return rclnodejs.countSubscribers(this.handle, expandedTopic);
   }
 
+  /**
+   * Get the number of clients on a given service name.
+   * @param {string} serviceName - the service name
+   * @returns {Number}
+   */
+  countClients(serviceName) {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn('countClients is not supported by this version of ROS 2');
+      return null;
+    }
+    return rclnodejs.countClients(this.handle, serviceName);
+  }
+
+  /**
+   * Get the number of services on a given service name.
+   * @param {string} serviceName - the service name
+   * @returns {Number}
+   */
+  countServices(serviceName) {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn('countServices is not supported by this version of ROS 2');
+      return null;
+    }
+    return rclnodejs.countServices(this.handle, serviceName);
+  }
+
   /**
    * Get the list of parameter-overrides found on the commandline and
    * in the NodeOptions.parameter_overrides property.
@@ -1557,6 +1628,15 @@ class Node extends rclnodejs.ShadowNode {
     }
   }
 
+  /**
+   * Get the fully qualified name of the node.
+   *
+   * @returns {string} - String containing the fully qualified name of the node.
+   */
+  getFullyQualifiedName() {
+    return rclnodejs.getFullyQualifiedName(this.handle);
+  }
+
   // returns on 1st error or result {successful, reason}
   _validateParameters(parameters = [], declareParameterMode = false) {
     for (const parameter of parameters) {

package/lib/node_options.js

@@ -26,16 +26,19 @@ class NodeOptions {
    * @param {boolean} [startParameterServices=true]
    * @param {array} [parameterOverrides=[]]
    * @param {boolean} [automaticallyDeclareParametersFromOverrides=false]
+   * @param {boolean} [startTypeDescriptionService=true]
    */
   constructor(
     startParameterServices = true,
     parameterOverrides = [],
-    automaticallyDeclareParametersFromOverrides = false
+    automaticallyDeclareParametersFromOverrides = false,
+    startTypeDescriptionService = true
   ) {
     this._startParameterServices = startParameterServices;
     this._parameterOverrides = parameterOverrides;
     this._automaticallyDeclareParametersFromOverrides =
       automaticallyDeclareParametersFromOverrides;
+    this._startTypeDescriptionService = startTypeDescriptionService;
   }
 
   /**
@@ -105,6 +108,23 @@ class NodeOptions {
     this._automaticallyDeclareParametersFromOverrides = declareParamsFlag;
   }
 
+  /**
+   * Get the startTypeDescriptionService option, only available for ROS2 > Humble.
+   * Default value = true;
+   * @returns {boolean} - true if the type description service is enabled.
+   */
+  get startTypeDescriptionService() {
+    return this._startTypeDescriptionService;
+  }
+
+  /**
+   * Set startTypeDescriptionService, only available for ROS2 > Humble
+   * @param {boolean} willStartTypeDescriptionService
+   */
+  set startTypeDescriptionService(willStartTypeDescriptionService) {
+    this._startTypeDescriptionService = willStartTypeDescriptionService;
+  }
+
   /**
    * Return an instance configured with default options.
    * @returns {NodeOptions} - An instance with default values.

package/lib/publisher.js

@@ -72,6 +72,33 @@ class Publisher extends Entity {
     );
     return new Publisher(handle, typeClass, topic, options);
   }
+
+  /**
+   * Get the number of subscriptions to this publisher.
+   * @returns {number} The number of subscriptions
+   */
+  get subscriptionCount() {
+    return rclnodejs.getSubscriptionCount(this._handle);
+  }
+
+  /**
+   * Wait until all published message data is acknowledged or until the specified timeout elapses
+   *
+   * If the timeout is negative then this function will block indefinitely until all published
+   * message data is acknowledged.
+   * If the timeout is 0 then it will check if all published message has been acknowledged without
+   * waiting.
+   * If the timeout is greater than 0 then it will return after that period of time has elapsed or
+   * all published message data is acknowledged.
+   *
+   * Raises an error if failed, such as the middleware not supporting this feature.
+   *
+   * @param {timeout} timeout - The duration to wait for all published message data to be acknowledged in nanoseconds.
+   * @return {boolean} `true` if all published message data is acknowledged before the timeout, otherwise `false`.
+   */
+  waitForAllAcked(timeout) {
+    return rclnodejs.waitForAllAcked(this._handle, timeout);
+  }
 }
 
 module.exports = Publisher;

package/lib/service.js

@@ -125,7 +125,7 @@ class Service 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;
     }
@@ -138,10 +138,17 @@ class Service extends Entity {
       type.interfaceName,
       type.pkgName,
       qos,
-      introspectionState,
-      true
+      introspectionState
     );
   }
+
+  /**
+   * Get the options of this service.
+   * @return {object} The options of this service.
+   */
+  getOptions() {
+    return rclnodejs.getOptions(this._handle);
+  }
 }
 
 module.exports = Service;

package/lib/subscription.js

@@ -116,6 +116,14 @@ class Subscription extends Entity {
       ? rclnodejs.clearContentFilter(this.handle)
       : true;
   }
+
+  /**
+   * Get the number of publishers to this subscription.
+   * @returns {number} The number of publishers
+   */
+  get publisherCount() {
+    return rclnodejs.getPublisherCount(this._handle);
+  }
 }
 
 module.exports = Subscription;

package/lib/timer.js

@@ -15,6 +15,7 @@
 'use strict';
 
 const rclnodejs = require('bindings')('rclnodejs');
+const DistroUtils = require('./distro.js');
 
 /**
  * @class - Class representing a Timer in ROS
@@ -86,6 +87,37 @@ class Timer {
   timeUntilNextCall() {
     return rclnodejs.timerGetTimeUntilNextCall(this._handle);
   }
+
+  /**
+   * Change the timer period.
+   * @param {bigint} period - The new period in nanoseconds.
+   * @return {undefined}
+   */
+  changeTimerPeriod(period) {
+    rclnodejs.changeTimerPeriod(this._handle, period);
+  }
+
+  /**
+   * Get the timer period.
+   * @return {bigint} - The period in nanoseconds.
+   */
+  get timerPeriod() {
+    return rclnodejs.getTimerPeriod(this._handle);
+  }
+
+  /**
+   * Call a timer and starts counting again, retrieves actual and expected call time.
+   * @return {object} - The timer information.
+   */
+  callTimerWithInfo() {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn(
+        'callTimerWithInfo is not supported by this version of ROS 2'
+      );
+      return;
+    }
+    return rclnodejs.callTimerWithInfo(this._handle);
+  }
 }
 
 module.exports = Timer;

package/lib/type_description_service.js

@@ -0,0 +1,82 @@
+// 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 loader = require('./interface_loader.js');
+const rclnodejs = require('bindings')('rclnodejs');
+const Service = require('./service.js');
+
+// This class is used to create a TypeDescriptionService which can be used to
+// retrieve information about types used by the node’s publishers, subscribers,
+// services or actions.
+class TypeDescriptionService {
+  constructor(node) {
+    this._node = node;
+    this._serviceName = this._node.name() + '/get_type_description';
+    this._typeDescriptionServiceHandle = rclnodejs.initTypeDescriptionService(
+      this._node.handle
+    );
+    this._typeClass = loader.loadInterface(
+      'type_description_interfaces/srv/GetTypeDescription'
+    );
+    this._typeDescriptionService = null;
+  }
+
+  start() {
+    if (this._typeDescriptionService) {
+      return;
+    }
+
+    this._typeDescriptionService = new Service(
+      this._node.handle,
+      this._typeDescriptionServiceHandle,
+      this._serviceName,
+      this._typeClass,
+      this._node._validateOptions(undefined),
+      (request, response) => {
+        const responseToBeSent = new this._typeClass.Response();
+        const requestReceived = new this._typeClass.Request(request);
+        rclnodejs.handleRequest(
+          this._node.handle,
+          requestReceived.serialize(),
+          responseToBeSent.serialize()
+        );
+        responseToBeSent.deserialize(responseToBeSent.refObject);
+        rclnodejs.sendResponse(
+          this._typeDescriptionServiceHandle,
+          responseToBeSent.serialize(),
+          response._header
+        );
+        return null;
+      }
+    );
+    this._node._services.push(this._typeDescriptionService);
+    this._node.syncHandles();
+  }
+
+  /**
+   * Get the node this
+   * @return {Node} - The supported node.
+   */
+  get node() {
+    return this._node;
+  }
+
+  static toTypeHash(topicTypeHash) {
+    return `RIHS0${topicTypeHash.version}_${topicTypeHash.value.toString('hex')}`;
+  }
+}
+
+module.exports = TypeDescriptionService;