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,assets].
• asset_uri_allowlist: List of regular expressions (ECMAScript grammar) of allowed asset URIs. Uses the resource_retriever to resolve package://, file:// or http(s):// URIs. Note that this list should be carefully configured such that no confidential files are accidentally exposed over the websocket connection. As an extra security measure, URIs containing two consecutive dots (..) are disallowed as they could be used to construct URIs that would allow retrieval of confidential files if the allowlist is not configured strict enough (e.g. package://<pkg_name>/../../../secret.txt). Defaults to ["^package://(?:\w+/)*\w+\.(?:dae|fbx|glb|gltf|jpeg|jpg|mtl|obj|png|stl|tif|tiff|urdf|webp|xacro)$"].
• (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 1) service_type_retrieval_timeout_ms: Max number of milliseconds for retrieving a services type information. Defaults to 250.
• (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 25.
• (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.7.3 (2023-10-25)

• Fix [asset_uri_whitelist]{.title-ref} regex backtracking issue, add more extensions (#270)
• [ROS1] Fix callback accessing invalid reference to promise (#268)
• Contributors: Hans-Joachim Krauch

0.7.2 (2023-09-12)

• Fix invalid pointers not being caught (#265)
• Make ROS1 service type retrieval more robust (#263)
• Contributors: Hans-Joachim Krauch

0.7.1 (2023-08-21)

• Communicate double / double array parameters with type info, explicitly cast when set from integer (#256)
• Make ROS 2 smoke tests less flaky (#260)
• Add debug config for ros2 smoke test (#257)
• Handle client disconnection in message handler thread (#259)
• Reduce smoke test flakiness (#258)
• Server code improvements (#250)
• Contributors: Hans-Joachim Krauch

0.7.0 (2023-07-12)

• Fix ROS2 launch file install rule not installing launch subfolder (#243)
• Support building with boost asio (#247)
• Avoid usage of tmpnam() for creating random filename (#246)
• Implement ws-protocol\'s [fetchAsset]{.title-ref} specification (#232)
• Use [--include-eol-distros]{.title-ref} for [rosdep]{.title-ref} to fix melodic builds (#244)
• Reduce logging severity for parameter retrieval logs (#240)
• Contributors: Hans-Joachim Krauch, Micah Guttman

0.6.4 (2023-07-05)

• Assume publisher qos depth of 1 if the middleware reports the qos history as unknown (#239)
• devcontainer: Use [--include-eol-distros]{.title-ref} for [rosdep update]{.title-ref} (#237)
• Contributors: Hans-Joachim Krauch

0.6.3 (2023-06-16)

• Add iron build to CI (#234)
• Fix QoS history being unknown when copied from existing publisher (#233)
• Extract ROS 2 bridge header (#228)
• Contributors: Hans-Joachim Krauch, Milan Vukov

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