@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.

$3

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.

$3

- @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

$3

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

$3

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

$3

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.

$3

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.

$3

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.

$3

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.

$3

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

$3

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
`

`ts
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

1. 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:

`ts
ros.on("error", (error) => {
console.log(error);
});
ros.on("connection", () => {
console.log("Connection made!");
});
`

2. Check that you have the websocket server is running on
port 9090. For server use, run

`bash
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