Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/RobotWebTools/rclnodejs
Node.js version of ROS 2.0 client
https://github.com/RobotWebTools/rclnodejs
client javascript nodejs rcl robotics ros ros2 typescript
Last synced: 24 days ago
JSON representation
Node.js version of ROS 2.0 client
- Host: GitHub
- URL: https://github.com/RobotWebTools/rclnodejs
- Owner: RobotWebTools
- License: apache-2.0
- Created: 2017-05-19T14:17:20.000Z (over 7 years ago)
- Default Branch: develop
- Last Pushed: 2024-02-19T01:59:06.000Z (10 months ago)
- Last Synced: 2024-04-27T04:33:16.959Z (8 months ago)
- Topics: client, javascript, nodejs, rcl, robotics, ros, ros2, typescript
- Language: JavaScript
- Homepage: https://docs.ros.org/en/humble/Concepts/Basic/About-Client-Libraries.html?highlight=rclnodejs#community-maintained
- Size: 3.03 MB
- Stars: 297
- Watchers: 28
- Forks: 69
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# rclnodejs - The ROS 2 Client Library for JavaScript
[](https://www.npmjs.com/package/rclnodejs)[](https://coveralls.io/github/RobotWebTools/rclnodejs?branch=develop)[](https://www.npmjs.com/package/rclnodejs)[](https://github.com/RobotWebTools/rclnodejs/blob/develop/LICENSE)[](https://nodejs.org/en/download/releases/)[](https://www.npmjs.com/package/rclnodejs)[](https://github.com/prettier/prettier)
| **ROS Distro\*** | **Linux** | **Windows** |
| :--------------: | :------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------: |
| Jazzy |  |  |
| Humble |  |  |
| Iron |  |  |
\* rclnodejs development and maintenance is limited to the ROS 2 LTS releases and the Rolling development branch
**rclnodejs** is a Node.js client library for the Robot Operating System
([ROS 2](https://www.ros.org/)). It provides tooling and comprehensive
JavaScript and TypeScript APIs for developing ROS 2 solutions capable of
interoperating with ROS 2 nodes implemented in other languages such as
C++ and Python.
Here's an example for creating a ROS 2 node that publishes a string message in a few lines of JavaScript.
```JavaScript
const rclnodejs = require('rclnodejs');
rclnodejs.init().then(() => {
const node = new rclnodejs.Node('publisher_example_node');
const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
publisher.publish(`Hello ROS 2 from rclnodejs`);
node.spin();
});
```
## Documentation
- [Installation](#installation)
- [rclnodejs-cli](#rclnodejs-cli)
- [API Documentation](#api-documentation)
- [Using TypeScript](#using-rclnodejs-with-typescript)
- [Examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example)
- [Electron demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo)
- [Efficient Usage Tips](./docs/EFFICIENCY.md)
- [FAQ and Known Issues](./docs/FAQ.md)
- [Building from Scratch](./docs/BUILDING.md)
- [Contributing](./docs/CONTRIBUTING.md)
## Installation
### Prerequisites
Before installing `rclnodejs` please ensure the following software is installed and configured on your system:
- [Nodejs](https://nodejs.org/en/) version >= 16.13.0.
- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) for details.
**DON'T FORGET TO [SOURCE THE ROS 2 SETUP FILE](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)**
### Installing rclnodejs
Install the rclnodejs version that is compatible with your version of ROS 2 (see table below).
For the most current version of rclnodejs run:
```bash
npm i rclnodejs
```
To install a specific version of rclnodejs use:
```bash
npm i [email protected]
```
- **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#"` to your `package.json` dependency section.
## rclnodejs-cli
[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.
```
_ _ _
_ __ ___| |_ __ ___ __| | ___ (_)___
| '__/ __| | '_ \ / _ \ / _` |/ _ \| / __|
| | | (__| | | | | (_) | (_| | __/| \__ \
|_| \___|_|_| |_|\___/ \__,_|\___|/ |___/
|__/
Usage: rclnodejs [command] [options]
Options:
-h, --help display help for command
Commands:
create-package [options] Create a ROS2 package for Nodejs development.
generate-ros-messages Generate JavaScript code from ROS2 IDL interfaces
help [command] display help for command
```
## API Documentation
API documentation is generated by `jsdoc` and can be viewed in the `docs/` folder or [online doc](https://robotwebtools.github.io/rclnodejs/docs/index.html). To create a local copy of the documentation run `npm run docs`.
## Using rclnodejs with TypeScript
`rclnodejs` API can be used in TypeScript projects. You can find the TypeScript declaration files (\*.d.ts) in the `types/` folder.
Your `tsconfig.json` file should include the following compiler options:
```jsonc
{
"compilerOptions": {
"module": "commonjs",
"moduleResolution": "node",
"target": "es6"
// your additional options here
}
}
```
Here's a short `rclnodejs` TypeScript example:
```typescript
import * as rclnodejs from 'rclnodejs';
rclnodejs.init().then(() => {
const node = new rclnodejs.Node('publisher_example_node');
const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
publisher.publish(`Hello ROS 2 from rclnodejs`);
node.spin();
});
```
The benefits of using TypeScript become evident when working with more complex use-cases. ROS messages are defined in the `types/interfaces.d.ts` module. This module is updated as part of the `generate-ros-messages` process described in the next section.
## ROS2 Interface Message Generation (important)
ROS components communicate by sending and receiving messages described
by the interface definition language (IDL). ROS client libraries such as
rclnodejs are responsible for converting these IDL message descriptions
into source code of their target language. For this, rclnodejs provides
the npm binary`generate-ros-messages` script that reads the IDL
message files of a ROS environment and generates corresponding JavaScript
message interface files. Additionally, the tool generates the TypeScript
`interface.d.ts` file containing declarations for each IDL message file.
Learn more about ROS interfaces and IDL [here](https://docs.ros.org/en/jazzy/Concepts/Basic/About-Interfaces.html).
In the following example rclnodejs loads a generated JavaScript message file corresponding to the ROS `std_msgs/msg/String' definition.
```
import * as rclnodejs from 'rclnodejs';
let stringMsgObject = rclnodejs.createMessageObject('std_msgs/msg/String');
stringMsgObject.data = 'hello world';
```
### Maintaining Generated JavaScript Message Files
Message files are generated as a post-install step of the rclnodejs
installation process. Thereafter, you will need to manually run the
rclnodejs message generation script when new ROS message packages are installed
for which your ROS2-nodejs project has a dependency.
### Running `generate-ros-messages` Utility
To run the `generate-ros-messages` script from your Nodejs package, use the `npx` utility included in your Nodejs installation.
```
npx generate-ros-messages
```
The newly generated JavaScript files can be found at
`/node_modules/rclnodejs/generated/`.
## Contributing
Please read the [Contributing Guide]() before making a pull request.
Thank you to all the [people](CONTRIBUTORS.md) who already contributed to rclnodejs!
## License
This project abides by the [Apache License 2.0](https://github.com/RobotWebTools/rclnodejs/blob/develop/LICENSE).