rosbridge_suite: a JSON door into ROS for browsers and other languages

What the bridge actually does

rosbridge provides a JSON interface to ROS, allowing any client to send JSON to publish or subscribe to ROS topics, call ROS services and more. It supports a variety of transport layers, including WebSockets and TCP, and the protocol itself is specified in `ROSBRIDGE_PROTOCOL.md` in the repository.

The design follows from that first sentence. In a normal ROS system, a node is a process that links against the ROS client libraries, and it joins a graph that is discovered and configured through the middleware underneath. That is efficient and it is also a barrier: the client has to be a ROS node, which means it has to be in a language with a client library, and it has to be built with the right middleware.

rosbridge removes both constraints by putting a JSON interface in front of the graph. A browser can open a websocket and send a JSON object that means publish this string on that topic. A Java program can do the same over TCP. Nothing about the client has to know that ROS exists underneath, and the transport is ordinary HTTP-adjacent technology that networks, proxies and browsers already understand.

The trade is the one you would expect. A JSON message over a websocket carries more bytes and more parsing than a native ROS message, and the bridge is a process in the path. For a control loop that runs at hundreds of hertz inside the robot, that is the wrong place for it. For a dashboard, a configuration tool or a language with no ROS client at all, it is the only practical door in.

The project is part of the Robot Web Tools effort, whose point is exactly this, bringing the web to robotics. The licence is BSD, the primary language is Python, the default branch is `ros2`, the last push was on 2026-10-05, and the homepage is `robotwebtools.github.io`. The full documentation is on the ROS wiki, and there is a troubleshooting document in the repository for the common problems.

Four packages with four different jobs

The suite is a set of ROS packages, and the split between them is the architecture.

`rosbridge_suite` is the meta-package, which includes all the rosbridge packages, so that a user can depend on one name and get the whole set. It exists for the usual ROS reason, which is that a metapackage removes the need for consumers to know the internal structure.

`rosbridge_library` is the Python API that receives JSON-formatted strings as input and controls ROS publishers, subscribers and service calls according to the content of those strings. So the library is where the JSON becomes ROS operations, and it is the part that would be reused by any other transport.

`rosbridge_server` is the WebSocket server implementation that exposes the library. The separation is the point: the server is a transport, the library is the behaviour, and either can be replaced.

`rosapi` provides service calls for getting meta-information related to ROS, like topic lists, as well as interacting with the Parameter Server. That is the piece a client needs before it can do anything useful, because a client that wants to show a topic picker has to ask the graph what topics exist, and a client that wants to read a configuration value has to ask the parameter server for it.

The repository root shows the full set, including the message packages that carry the protocol itself: `rosapi/`, `rosapi_msgs/`, `rosbridge_library/`, `rosbridge_msgs/`, `rosbridge_server/`, `rosbridge_suite/`, and `rosbridge_test_msgs/` for the test fixtures. The `rosbridge_msgs` package is the interesting one for an implementer, because it is where the JSON schema becomes a set of compiled message types, which means the protocol is not a loose convention but something both sides compile against.

The client family, and why the interface matters

A rosbridge client is a program that communicates with rosbridge using its JSON API, and the README names four of them.

`roslibjs` is a JavaScript API which communicates with rosbridge over WebSockets. `jrosbridge` is a Java API, also over WebSockets. `roslibpy` is a Python API, and `roslibrust` is a Rust API. All four speak over WebSockets.

The fact that four client libraries exist in four languages, none of which is C++, is the clearest statement of what the bridge is for. A ROS system is normally written in C++ or Python with the native client libraries, and the browser is the one place where those libraries do not exist. A JavaScript client is what makes a web dashboard, an operator console or a JavaScript simulation of a robot possible, and the Java and Rust clients cover the other two situations where a team wants the ROS graph but not the ROS build system.

For a team that is writing a web interface over a robot, the practical question is what the interface needs. The protocol covers publishing and subscribing to topics and calling services, and `rosapi` covers the metadata, so a client that displays sensor topics and lets an operator set parameters is fully covered. A client that wants the middleware's own features, the fine grained quality of service settings or the peer to peer discovery semantics, is outside what the protocol exposes, and that is the boundary worth checking before committing.

The client libraries are separate repositories, and the suite is what they talk to. So the version compatibility between a client and the bridge is a real operational concern, and the release process described later in this article is the answer to it.

Releasing into ROS is a different job from releasing a package

The release process section of the README is the most instructive part of the repository for anyone who ships software inside a platform, and it is worth reproducing because it shows that a release here is a multi-repository, multi-distribution operation.

Releasing requires push access to `RobotWebTools/rosbridge_suite` and to `ros2-gbp/rosbridge_suite-release`, and the steps are four.

The first is to run `catkin_generate_changelog` to update the CHANGELOG.rst files. The second is to manually edit and clean up the changelogs and commit the changes. The third is to run `catkin_prepare_release --bump [major/minor/patch]`, which bumps the versions in the package.xml files and pushes the changes to origin. The fourth is the set of bloom commands, one per distribution:

bloom-release --rosdistro humble rosbridge_suite
bloom-release --rosdistro jazzy rosbridge_suite
bloom-release --rosdistro rolling rosbridge_suite

Once those pull requests are merged, the packages become available for each distribution after the next synchronisation, and the build and sync status is visible on the status pages for Humble, Jazzy and Rolling.

The branch arrangement is the other detail. The Humble release is tracked in the `humble` branch, while Jazzy and later are tracked in the `ros2` branch, and the default branch of this repository is `ros2`. So the repository carries two parallel release lines, and a bug fixed for the newer distributions has to be applied to the older branch as well.

This is why there are no GitHub releases here, and it is the reason a consumer pins a ROS distribution rather than a tag.

Quality Level 3, and a linting stack that says what the project tolerates

The package claims to be in the Quality Level 3 category, with the details in `QUALITY_DECLARATION.md` in the repository. In ROS, the quality levels are a published ladder, and claiming a level is a promise about testing and documentation that a consumer can check against a written definition rather than against a vibe.

The tooling configuration is in `pyproject.toml`, and it is unusually informative because the linter selection is annotated. The project requires Python 3.10 or later, and it uses ruff for formatting with a line length of 100, while the black configuration is kept in step:

[tool.black]
# We use ruff for formatting, but black formatter should be compatible with ruff.
line-length = 100

[tool.ruff]
line-length = 100

Keeping the black configuration in the repository even though ruff does the formatting is a deliberate choice, so that a developer with black installed in their editor does not fight the project over formatting.

The lint rule selection is the interesting part, because the exclusions carry reasons. Enabled are the rule families for annotations, async correctness, the bandit security checks, bugbear, builtins shadowing, comprehensions, timezone handling, the debugger check, the error message rules, the executable rules, future annotations, gettext, implicit string concatenation, import conventions, logging, the logging format rules, pie, pyi, quotes, raise, return, and simplification. Disabled, with an explanation each time, are the blind except rules because it is too much hassle to fix, the boolean trap rules because boolean traps are allowed, the copyright rules because the preview feature is not wanted, the debug rules because prints are allowed, the pytest style rules because there are too many errors to fix for now, the private member rules, and the Airflow, FastAPI, Django and pep420 rules for the frameworks the project does not use.

Each of those comments is a small record of a decision, and together they describe the project more precisely than a style guide would.

Where rosbridge is the wrong tool

Two limits are worth naming, and they pull in opposite directions.

The first is the performance of the path. A rosbridge message is a JSON document that is serialised in Python, sent over a socket, parsed in the client and turned into a native ROS message, and the reverse happens on the way back. The bridge process is in the middle of that. For a control loop, a sensor pipeline that runs at high rate inside the robot, or anything where the last millisecond matters, a native ROS client is the right answer and the bridge is a bottleneck. The suite is for the edges of the system, where the client is a browser or a tool in another language, and using it in the middle is choosing the wrong tool.

The second is the feature set the protocol does not carry. The JSON interface covers topics, services and the metadata that `rosapi` exposes, and it does not carry the middleware's own configuration in full, so a client that needs particular quality of service settings, or the graph's discovery semantics, or the ability to run a node's lifecycle, is asking for more than the protocol provides. That is a real limit of the approach rather than a missing feature, because the protocol is a translation layer, and a translation layer only carries what the translation defines.

The alternative is the native client library in the language of the node, which for a robot written in Python or C++ is not extra work at all, since the ROS clients are already there. The difference in approach is that rosbridge is an interface for people who are not writing ROS nodes, and the native client is an interface for people who are.

There is a third, smaller consideration. A rosbridge deployment is a service that has to be running, on a port, reachable from the client, and its security depends on the network it is exposed to, since the protocol is JSON over a socket with no authentication of its own described in the README. A bridge on a robot network that is reachable from a browser is a bridge on a network somebody can reach, and the deployment has to account for that.

Editorial conclusion

rosbridge_suite fits a team whose clients are not ROS nodes, a browser dashboard, a mobile application, a tool written in another language, or a test harness that should not have to link against ROS. It is the wrong choice for a latency-sensitive path inside the robot, because a JSON message over a websocket is not the same as a DDS message between native nodes, and the alternative is the ROS client library in the same language as the node. Before adopting it, read `ROSBRIDGE_PROTOCOL.md` for the operations you actually need, check the `rosapi` service for the metadata your interface needs, and remember that the release process requires push access to two repositories, so pinning a version means pinning a distribution release rather than a Git tag.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. Project website
4. README
5. RobotWebTools/rosbridge_suite on GitHub