Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 53 additions & 61 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,11 @@

[![Nightly Compatibility](https://github.com/RobotWebTools/rclnodejs/actions/workflows/nightly-compatibility.yml/badge.svg?branch=develop&event=schedule)](https://github.com/RobotWebTools/rclnodejs/actions/workflows/nightly-compatibility.yml?query=branch%3Adevelop+event%3Aschedule)

*Early-warning checks for ROS Rolling [nightlies](https://github.com/ros2/ros2/releases/tag/release-rolling-nightlies) using Node.js 27 [alpha](https://nodejs.org/en/about/previous-releases). See the [build documentation](./docs/BUILDING.md#nightly-compatibility-checks).*
*Nightly Compatibility checks: ROS Rolling [nightlies](https://github.com/ros2/ros2/releases/tag/release-rolling-nightlies) with Node.js 27 [alpha](https://nodejs.org/en/about/previous-releases). See the [build documentation](./docs/BUILDING.md#nightly-compatibility-checks).*

**rclnodejs** is a Node.js client library for [ROS 2](https://www.ros.org/) that provides comprehensive JavaScript and TypeScript APIs for developing ROS 2 solutions.
**rclnodejs** is a Node.js client library for [ROS 2](https://www.ros.org/) with JavaScript and TypeScript APIs. It supports topics, services, actions, parameters, lifecycle nodes, RxJS subscriptions, and Electron and browser apps.

**Key features:** Topics, Services, Actions, Parameters, Lifecycle Nodes, TypeScript support, RxJS Observables, Electron integration, ROS 2 in the browser (typed Web SDK + thin WebSocket gateway — `rclnodejs/web`, `rosocket`), and prebuilt binaries for Linux x64/arm64.

New to ROS 2 or rclnodejs? Start with [Writing Your First rclnodejs Nodes](./tutorials/writing-your-first-rclnodejs-nodes.md) for project setup, publisher/subscriber examples, and service calls.
Start with [Writing Your First rclnodejs Nodes](./tutorials/writing-your-first-rclnodejs-nodes.md) for setup, topics, and service calls.

```javascript
import rclnodejs from 'rclnodejs';
Expand All @@ -33,10 +31,8 @@ node.spin();

## Documentation

- Reference:
[API Documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html), [Web SDK guide](./web/README.md), [Tutorials](./tutorials/)
- Project docs:
[Efficient Usage Tips](./docs/EFFICIENCY.md), [FAQ and Known Issues](./docs/FAQ.md), [Building from Scratch](./docs/BUILDING.md), [Contributing](./docs/CONTRIBUTING.md)
- Reference: [API Documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html), [Web SDK guide](./web/README.md), [Tutorials](./tutorials/)
- Project docs: [Efficient Usage Tips](./docs/EFFICIENCY.md), [FAQ and Known Issues](./docs/FAQ.md), [Building from Scratch](./docs/BUILDING.md), [Contributing](./docs/CONTRIBUTING.md)

## Installation

Expand All @@ -57,13 +53,9 @@ source /opt/ros/<distro>/setup.bash
npm i rclnodejs
```

For a branch or commit not yet published to npm, use
`npm install RobotWebTools/rclnodejs#<branch>`, which builds from source.
Install an unpublished branch or commit with `npm install RobotWebTools/rclnodejs#<branch>`. GitHub installs and source checkouts need newer Node.js/npm versions than the runtime minimum; see the [build guide](./docs/BUILDING.md).

Prebuilt binaries ship for Ubuntu 22.04 (Humble), 24.04 (Jazzy, Kilted) and
26.04 (Lyrical) on x64 and arm64, so most installs skip compilation; anything
else builds from source. Set `RCLNODEJS_FORCE_BUILD=1` to always build from
source, and see the [Dockerfile](./Dockerfile) for containerized development.
Prebuilt binaries cover Ubuntu 22.04 (Humble), 24.04 (Jazzy, Kilted), and 26.04 (Lyrical) on x64 and arm64. Other platforms build from source. Set `RCLNODEJS_FORCE_BUILD=1` to force compilation, or use the [Dockerfile](./Dockerfile) for container development.

### Run the examples from a clone

Expand All @@ -76,66 +68,66 @@ More in [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/examp

## Bring ROS 2 to the Web

`rclnodejs` ships **two** ways to reach ROS 2 from the browser — pick one based on
how much glue you want to write.

- **[`rclnodejs/web`](./web/README.md)** — a typed layer over your ROS 2 graph:
you allow-list capabilities in `web.json` or via CLI flags; anything else is
rejected before it reaches ROS 2. Best for typed web apps and HTTP clients.
- **Typed SDK** — `call`, `publish`, `subscribe`, and `action`, typed
from generated ROS interfaces.
- **Two transports** — WebSocket for all verbs, or HTTP (`--http-port`)
for calls, publishes, and SSE actions. Action cancellation requires
WebSocket and server acceptance. SDK subscriptions use WebSocket;
`--http-sse` enables raw HTTP subscriptions.
- **OpenAPI 3.1** — export service, topic, and action schemas with
`rclnodejs-web openapi`.

```ts
import type {} from 'rclnodejs';
import { connect } from 'rclnodejs/web';
const ros = await connect('ws://host:9000/capability');
const reply = await ros.call<'example_interfaces/srv/AddTwoInts'>(
'/add_two_ints', { a: '2n', b: '40n' }
); // reply.sum is typed as `${number}n`
```

See the [Fibonacci action demo](./demo/web/api-playground/javascript/README.md#fibonacci-actions)
for a runnable example, or the [browser manipulator demo](./demo/web/manipulator/)
for terminal keyboard control and live Three.js visualization.
Browse all [web demos](./demo/web/README.md) by scenario and implementation.

- **[`rosocket`](./rosocket/README.md)** — thin WebSocket gateway,
zero browser dependencies (just built-in `WebSocket` + `JSON`).
Best for quick prototypes and `roslibjs`-style apps.

```bash
npx rosocket --port 9000 --topic /chatter:std_msgs/msg/String
```
Build robot dashboards, control panels, and 3D visualizations in JavaScript or TypeScript. Your browser app connects to a Node.js runtime that handles ROS 2 communication.

### Typed Web SDK

[rclnodejs/web](./web/README.md) provides `call`, `publish`, `subscribe`, and `action`, with payload types derived from your generated ROS interfaces.

- Choose which services, topics, and actions to expose in `web.json` or CLI flags. Unlisted operations are rejected before reaching ROS 2.
- Use WebSocket for all four operations, or HTTP/SSE for service calls, publishing, and actions. HTTP endpoints also work with `curl` and Postman.
- Export OpenAPI 3.1 with `rclnodejs-web openapi` for API explorers and client generation.

With the [runtime](./web/README.md#server) and a ROS `/add_two_ints` service running:

```ts
import type {} from 'rclnodejs';
import { connect } from 'rclnodejs/web';

const ros = await connect('ws://localhost:9000/capability');
const reply = await ros.call<'example_interfaces/srv/AddTwoInts'>(
'/add_two_ints',
{ a: '2n', b: '40n' }
);
console.log(reply.sum);
await ros.close();
```

SDK subscriptions and action cancellation use WebSocket; cancellation also requires server acceptance. Raw HTTP topic subscriptions are available with `--http-sse`.

Try [Fibonacci actions in the browser](./demo/web/api-playground/javascript/README.md#fibonacci-actions), or watch a [terminal-controlled manipulator in 3D](./demo/web/manipulator/). See all [web demos](./demo/web/README.md) for setup and runnable code.

### WebSocket URLs Without an SDK

[rosocket](https://github.com/RobotWebTools/rclnodejs/blob/develop/rosocket/README.md) exposes one topic or service per WebSocket connection. Browser clients use only the built-in `WebSocket` and `JSON` APIs.

```bash
npx rosocket --host 127.0.0.1 --port 9000 --topic /chatter:std_msgs/msg/String
```

## Observable Subscriptions

rclnodejs supports [RxJS](https://rxjs.dev/) Observable subscriptions for reactive programming with ROS 2 messages — operators like `throttleTime()`, `debounceTime()`, `map()`, and `combineLatest()` build declarative message processing pipelines. See the [Observable Subscriptions Tutorial](./tutorials/observable-subscriptions.md) for the full API and runnable examples.
rclnodejs exposes topic subscriptions as [RxJS](https://rxjs.dev/) Observables. See the [Observable Subscriptions Tutorial](./tutorials/observable-subscriptions.md) for a runnable example and subscription cleanup.

## Electron-based Visualization

Build desktop ROS 2 apps with Electron + Three.js, packaged for Windows/macOS/Linux via **Electron Forge**. Featured demo: 🦾 **[manipulator](./demo/electron/manipulator)** — a two-joint arm with manual/automatic control. More in [demo/electron](./demo/electron/).
See the [Electron demos](./demo/electron/) for desktop ROS 2 apps and packaging with Electron Forge. The [manipulator](./demo/electron/manipulator/) uses Electron and Three.js to control a two-joint arm.

## ROS 2 Interface Message Generation

rclnodejs auto-generates JavaScript bindings and TypeScript declarations for every ROS 2 `.msg`, `.srv`, and `.action` interface in your sourced environment. This runs during `npm install`, so in most projects you never invoke it by hand.
rclnodejs generates JavaScript bindings and TypeScript declarations during `npm install` for ROS 2 `.msg`, `.srv`, and `.action` interfaces in your sourced environment.

If you install additional ROS packages afterwards, re-run it from your project so the new interfaces are picked up:
After adding ROS interface packages, source their workspace and run from your project:

```bash
npx generate-ros-messages
```

Generated files are written to `<your-project>/node_modules/rclnodejs/generated/`. For custom `.idl` files, this repo also exposes `npm run generate-messages-idl`.
JavaScript bindings are written to `<your-project>/node_modules/rclnodejs/generated/` and TypeScript declarations to `node_modules/rclnodejs/types/interfaces.d.ts`. For custom `.idl` files, this repo also exposes `npm run generate-messages-idl`.

## Using rclnodejs with TypeScript

TypeScript declaration files are included in the package and exposed through the `types` entry in `package.json`. In most projects, configuring your `tsconfig.json` is sufficient:
The package includes TypeScript declarations. Use NodeNext module resolution in `tsconfig.json`:

```jsonc
{
Expand All @@ -147,12 +139,12 @@ TypeScript declaration files are included in the package and exposed through the
}
```

Then `import * as rclnodejs from 'rclnodejs'` works as in the example above. See [TypeScript demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/demo/typescript).
See the [TypeScript demos](./demo/typescript/).

## More

- **Performance** — faster than `rclpy` and competitive with `rclcpp` for both topic and service round-trips. Full benchmarks in [benchmark/README.md](./benchmark/README.md).
- **Companion CLI** — [`rclnodejs-cli`](https://github.com/RobotWebTools/rclnodejs-cli/) scaffolds rclnodejs application skeletons and orchestrates launch files for multi-node setups.
- [Benchmarks](./benchmark/README.md) record topic publishing and service request-response measurements for rclnodejs v1.5.0, rclcpp, and rclpy.
- [rclnodejs-cli](https://github.com/RobotWebTools/rclnodejs-cli/) creates application skeletons and launch files for multi-node setups.

## Contributing

Expand All @@ -162,4 +154,4 @@ Thanks to all [contributors](CONTRIBUTORS.md)!

## License

This project abides by the [Apache License 2.0](https://github.com/RobotWebTools/rclnodejs/blob/develop/LICENSE).
Licensed under [Apache 2.0](https://github.com/RobotWebTools/rclnodejs/blob/develop/LICENSE).
155 changes: 51 additions & 104 deletions benchmark/README.md
Original file line number Diff line number Diff line change
@@ -1,137 +1,84 @@
# ROS 2 Client Library Benchmarks

Performance benchmarks for comparing ROS 2 client libraries: C++ (rclcpp), Python (rclpy), and JavaScript (rclnodejs).
Topic and service benchmarks for rclcpp (C++), rclpy (Python), and rclnodejs (JavaScript).

## Prerequisites

1. **ROS 2**: Install from [ros.org](https://docs.ros.org/en/lyrical/Installation.html)
2. **Node.js**: v20.20.2+ for rclnodejs (from [nodejs.org](https://nodejs.org/))
3. **rclnodejs**: Follow [installation guide](https://github.com/RobotWebTools/rclnodejs#installation)
4. **Build Dependencies**: For C++ benchmarks: `sudo apt install libssl-dev cmake build-essential`
- Install ROS 2 with rclcpp, rclpy, `std_msgs`, and `nav_msgs`.
- For JavaScript, prepare the checkout using the [build guide](../docs/BUILDING.md).
- For C++, install `cmake`, `build-essential`, and `libssl-dev`.

## Benchmark Structure
Run from the repository root. Source ROS 2 in each terminal:

Each client library has identical benchmark tests:
```bash
source /opt/ros/<distro>/setup.bash
```

| Test Type | Description |
| ----------- | ------------------------------------------- |
| **topic** | Publisher/subscriber performance |
| **service** | Client/service request-response performance |
Build the C++ benchmarks:

## Performance Results
```bash
cmake -S benchmark/rclcpp -B benchmark/rclcpp/build
cmake --build benchmark/rclcpp/build
```

## Recorded Results

Recorded on August 30, 2025, using rclnodejs v1.5.0. These are historical results, not measurements of the current release.

### Test Environment

**Hardware:**
Hardware:

- **CPU:** 11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz (4 cores, 8 threads)
- **Memory:** 8GB RAM
- **Architecture:** x86_64
- CPU: 11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz (4 cores, 8 threads)
- Memory: 8GB RAM
- Architecture: x86_64

**Software:**
Software:

- **OS:** Ubuntu 24.04.3 LTS (WSL2)
- **Kernel:** 6.6.87.2-microsoft-standard-WSL2
- **ROS 2:** [Jazzy Patch Release 6](https://github.com/ros2/ros2/releases/tag/release-jazzy-20250820)
- **C++ Compiler:** GCC 13.3.0 (Ubuntu 13.3.0-6ubuntu2~24.04)
- **Python:** 3.12.3
- **Node.js:** v22.18.0
- **rclnodejs:** [v1.5.0](https://www.npmjs.com/package/rclnodejs/v/1.5.0)
- OS: Ubuntu 24.04.3 LTS (WSL2)
- Kernel: 6.6.87.2-microsoft-standard-WSL2
- ROS 2: [Jazzy Patch Release 6](https://github.com/ros2/ros2/releases/tag/release-jazzy-20250820)
- C++ compiler: GCC 13.3.0 (Ubuntu 13.3.0-6ubuntu2~24.04)
- Python: 3.12.3
- Node.js: v22.18.0
- rclnodejs: [v1.5.0](https://www.npmjs.com/package/rclnodejs/v/1.5.0)

### Benchmark Results

Benchmark parameters: 1000 iterations, 1024KB message size
1000 iterations with 1024KB topic payloads and service responses. Ratios are relative to the C++ result.

| Client Library | Topic (ms) | Service (ms) | Performance Ratio |
| ----------------------- | ---------- | ------------ | ------------------- |
| **rclcpp (C++)** | 168 | 627 | Baseline (fastest) |
| **rclpy (Python)** | 1,618 | 15,380 | 9.6x / 24.5x slower |
| **rclnodejs (Node.js)** | 744 | 927 | 4.4x / 1.5x slower |

_Last updated: August 30, 2025_

**Notes:**

- Topic benchmarks: All libraries completed successfully with 1024KB messages
- Service benchmarks: All libraries completed successfully with 1024KB responses
- Performance ratios are relative to C++ baseline
- C++ shows excellent performance as expected for a compiled language
- Node.js performs significantly better than Python, likely due to V8 optimizations
- Python service performance shows significant overhead with large payloads compared to topics
| rclcpp (C++) | 168 | 627 | Baseline |
| rclpy (Python) | 1,618 | 15,380 | 9.6x / 24.5x slower |
| rclnodejs (Node.js) | 744 | 927 | 4.4x / 1.5x slower |

## Running Benchmarks

### C++ (rclcpp)
Choose one implementation at a time. Start its subscriber or service in terminal 1, then run its publisher or client in terminal 2.

```bash
cd benchmark/rclcpp/
mkdir -p build && cd build
source ~/Download/ros2-linux/local_setup.bash # Adjust path
cmake .. && make
# Run from build directory:
./publisher-stress-test -r 1000 -s 1024
./client-stress-test -r 1000
```
### Topics

### Python (rclpy)
Publishes `std_msgs/msg/UInt8MultiArray`; `-s` sets the array size in KB.

```bash
cd benchmark/rclpy/
source ~/Download/ros2-linux/local_setup.bash # Adjust path
python3 topic/publisher-stress-test.py -r 1000 -s 1024
python3 service/client-stress-test.py -r 1000
```
| Library | Terminal 1: subscriber | Terminal 2: publisher |
| --- | --- | --- |
| rclcpp | `benchmark/rclcpp/build/subscription-stress-test` | `benchmark/rclcpp/build/publisher-stress-test -r 1000 -s 1024` |
| rclpy | `python3 benchmark/rclpy/topic/subscription-stress-test.py` | `python3 benchmark/rclpy/topic/publisher-stress-test.py -r 1000 -s 1024` |
| rclnodejs | `node benchmark/rclnodejs/topic/subscription-stress-test.js` | `node benchmark/rclnodejs/topic/publisher-stress-test.js -r 1000 -s 1024` |

### JavaScript (rclnodejs)
### Services

```bash
cd /path/to/rclnodejs/ # Project root
source ~/Download/ros2-linux/local_setup.bash # Adjust path
node benchmark/rclnodejs/topic/publisher-stress-test.js -r 1000 -s 1024
node benchmark/rclnodejs/service/client-stress-test.js -r 1000
```

## Test Workflow

For complete tests, run subscriber/service first, then publisher/client:

**Topic Test:**

```bash
# Terminal 1: Start subscriber (adjust for your language)
python3 topic/subscription-stress-test.py # Python
./subscription-stress-test # C++ (from build dir)
node benchmark/rclnodejs/topic/subscription-stress-test.js # Node.js

# Terminal 2: Run publisher benchmark
python3 topic/publisher-stress-test.py -r 1000 -s 1024 # Python
./publisher-stress-test -r 1000 -s 1024 # C++ (from build dir)
node benchmark/rclnodejs/topic/publisher-stress-test.js -r 1000 -s 1024 # Node.js
```

**Service Test:**

```bash
# Terminal 1: Start service (adjust for your language)
python3 service/service-stress-test.py -s 1024 # Python
./service-stress-test -s 1024 # C++ (from build dir)
node benchmark/rclnodejs/service/service-stress-test.js -s 1024 # Node.js

# Terminal 2: Run client benchmark
python3 service/client-stress-test.py -r 1000 # Python
./client-stress-test -r 1000 # C++ (from build dir)
node benchmark/rclnodejs/service/client-stress-test.js -r 1000 # Node.js
```
Calls `nav_msgs/srv/GetMap`; `-s` sets the service's map data size in KB.

## Message Types
| Library | Terminal 1: service | Terminal 2: client |
| --- | --- | --- |
| rclcpp | `benchmark/rclcpp/build/service-stress-test -s 1024` | `benchmark/rclcpp/build/client-stress-test -r 1000` |
| rclpy | `python3 benchmark/rclpy/service/service-stress-test.py -s 1024` | `python3 benchmark/rclpy/service/client-stress-test.py -r 1000` |
| rclnodejs | `node benchmark/rclnodejs/service/service-stress-test.js -s 1024` | `node benchmark/rclnodejs/service/client-stress-test.js -r 1000` |

- **Topics**: `std_msgs/msg/UInt8MultiArray` (configurable size)
- **Services**: `nav_msgs/srv/GetMap` (map data request/response)
### What the Timers Measure

## Notes
Timing differs between runners. The JavaScript topic timer covers node, publisher, and message setup, then publishing, not subscriber delivery or round-trip latency. The service timer also includes node/client setup and service discovery.

- All benchmarks use high-precision timing for accurate measurements
- C++ provides baseline performance; Python/JavaScript show expected interpreted language overhead
- All implementations are now working correctly across the three client libraries
- Results vary by system configuration; use relative comparisons between client libraries
- Service benchmarks involve request-response cycles with substantial data payloads (OccupancyGrid maps)
These are total run times, not per-message latencies. Middleware, payload size, and hardware affect the results.
Loading
Loading