rclnodejs 1.5.0 → 1.5.1

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,38 +16,20 @@ 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) |
+- **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
 
 ## Documentation
 
@@ -53,98 +37,23 @@ API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) i
 
 ## 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
-
-```JavaScript
-const rclnodejs = require('../index.js');
-
-// Create a ROS node and then print out the string message received from publishers
-rclnodejs.init().then(() => {
-  const node = rclnodejs.createNode('subscription_example_node');
-
-  node.createSubscription('std_msgs/msg/String', 'topic', (msg) => {
-    console.log(`Received message: ${typeof msg}`, msg);
-  });
-
-  rclnodejs.spin(node);
-});
-```
-
-Create a service
-
-```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);
-  });
-
-```
-
-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),
-  };
-
-  console.log(`Sending: ${typeof request}`, request);
-  client.sendRequest(request, (response) => {
-    console.log(`Result: ${typeof response}`, response);
-  });
-
-```
-
-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 +65,17 @@ 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
+Try the `electron_demo/turtle_tf2` demo for real-time coordinate frame visualization with dynamic transforms and keyboard-controlled turtle movement. More examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
 
-Check out [demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
+![demo screenshot](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.gif?raw=true)
 
 ## License
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",

package/rosidl_gen/generate_worker.js

@@ -0,0 +1,63 @@
+// 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.
+
+const fse = require('fs-extra');
+const generateJSStructFromIDL = require('./idl_generator.js');
+const packages = require('./packages.js');
+const path = require('path');
+const idlConvertor = require('../rosidl_convertor/idl_convertor.js');
+
+const generatedRoot = path.join(__dirname, '../generated/');
+const idlPath = path.join(generatedRoot, 'share');
+const useIDL = !!process.argv.find((arg) => arg === '--idl');
+
+// Get target path from environment variable instead of workerData
+const targetPath = process.env.WORKER_TARGET_PATH;
+
+async function generateInPath(targetPath) {
+  let pkgsInfo = null;
+  if (!useIDL) {
+    pkgsInfo = Array.from(
+      (await packages.findPackagesInDirectory(targetPath)).values()
+    );
+  } else {
+    const idlPkgs = await packages.findPackagesInDirectory(targetPath, useIDL);
+    await fse.ensureDir(idlPath);
+    const promises = [];
+    idlPkgs.forEach((pkg) => {
+      pkg.idls.forEach((idl) => {
+        promises.push(idlConvertor(idl.pkgName, idl.filePath, idlPath));
+      });
+    });
+    await Promise.all(promises);
+    const pkgsFromIdl = await packages.findPackagesInDirectory(idlPath, false);
+    pkgsInfo = Array.from(pkgsFromIdl.values());
+  }
+
+  await Promise.all(
+    pkgsInfo.map((pkgInfo) => generateJSStructFromIDL(pkgInfo, generatedRoot))
+  );
+}
+
+async function main() {
+  try {
+    await generateInPath(targetPath);
+    process.exit(0);
+  } catch (error) {
+    console.error('Worker generation failed:', error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/rosidl_gen/index.js

@@ -53,6 +53,35 @@ async function generateInPath(path) {
   );
 }
 
+function generateInPathSyncWorker(targetPath) {
+  try {
+    // Use child_process.spawnSync for truly synchronous execution
+    const result = require('child_process').spawnSync(
+      'node',
+      [path.join(__dirname, 'generate_worker.js')],
+      {
+        env: { ...process.env, WORKER_TARGET_PATH: targetPath },
+        encoding: 'utf8',
+        timeout: 30000,
+      }
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    if (result.status !== 0) {
+      throw new Error(
+        `Worker process exited with code ${result.status}. stderr: ${result.stderr}`
+      );
+    }
+
+    return result.stdout;
+  } catch (error) {
+    throw error;
+  }
+}
+
 async function generateAll(forcedGenerating) {
   // If we want to create the JavaScript files compulsively (|forcedGenerating| equals to true)
   // or the JavaScript files have not been created (|exist| equals to false),
@@ -86,7 +115,9 @@ const generator = {
 
   generateAll,
   generateInPath,
+  generateInPathSyncWorker,
   generatedRoot,
+  getInstalledPackagePaths,
 };
 
 module.exports = generator;