foxglove_bridge

High performance ROS 1 and ROS 2 WebSocket bridge using the Foxglove WebSocket protocol, written in C++.

Motivation

Live debugging of ROS systems has traditionally relied on running ROS tooling such as rviz. This requires either a GUI and connected peripherals on the robot, or replicating the same ROS environment on a network-connected development machine including the same version of ROS, all custom message definitions, etc. To overcome this limitation and allow remote debugging from web tooling or non-ROS systems, rosbridge was developed. However, rosbridge suffers from performance problems with high frequency topics and/or large messages, and the protocol does not support full visibility into ROS systems such as interacting with parameters or seeing the full graph of publishers and subscribers.

The foxglove_bridge uses the Foxglove WebSocket protocol, a similar protocol to rosbridge but with the ability to support additional schema formats such as ROS 2 .msg and ROS 2 .idl, parameters, graph introspection, and non-ROS systems. The bridge is written in C++ and designed for high performance with low overhead to minimize the impact to your robot stack.

Installation

Note: This project is under active development and binary releases of foxglove_bridge might be quite outdated. For the latest features and bug fixes, consider building foxglove_bridge from source.

The foxglove_bridge package is available for ROS 1 Melodic and Noetic, and ROS 2 Humble and Rolling. Earlier releases of ROS will not be supported due to API design and/or performance limitations. The package can be installed with the following command:

$ sudo apt install ros-$ROS_DISTRO-foxglove-bridge

Running the bridge

To run the bridge node, it is recommended to use the provided launch file:

ROS 1

$ roslaunch --screen foxglove_bridge foxglove_bridge.launch port:=8765

<launch>
  <!-- Including in another launch file -->
  <include file="$(find foxglove_bridge)/launch/foxglove_bridge.launch">
    <arg name="port" value="8765" />
    <!-- ... other arguments ... -->
  </include>
</launch>

ROS 2

$ ros2 launch foxglove_bridge foxglove_bridge_launch.xml port:=8765

<launch>
  <!-- Including in another launch file -->
  <include file="$(find-pkg-share foxglove_bridge)/launch/foxglove_bridge_launch.xml"/>
    <arg name="port" value="8765"/>
    <!-- ... other arguments ... -->
  </include>
</launch>

Configuration

Parameters are provided to configure the behavior of the bridge. These parameters must be set at initialization through a launch file or the command line, they cannot be modified at runtime.

• port: The TCP port to bind the WebSocket server to. Must be a valid TCP port number, or 0 to use a random port. Defaults to 8765.
• address: The host address to bind the WebSocket server to. Defaults to 0.0.0.0, listening on all interfaces by default. Change this to 127.0.0.1 to only accept connections from the local machine.
• tls: If true, use Transport Layer Security (TLS) for encrypted communication. Defaults to false.
• certfile: Path to the certificate to use for TLS. Required when tls is set to true. Defaults to "".
• keyfile: Path to the private key to use for TLS. Required when tls is set to true. Defaults to "".
• topic_whitelist: List of regular expressions (ECMAScript grammar) of whitelisted topic names. Defaults to [".*"].
• service_whitelist: List of regular expressions (ECMAScript grammar) of whitelisted service names. Defaults to [".*"].
• param_whitelist: List of regular expressions (ECMAScript grammar) of whitelisted parameter names. Defaults to [".*"].
  • client_topic_whitelist: List of regular expressions (ECMAScript grammar) of whitelisted client-published topic names. Defaults to [".*"].
• send_buffer_limit: Connection send buffer limit in bytes. Messages will be dropped when a connection's send buffer reaches this limit to avoid a queue of outdated messages building up. Defaults to 10000000 (10 MB).
• use_compression: Use websocket compression (permessage-deflate). Suited for connections with smaller bandwith, at the cost of additional CPU load.
• capabilities: List of supported server capabilities. Defaults to [clientPublish,parameters,parametersSubscribe,services,connectionGraph].
• (ROS 1) max_update_ms: The maximum number of milliseconds to wait in between polling roscore for new topics, services, or parameters. Defaults to 5000.
• (ROS 2) num_threads: The number of threads to use for the ROS node executor. This controls the number of subscriptions that can be processed in parallel. 0 means one thread per CPU core. Defaults to 0.
• (ROS 2) min_qos_depth: Minimum depth used for the QoS profile of subscriptions. Defaults to 1. This is to set a lower limit for a subscriber's QoS depth which is computed by summing up depths of all publishers. See also #208.
• (ROS 2) max_qos_depth: Maximum depth used for the QoS profile of subscriptions. Defaults to 10.
• (ROS 2) include_hidden: Include hidden topics and services. Defaults to false.

Building from source

Fetch source and install dependencies

cd <path/to/your/ros_ws>
git clone https://github.com/foxglove/ros-foxglove-bridge.git src/ros-foxglove-bridge
rosdep update
rosdep install --ignore-src --default-yes --from-path src

ROS 1

catkin_make
source install/local_setup.bash
roslaunch --screen foxglove_bridge foxglove_bridge.launch

ROS 2

colcon build --event-handlers console_direct+ --symlink-install
source install/local_setup.bash
ros2 launch foxglove_bridge foxglove_bridge_launch.xml

Clients

Foxglove Studio connects to foxglove_bridge for live robotics visualization.

Development

A VSCode container is provided with a dual ROS 1 and ROS 2 installation and enough tools to build and run the bridge. Some bash aliases are defined to simplify the common workflow. Here's an example of building and running the ROS 2 node:

source /opt/ros/galactic/setup.bash
ros2_build_debug  # or ros2_build_release
ros2_foxglove_bridge

To test the bridge with example data, open another terminal and download the test .mcap files:

./download_test_data.sh

Then start playback:

source /opt/ros/galactic/setup.bash
ros2 bag play -l --clock 100 -s mcap data/nuScenes-v1.0-mini-scene-0061-ros2.mcap

License

foxglove_bridge is released with a MIT license. For full terms and conditions, see the LICENSE file.

Changelog for package foxglove_bridge

0.6.2 (2023-05-11)

• Fix connection graph updates to due incorrect use of std::set_difference (#226)
• Contributors: Ivan Nenakhov

0.6.1 (2023-05-05)

• Fix warning messages not being logged (#224)
• Contributors: Hans-Joachim Krauch

0.6.0 (2023-05-04)

• Add support for nested parameters (ROS1) (#221)
• Catch exceptions thrown in handler functions, send status to client (#210)
• Fix unhandled xmlrpc exception (#218)
• Add support for action topic and services (ROS2) (#214)
• Add parameter to include hidden topics and services (ROS 2) (#216)
• Add workaround for publishers not being cleaned up after they got destroyed (#215)
• Fix error when compiling with C++20 (#212)
• Devcontainer improvements (#213)
• Add parameter for minimum subscription QoS depth (#211)
• Log version and commit hash when node is started (#209)
• Contributors: Hans-Joachim Krauch

0.5.3 (2023-03-31)

• Fix publishers being created with invalid QoS profile (#205)
• Contributors: Hans-Joachim Krauch

0.5.2 (2023-03-29)

• Notify client when Server\'s send buffer limit has been reached (#201)
• Add support for byte array params (#199)
• Do not allow connection output buffer to exceed configured limit (#196)
• Fix exception parameter not being used (#194)
• Contributors: Hans-Joachim Krauch

0.5.1 (2023-03-09)

• Add more exception handling (#191)
• [ROS1] Fix exception not being caught when retrieving service type (#190)
• Devcontainer: Use catkin tools, add build commands for ros1 (#188)
• Contributors: Hans-Joachim Krauch

0.5.0 (2023-03-08)

• Add support for [schemaEncoding]{.title-ref} field (#186)
• Use QoS profile of existing publishers (if available) when creating new publishers (#184)
• Make server more independent of given server configurations (#185)
• Add parameter [client_topic_whitelist]{.title-ref} for whitelisting client-published topics (#181)
• Make server capabilities configurable (#182)
• Fix action topic log spam (#179)
• Remove (clang specific) compiler flag -Wmost (#177)
• Improve the way compiler flags are set, use clang as default compiler (#175)
• Avoid re-advertising existing channels when advertising new channels (#172)
• Allow subscribing to connection graph updates (#167)
• Contributors: Hans-Joachim Krauch

0.4.1 (2023-02-17)

• Run client handler functions in separate thread (#165)
• Fix compilation error due to mismatched new-delete (#163)
• Decouple server implementation (#156)
• ROS2 parameter fixes (#169)
• Fix program crash due to unhandled exception when creating publisher with invalid topic name (#168)
• Contributors: Hans-Joachim Krauch

0.4.0 (2023-02-15)

• Update README with suggestion to build from source, minor fixes
• Do not build docker images, remove corresponding documentation (#159)
• Add option to use permessage-deflate compression (#152)
• Improve launch file documentation, add missing launch file arguments (#158)
• Allow unsetting (deleting) parameters (#145)
• Improve mutex usage (#154)
• Add sessionId to serverInfo (#153)
• Performance improvements (#151)
• Add ROS2 support for calling server-advertised services (#142)
• Add ROS1 support for calling server-advertised services (#136)
• ROS2 smoke test: Increase default timeout 8->10 seconds (#143)
• Fix flaky parameter test (noetic) (#141)
• Always --pull when building docker images in the makefile (#140)
• Fix failed tests not causing CI to fail (#138)
• Fix setting [int]{.title-ref} / [int[]]{.title-ref} parameters not working (ROS 1) (#135)
• Send ROS_DISTRO to clients via metadata field (#134)
• Communicate supported encodings for client-side publishing (#131)
• Fix client advertised channels not being updated on unadvertise (#132)
• Add support for optional request id for [setParameter]{.title-ref} operation (#133)
• Fix exception when setting parameter to empty array (#130)
• Fix wrong parameter field names being used (#129)
• Add parameter support (#112)
• Add throttled logging when send buffer is full (#128)
• Contributors: Hans-Joachim Krauch, John Hurliman

0.3.0 (2023-01-04)

• Add launch files, add install instructions to README (#125)
• Drop messages when connection send buffer limit has been reached (#126)
• Remove references to galactic support from README (#117)
• Add missing build instructions (#123)
• Use a single reentrant callback group for all subscriptions (#122)
• Fix clang compilation errors (#119)
• Publish binary time data when [use_sim_time]{.title-ref} parameter is [true]{.title-ref} (#114)
• Optimize Dockerfiles (#110)
• Contributors: Hans-Joachim Krauch, Ruffin

0.2.2 (2022-12-12)

• Fix messages not being received anymore after unadvertising a client publication (#109)
• Allow to whitelist topics via a ROS paramater (#108)
• Contributors: Hans-Joachim Krauch

0.2.1 (2022-12-05)

• Fix compilation on platforms where size_t is defined as [unsigned int]{.title-ref}
• Contributors: Hans-Joachim Krauch

0.2.0 (2022-12-01)

• Add support for client channels (#66)
• Add smoke tests (#72)
• Update package maintainers (#70)
• [ROS2]: Fix messages not being received anymore after unsubscribing a topic (#92)
• [ROS2]: Refactor node as a component (#63)
• [ROS2]: Fix message definition loading for [.msg]{.title-ref} or [.idl]{.title-ref} files not located in [msg/]{.title-ref} (#95)
• [ROS1]: Mirror ROS 2 node behavior when [/clock]{.title-ref}[ topic is present (]{.title-ref}#99 <https://github.com/foxglove/ros-foxglove-bridge/issues/99>`_)
• [ROS1]: Fix topic discovery function not being called frequently at startup (#68)
• Contributors: Hans-Joachim Krauch, Jacob Bandes-Storch, John Hurliman

0.1.0 (2022-11-21)

• Initial release, topic subscription only