rclnodejs 1.5.0 → 1.5.2

package/README.md

@@ -1,7 +1,9 @@
-# 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 [![Linux](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-x64-push-test.yml/badge.svg?branch=develop)](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-x64-push-test.yml?query=branch%3Adevelop)[![Linux](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-arm64-push-test.yml/badge.svg?branch=develop)](https://github.com/RobotWebTools/rclnodejs/actions/workflows/linux-arm64-push-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.
 
+\* rclnodejs development and maintenance is limited to all active ROS 2 LTS releases and the Rolling development branch
+
 Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
 
 ```JavaScript
@@ -14,137 +16,64 @@ rclnodejs.init().then(() => {
 });
 ```
 
-## Prerequisites
-
-**Node.js**
-
-- [Node.js](https://nodejs.org/en/) version >= 16.13.0.
+## Installation
 
-**ROS 2 SDK**
+### Prerequisites
 
-- 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)**
+- [Node.js](https://nodejs.org/en/) version >= 16.13.0
+- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) - **Don't forget to [source the setup file](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)**
 
-## Install rclnodejs
-
-Install the rclnodejs version that is compatible with your installed version of ROS 2 (see table below).
-
-Run the following command for the most current version of rclnodejs
+### Install rclnodejs
 
 ```bash
 npm i rclnodejs
 ```
 
-or to install a specific version of rclnodejs use
-
-```bash
-npm i rclnodejs@x.y.z
-```
-
-#### RCLNODEJS - ROS 2 Version Compatibility
-
-|                                     RCLNODEJS Version                                      |                                                                                               Compatible ROS 2 LTS                                                                                               |
-| :----------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
-| latest version (currently [v1.5.0](https://github.com/RobotWebTools/rclnodejs/tree/1.5.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
-
-API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) is available online.
-
-## JavaScript Examples
-
-The source for the following examples and many others can be found [here](https://github.com/RobotWebTools/rclnodejs/tree/develop/example).
-
-Use complex message
-
-```JavaScript
-  const publisher = node.createPublisher('sensor_msgs/msg/JointState', 'topic');
-  publisher.publish({
-    header: {
-      stamp: {
-        sec: 123456,
-        nanosec: 789,
-      },
-      frame_id: 'main frame',
-    },
-    name: ['Tom', 'Jerry'],
-    position: [1, 2],
-    velocity: [2, 3],
-    effort: [4, 5, 6],
-  });
-
-```
-
-Create a subscription
+- **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
 
-```JavaScript
-const rclnodejs = require('../index.js');
+### Prebuilt Binaries
 
-// Create a ROS node and then print out the string message received from publishers
-rclnodejs.init().then(() => {
-  const node = rclnodejs.createNode('subscription_example_node');
+rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This significantly speeds up installation and reduces dependencies.
 
-  node.createSubscription('std_msgs/msg/String', 'topic', (msg) => {
-    console.log(`Received message: ${typeof msg}`, msg);
-  });
+**Supported Platforms:**
 
-  rclnodejs.spin(node);
-});
-```
+- **Ubuntu 22.04 (Jammy)** - ROS 2 Humble
+- **Ubuntu 24.04 (Noble)** - ROS 2 Jazzy, Kilted
+- **Architectures:** x64, arm64
+- **Node.js:** >= 16.20.2 (N-API compatible)
 
-Create a service
+**Force Building from Source:**
 
-```JavaScript
-  node.createService('example_interfaces/srv/AddTwoInts', 'add_two_ints', (request, response) => {
-    console.log(`Incoming request: ${typeof request}`, request);
-    let result = response.template;
-    result.sum = request.a + request.b;
-    console.log(`Sending response: ${typeof result}`, result, '\n--');
-    response.send(result);
-  });
+If you need to build from source even when a prebuilt binary is available, set the environment variable:
 
+```bash
+export RCLNODEJS_FORCE_BUILD=1
+npm install rclnodejs
 ```
 
-Send a request in a client
-
-```JavaScript
-  const client = node.createClient('example_interfaces/srv/AddTwoInts', 'add_two_ints');
-  const request = {
-    a: Math.floor(Math.random() * 100),
-    b: Math.floor(Math.random() * 100),
-  };
+## Documentation
 
-  console.log(`Sending: ${typeof request}`, request);
-  client.sendRequest(request, (response) => {
-    console.log(`Result: ${typeof response}`, response);
-  });
+API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) is available online.
 
-```
+## JavaScript Examples
 
-Check out more [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example).
+Try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started.
 
 ## Using rclnodejs with TypeScript
 
-In your node project install the rclnodejs package as described above. You will also need the TypeScript compiler and node typings installed.
-
-```
-  npm install typescript @types/node -D
-```
-
-In your project's tsconfig.json file include the following compiler options:
+TypeScript declaration files are included in the `types/` folder. Configure your `tsconfig.json`:
 
 ```jsonc
 {
   "compilerOptions": {
     "module": "commonjs",
     "moduleResolution": "node",
-    "target": "es6",
-    ...
-  }
+    "target": "es2020",
+  },
 }
 ```
 
-Here's an earlier JavaScript example reimplemented in TypeScript.
+TypeScript example:
 
 ```typescript
 import * as rclnodejs from 'rclnodejs';
@@ -156,21 +85,20 @@ rclnodejs.init().then(() => {
 });
 ```
 
-Type-aliases for the ROS2 messages can be found in the `types/interfaces.d.ts` file. To use a message type-alias follow the naming pattern <pkg_name>.[msg|srv].<type>, e.g., sensor_msgs.msg.LaserScan or the std_msgs.msg.String as shown below.
+See [TypeScript demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo) for more examples.
 
-```typescript
-const msg: rclnodejs.std_msgs.msg.String = {
-  data: 'hello ROS2 from rclnodejs',
-};
-```
+**Note** that the interface.d.ts file is updated each time the generate_messages.js script is run.
 
-Check out more TypeScript [demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo).
+## Electron-based Visualization
 
-**Note** that the interface.d.ts file is updated each time the generate_messages.js script is run.
+Create rich, interactive desktop applications using Electron and web technologies like Three.js. Build 3D visualizations, monitoring dashboards, and control interfaces that run on Windows, macOS, and Linux.
 
-## Using rclnodejs with Electron
+|                                                  Demo                                                   |                                                              Description                                                              |                                                           Screenshot                                                            |
+| :-----------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------: |
+|  **🐢 [turtle_tf2](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/turtle_tf2)**  |  Real-time coordinate frame visualization with turtle control. Features TF2 transforms, keyboard control, and dynamic frame updates.  |  ![turtle_tf2](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.png?raw=true)   |
+| **🦾 [manipulator](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/manipulator)** | Interactive two-joint robotic arm simulation. Features 3D joint visualization, manual/automatic control, and visual movement markers. | ![manipulator](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/manipulator/manipulator-demo.png?raw=true) |
 
-Check out [demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
+Explore more examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
 
 ## License
 

package/binding.gyp

@@ -42,9 +42,11 @@
         './src/rcl_timer_bindings.cpp',
         './src/rcl_utilities.cpp',
         './src/shadow_node.cpp',
+        './third_party/ref-napi/src/ref_napi_bindings.cpp',
       ],
       'include_dirs': [
         '.',
+        './third_party/ref-napi/src',
         '<(ros_include_root)',
         "<!@(node -p \"require('node-addon-api').include\")",
       ],

package/index.js

@@ -37,7 +37,7 @@ const {
 } = require('./lib/parameter.js');
 const path = require('path');
 const QoS = require('./lib/qos.js');
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./lib/native_loader.js');
 const tsdGenerator = require('./rostsd_gen/index.js');
 const validator = require('./lib/validator.js');
 const Time = require('./lib/time.js');

package/lib/action/client.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
 const ClientGoalHandle = require('./client_goal_handle.js');

package/lib/action/graph.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 
 /**
  * Get a list of action names and types for action clients associated with a node.

package/lib/action/server.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
 const DistroUtils = require('../distro.js');

package/lib/action/server_goal_handle.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const Deferred = require('./deferred.js');
 const { GoalEvent } = require('./response.js');

package/lib/client.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
 const debug = require('debug')('rclnodejs:client');

package/lib/clock.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Time = require('./time.js');
 const ClockType = require('./clock_type.js');
 

package/lib/context.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 let defaultContext = null;
 

package/lib/duration.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const S_TO_NS = 10n ** 9n;
 
 /**

package/lib/event_handler.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
 

package/lib/guard_condition.js

@@ -12,7 +12,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Entity = require('./entity.js');
 const Context = require('./context.js');
 

package/lib/interface_loader.js

@@ -90,6 +90,95 @@ let interfaceLoader = {
     return pkg;
   },
 
+  _isRos2InstallationPath(pkgPath) {
+    // Use "which ros2" to dynamically find the ROS2 installation root
+    try {
+      const whichResult = require('child_process').spawnSync(
+        'which',
+        ['ros2'],
+        {
+          encoding: 'utf8',
+          timeout: 5000,
+        }
+      );
+
+      if (whichResult.status === 0 && whichResult.stdout) {
+        const ros2BinPath = whichResult.stdout.trim();
+        // Get the ROS2 installation root (typically /opt/ros/<distro> or similar)
+        const ros2Root = path.dirname(path.dirname(ros2BinPath));
+
+        return pkgPath.includes(ros2Root);
+      }
+    } catch (err) {
+      console.error('Error running which ros2:', err.message);
+      // If "which ros2" fails, fall back to hardcoded check
+      return pkgPath.includes('ros2-linux');
+    }
+
+    return false;
+  },
+
+  _searchAndGenerateInterface(packageName, type, messageName, filePath) {
+    // Check if it's a valid package
+    for (const pkgPath of generator.getInstalledPackagePaths()) {
+      // We are going to ignore the path where ROS2 is installed.
+      if (this._isRos2InstallationPath(pkgPath)) {
+        continue;
+      }
+
+      // Recursively search for files named messageName.* under pkgPath/
+      if (fs.existsSync(pkgPath)) {
+        // Recursive function to search for files
+        function searchForFile(dir) {
+          try {
+            const items = fs.readdirSync(dir, { withFileTypes: true });
+            for (const item of items) {
+              const fullPath = path.join(dir, item.name);
+
+              if (item.isFile()) {
+                const baseName = path.parse(item.name).name;
+                // Check if the base filename matches messageName
+                if (baseName === messageName) {
+                  return fullPath;
+                }
+              } else if (item.isDirectory()) {
+                // Recursively search subdirectories
+                const result = searchForFile(fullPath);
+                if (result) {
+                  return result;
+                }
+              }
+            }
+          } catch (err) {
+            // Skip directories we can't read
+            console.error('Error reading directory:', dir, err.message);
+          }
+          return null;
+        }
+
+        const foundFilePath = searchForFile(
+          path.join(pkgPath, 'share', packageName)
+        );
+
+        if (foundFilePath && foundFilePath.length > 0) {
+          // Use worker thread to generate interfaces synchronously
+          try {
+            generator.generateInPathSyncWorker(pkgPath);
+            // Now try to load the interface again from the generated files
+            if (fs.existsSync(filePath)) {
+              return require(filePath);
+            }
+          } catch (err) {
+            console.error('Error in interface generation:', err);
+          }
+        }
+      }
+    }
+    throw new Error(
+      `The message required does not exist: ${packageName}, ${type}, ${messageName} at ${generator.generatedRoot}`
+    );
+  },
+
   loadInterface(packageName, type, messageName) {
     if (arguments.length === 1) {
       const type = arguments[0];
@@ -100,7 +189,6 @@ let interfaceLoader = {
       }
       throw new Error(`The message required does not exist: ${type}`);
     }
-
     if (packageName && type && messageName) {
       let filePath = path.join(
         generator.generatedRoot,
@@ -110,8 +198,16 @@ let interfaceLoader = {
 
       if (fs.existsSync(filePath)) {
         return require(filePath);
+      } else {
+        return this._searchAndGenerateInterface(
+          packageName,
+          type,
+          messageName,
+          filePath
+        );
       }
     }
+    // We cannot parse `packageName`, `type` and `messageName` from the string passed.
     throw new Error(
       `The message required does not exist: ${packageName}, ${type}, ${messageName} at ${generator.generatedRoot}`
     );

package/lib/lifecycle.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const LifecyclePublisher = require('./lifecycle_publisher.js');
 const loader = require('./interface_loader.js');
 const Context = require('./context.js');

package/lib/lifecycle_publisher.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Logging = require('./logging.js');
 const Publisher = require('./publisher.js');
 

package/lib/logging.js

@@ -15,7 +15,7 @@
 'use strict';
 
 const path = require('path');
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 /**
  * Enum for LoggingSeverity

package/lib/native_loader.js

@@ -0,0 +1,173 @@
+// 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 fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const bindings = require('bindings');
+const debug = require('debug')('rclnodejs');
+const { detectUbuntuCodename } = require('./utils');
+
+let nativeModule = null;
+
+// Simplified loader: only use prebuilt binaries with exact Ubuntu/ROS2/arch match
+// Note: Prebuilt binaries are only supported on Linux (Ubuntu) platform
+function customFallbackLoader() {
+  // Prebuilt binaries are only for Linux platform
+  if (process.platform !== 'linux') {
+    debug('Prebuilt binaries are only supported on Linux platform');
+    return null;
+  }
+
+  const rosDistro = process.env.ROS_DISTRO;
+  const arch = process.arch;
+  const ubuntuCodename = detectUbuntuCodename();
+
+  // Require all three components for exact match
+  if (!rosDistro || !ubuntuCodename || !arch) {
+    debug(
+      `Missing environment info - ROS: ${rosDistro}, Ubuntu: ${ubuntuCodename}, Arch: ${arch}`
+    );
+    return null;
+  }
+
+  const prebuildDir = path.join(
+    __dirname,
+    '..',
+    'prebuilds',
+    `${process.platform}-${arch}`
+  );
+
+  if (!fs.existsSync(prebuildDir)) {
+    debug('No prebuilds directory found');
+    return null;
+  }
+
+  try {
+    // Look for exact match binary: {ros_distro}-{ubuntu_codename}-{arch}-rclnodejs.node
+    const exactMatchFilename = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
+    const exactMatchPath = path.join(prebuildDir, exactMatchFilename);
+
+    if (fs.existsSync(exactMatchPath)) {
+      debug(`Found exact match binary: ${exactMatchFilename}`);
+      return require(exactMatchPath);
+    }
+
+    debug(`No exact match found for: ${exactMatchFilename}`);
+    return null;
+  } catch (e) {
+    debug('Error in simplified prebuilt loader:', e.message);
+  }
+
+  return null;
+}
+
+// Simplified prebuilt binary loader: exact match or build from source
+function loadNativeAddon() {
+  if (nativeModule) {
+    return nativeModule;
+  }
+
+  // Environment variable to force building from source
+  if (process.env.RCLNODEJS_FORCE_BUILD === '1') {
+    debug('Forcing build from source (RCLNODEJS_FORCE_BUILD=1)');
+
+    // Trigger actual compilation
+    try {
+      debug('Running forced node-gyp rebuild...');
+      execSync('npm run rebuild', {
+        stdio: 'inherit',
+        cwd: path.join(__dirname, '..'),
+        timeout: 300000, // 5 minute timeout
+      });
+
+      // Load the newly built binary
+      nativeModule = bindings('rclnodejs');
+      debug('Successfully force compiled and loaded from source');
+      return nativeModule;
+    } catch (compileError) {
+      debug('Forced compilation failed:', compileError.message);
+      throw new Error(
+        `Failed to force build rclnodejs from source: ${compileError.message}`
+      );
+    }
+  }
+
+  const rosDistro = process.env.ROS_DISTRO;
+  const ubuntuCodename = detectUbuntuCodename();
+
+  debug(
+    `Platform: ${process.platform}, Arch: ${process.arch}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
+  );
+
+  // Prebuilt binaries are only supported on Linux (Ubuntu)
+  if (process.platform === 'linux') {
+    // Try exact match prebuilt binary first
+    try {
+      const prebuiltModule = customFallbackLoader();
+      if (prebuiltModule) {
+        nativeModule = prebuiltModule;
+        return nativeModule;
+      }
+    } catch (e) {
+      debug('Exact match prebuilt loading failed:', e.message);
+    }
+
+    debug(
+      'No exact match prebuilt binary found, falling back to build from source'
+    );
+  } else {
+    debug(
+      `Platform ${process.platform} does not support prebuilt binaries, will try existing build or compile from source`
+    );
+  }
+
+  try {
+    // Try to find existing built binary first (works on all platforms)
+    // The 'bindings' module will search standard locations like:
+    // - build/Release/rclnodejs.node
+    // - build/Debug/rclnodejs.node
+    // - compiled/{node_version}/{platform}/{arch}/rclnodejs.node
+    // etc.
+    nativeModule = bindings('rclnodejs');
+    debug('Found and loaded existing built binary');
+    return nativeModule;
+  } catch {
+    debug('No existing built binary found, triggering compilation...');
+
+    // Trigger actual compilation
+    try {
+      debug('Running node-gyp rebuild...');
+      execSync('npm run rebuild', {
+        stdio: 'inherit',
+        cwd: path.join(__dirname, '..'),
+        timeout: 300000, // 5 minute timeout
+      });
+
+      // Try to load the newly built binary
+      nativeModule = bindings('rclnodejs');
+      debug('Successfully compiled and loaded from source');
+      return nativeModule;
+    } catch (compileError) {
+      debug('Compilation failed:', compileError.message);
+      throw new Error(
+        `Failed to build rclnodejs from source: ${compileError.message}`
+      );
+    }
+  }
+}
+
+module.exports = loadNativeAddon();

package/lib/node.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 const ActionInterfaces = require('./action/interfaces.js');
 const Client = require('./client.js');