Important

This repository is currently in Developer Preview mode and not ready for production use. There may be bugs, and APIs and configuration options are subject to change during this period.

ROS Portal

ROS Portal connects a ROS 2 graph to other LiveKit participants (ROS 2 or not) through LiveKit's real-time network, enabling access to a ROS graph from anywhere in the world. It forwards configured ROS topics as schema-described LiveKit DataTracks, republishes allowed remote tracks back into ROS, forwards configured service calls over LiveKit RPC, and streams sensor_msgs/msg/Image topics as LiveKit video. ROS Portal enables low-latency teleoperation, monitoring, and robot-to-cloud communication without exposing DDS across networks.

Quick Start

1. Install ROS Portal. Download the .deb for your ROS 2 distro and architecture and install, or skip this step if running from Docker. See Installation.
2. Configure ROS Portal. Set LiveKit credentials and a YAML config for the topics and services to forward. See Configuration.
3. Run ROS Portal. Start a LiveKit server or connect to your LiveKit Cloud project, then run. See Running.

Or quickly run via Docker for your ROS distribution:

Set LIVEKIT_* environment variables and define a configuration file ros_portal.yaml as described in Configuration, then run:

docker login

# LIVEKIT_URL and LIVEKIT_TOKEN are set in the environment
# Assumes ros_portal.yaml exists in same location

# Change to desired ROS distro, or skip this if already in a ROS environment
export ROS_DISTRO=jazzy
docker run --rm \
  --network host \
  -e LIVEKIT_URL \
  -e LIVEKIT_TOKEN \
  --volume $(pwd)/ros_portal.yaml:/config/ros_portal.yaml:ro \
  livekit/ros-portal:$ROS_DISTRO \
  ros2 launch ros_portal ros_portal.launch.py \
  config_path:=/config/ros_portal.yaml

User Guides

• Installation: Installing LiveKit dependencies and ROS Portal.
• Configuration: Configuring LiveKit environment variables and the ROS Portal configuration file.
• Running: Running ROS Portal against LiveKit Cloud or local server.
• Docker: Details for the ROS Portal Docker image.
• Remote ROS2 CLI calls: Remote ros2 command services backed by LiveKit RPC.
• Diagnostics: /diagnostics fields and aggregator setup.
• Tutorials: Run the ROS Turtlesim example across two graphs.

Developer Guides

• Development: devcontainer layout, SSH agent forwarding, Docker image caching, and C++ tooling.
• Testing: unit and integration test commands and required LiveKit test environment.
• Current limitations: known implementation limits and follow-up work.

Design Reference

• Architecture: ROS Portal data flow, LiveKit DataTracks, LiveKit RPC, message paths, and QoS selection.
• Data-track schemas: ROS message schema transport, registration, validation, and failure behavior.

Packages of Interest

• ros_portal: ROS Portal node, launch files, default config, and ROS Portal-specific tests.
• ros_portal_config: schema-driven YAML config parser and generated C++ config types.
• ros_portal_msgs: custom service interfaces for remote ros2 CLI operations.
• ros_portal_tutorials: tutorials for using ROS Portal in a variety of scenarios.

Other package READMEs under src/ document package-specific setup, fixtures, and examples.

Robots

Complete robot stacks that consume ROS Portal live in their own repositories, so that hardware-specific drivers, launch trees, and container images stay out of this one:

• cobra_flex_ros: teleoperation for the Waveshare Cobra Flex rover.
• waver_ros: teleoperation and autonomous navigation for the 4-wheeled Waveshare WAVE ROVER on a Raspberry Pi.