Skip to content

Latest commit

 

History

History
138 lines (103 loc) · 7.41 KB

README.md

File metadata and controls

138 lines (103 loc) · 7.41 KB
Raw

foxglove_bridge

ROS Melodic version ROS Noetic version ROS Galactic version ROS Humble version ROS Rolling version

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.
  • (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) max_qos_depth: Maximum depth used for the QoS profile of subscriptions. Defaults to 10.
  • (ROS 2) capabilities: List of supported server capabilities. Defaults to [clientPublish,parameters,parametersSubscribe,services,connectionGraph].

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.