You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> **Note:**rclnodejs development and maintenance is limited to the ROS 2 LTS releases and the Rolling development branch
9
+
> **Note:**Supported ROS 2 distributions include Humble, Jazzy, Kilted, and Rolling.
10
10
11
11
**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.
[Efficient Usage Tips](./docs/EFFICIENCY.md), [FAQ and Known Issues](./docs/FAQ.md), [Building from Scratch](./docs/BUILDING.md), [Contributing](./docs/CONTRIBUTING.md)
38
33
39
34
## Installation
40
35
@@ -66,6 +61,8 @@ rclnodejs ships with prebuilt native binaries for common Linux configurations si
66
61
-**Architectures:** x64, arm64
67
62
-**Node.js:** >= 16.20.2 (N-API compatible)
68
63
64
+
Installations outside this prebuilt matrix automatically fall back to building from source.
65
+
69
66
**Force Building from Source:**
70
67
71
68
If you need to build from source even when a prebuilt binary is available, set the environment variable:
[rclnodejs-cli](https://github.com/RobotWebTools/rclnodejs-cli/) is a companion project we recently launched to provide a commandline interface to a set of developer tools for working with this `rclnodejs`. You may find `rclnodejs-cli` particularly useful if you plan to create ROS 2 node(s) and launch files for working with multiple node orchestrations.
83
+
2. Install the repository dependencies.
81
84
82
85
```bash
83
-
Usage: rclnodejs [command] [options]
86
+
npm install
87
+
```
84
88
85
-
Options:
86
-
-h, --help display helpforcommand
89
+
3. Run a publisher example from this checkout.
87
90
88
-
Commands:
89
-
create-package [options] <package-name> Create a ROS2 package for Nodejs development.
90
-
generate-ros-messages Generate JavaScript code from ROS2 IDL interfaces
You should see messages being published once per second. Explore more runnable examples in [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) and step-by-step guides in [tutorials/](./tutorials/).
96
+
97
+
## rclnodejs-cli
98
+
99
+
[rclnodejs-cli](https://github.com/RobotWebTools/rclnodejs-cli/) is a separate companion project that provides command-line tooling for working with rclnodejs-based ROS 2 applications. It is particularly useful for creating ROS 2 Node.js packages and working with launch files for multi-node orchestration.
100
+
101
+
See the rclnodejs-cli repository for installation instructions and the current command set.
102
+
94
103
## API Documentation
95
104
96
105
API documentation is available [online](https://robotwebtools.github.io/rclnodejs/docs/index.html) or generate locally with `npm run docs`.
@@ -108,7 +117,7 @@ Explore more examples in [electron_demo](https://github.com/RobotWebTools/rclnod
108
117
109
118
## Using rclnodejs with TypeScript
110
119
111
-
TypeScript declaration files are included in the `types/` folder. Configure your `tsconfig.json`:
120
+
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:
112
121
113
122
```jsonc
114
123
{
@@ -177,7 +186,7 @@ npx generate-ros-messages
177
186
178
187
Generated files are located at `<yourproject>/node_modules/rclnodejs/generated/`.
179
188
180
-
> **Note:** This step is not needed for rclnodejs > 1.5.0
189
+
> **Note:** This step is not needed for `rclnodejs > 1.5.0` because bundled interfaces are generated during installation. Rerun this command only after adding new ROS packages to your environment.
181
190
182
191
### IDL Message Generation
183
192
@@ -193,14 +202,14 @@ npm run generate-messages-idl
193
202
194
203
Benchmark results for 1000 iterations with 1024KB messages (Ubuntu 24.04.3 WSL2, i7-1185G7):
195
204
205
+
These numbers are workload- and environment-specific. See [benchmark/README.md](./benchmark/README.md) for the full setup and methodology.
`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.
3
+
`rclnodejs` is a Node.js client library for ROS 2 that provides JavaScript and TypeScript APIs for building ROS 2 applications.
4
4
5
-
\* rclnodejs development and maintenance is limited to all active ROS 2 LTS releases and the Rolling development branch
5
+
Supported ROS 2 distributions include Humble, Jazzy, Kilted, and Rolling.
6
6
7
-
Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
-**Note:**to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json`dependency section.
30
+
-**Note:**To install rclnodejs from GitHub, add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json`dependencies.
33
31
34
32
### Prebuilt Binaries
35
33
36
-
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.
34
+
rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation.
37
35
38
36
**Supported Platforms:**
39
37
@@ -42,26 +40,36 @@ rclnodejs ships with prebuilt native binaries for common Linux configurations si
42
40
-**Architectures:** x64, arm64
43
41
-**Node.js:** >= 16.20.2 (N-API compatible)
44
42
45
-
**Force Building from Source:**
43
+
Installations outside this prebuilt matrix automatically fall back to building from source.
46
44
47
-
If you need to build from source even when a prebuilt binary is available, set the environment variable:
45
+
**Force Building from Source:**
48
46
49
47
```bash
50
48
export RCLNODEJS_FORCE_BUILD=1
51
49
npm install rclnodejs
52
50
```
53
51
54
-
## Documentation
52
+
## Documentation and Examples
53
+
54
+
- API documentation: [robotwebtools.github.io/rclnodejs/docs](https://robotwebtools.github.io/rclnodejs/docs/index.html)
API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) is available online.
60
+
## Message Generation
57
61
58
-
## JavaScript Examples
62
+
rclnodejs generates JavaScript message interfaces and TypeScript declarations during installation for `rclnodejs > 1.5.0`. If you install additional ROS packages later, rerun:
59
63
60
-
Try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started.
64
+
```bash
65
+
npx generate-ros-messages
66
+
```
67
+
68
+
Generated files are written to `<your-project>/node_modules/rclnodejs/generated/`.
61
69
62
70
## Using rclnodejs with TypeScript
63
71
64
-
TypeScript declaration files are included in the `types/` folder. Configure your `tsconfig.json`:
72
+
TypeScript declaration files are included in the package. In most projects, configuring your `tsconfig.json` is sufficient:
65
73
66
74
```jsonc
67
75
{
@@ -73,33 +81,17 @@ TypeScript declaration files are included in the `types/` folder. Configure your
See [TypeScript demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo) for more examples.
89
-
90
-
**Note** that the interface.d.ts file is updated each time the generate_messages.js script is run.
91
-
92
-
## Electron-based Visualization
93
-
94
-
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.
|**🐢 [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. ||
99
-
|**🦾 [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. ||
100
-
101
-
Explore more examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
0 commit comments