README

@breq/roslib

A Modern TypeScript Library for ROS

This project is a port of roslibjs to TypeScript using modern ECMAScript features. The API is similar to the original, but not entirely compatible, as many asynchronous functions have been modified to return a Promise instead of accepting a callback.

This project is designed to work with projects in the Robot Web Tools effort. In particular, you must run rosbridge_server on your ROS node in order to connect with this library.

Do not expose a rosbridge endpoint to a public network or to the internet! This is a security risk. If you cannot run your robot's control system on a private network, you should use a reverse proxy on the server-side to restrict access.

ES Modules

This project is ESM only! ECMAScript modules reduce the build complexity, and they enable the use of tree-shaking to make your bundle smaller.

If you are creating a client app using a bundler like Webpack or Rollup, ensure that it can load ES modules.
If you are using Node on the server, set "type": "module" in your package.json file.
If you are developing a package that uses this library, your package must also be ESM only.

Dependencies

@xmldom/xmldom is used to parse Unified Robot Description Format (URDF) files.
bson is used to decode BSON-encoded messages from ROS.
cbor-js is used to decompress CBOR messages from ROS.
EventEmitter2 is used as the base for the Ros class and others to handle events.
isomorphic-ws is used to support WebSocket connections in both Node and browsers.
pngparse is used to decode PNG-encoded messages in Node.

Differences to `roslibjs`

TypeScript

This project is written entirely in TypeScript. This reduces bugs and gives users only the best 100% organic, grass-fed type definitions.

Unit Tests

This project has unit tests written covering Topic, Service and Param functionality. Code coverage is tracked.

Promise-based API

Services are written using ECMAScript Promises. This simplifies writing asynchronous code. Additionally, any functionality relying on ROS Services (such as calls to rosapi) now has a Promise-based API as well.

Narrower Scope

This project does not use Babel, Grunt, or similar build tools--just the TypeScript compiler. As a result, browser bundles are not provided. If you are building a client-side app, use a bundler like Webpack or Rollup. If you would like to target an older runtime (old Node, IE, etc.), you will need to use Babel yourself.

Pure ES Module, No Side Effects

This project is written purely in ES modules with zero side effects. This allows bundlers to remove unused code, and it simplifies use in browsers.

Support for modern bundlers (Vite, Create React App)

The original roslibjs did not work with Rollup due to a quirk in the configuration. Additionally, the original required webworkify to be installed, which is a dead library that does not work with Webpack 5. This project maintains compatibility with the latest bundlers, enabling use with tools like Vite and Create React App.

Use of ES6 Classes

This project replaces the original prototype-based classes with ES6 classes. This improves type-checking and code readability.

Cleaner WebSocket-in-Web-Worker Support

The original roslib relied on hijacking browserify/webworkify to take advantage of its internal implementation for running WebSockets in Web Workers. This library uses the workersocket library instead.

Usage

npm install roslibjs

import { Ros } from "roslib";

const ros = new Ros({
  url: "ws://localhost:9090",
});

const topic = ros.Topic({
  name: "/chatter",
  messageType: "std_msgs/String",
});

topic.subscribe((message) => {
  console.log(message.data);
  topic.unsubscribe();
  ros.close();
});

setTimeout(() => {
  topic.publish({
    data: "Hello, world!",
  });
}, 100);

Troubleshooting

Check that connection is established. You can listen to error and connection events to report them to console. See examples/simple.html for a complete example:
```
ros.on("error", (error) => {
  console.log(error);
});
ros.on("connection", () => {
  console.log("Connection made!");
});
```
Check that you have the websocket server is running on port 9090. For server use, run
```
netstat -a | grep 9090
```
and to check on the client, open http://[host]:9090/ in your browser, replacing [host] with the remote address of your ROS server. You should see a page mentioning "WebSocket Server."

Status

The following portions of the library have not yet been rewritten:

src/actionlib, ActionServer and client related utilities
src/tf, utilities related to the tf2 transform handling library

Usage no npm install needed!