Skip to content

About

ROS Portal connects a ROS 2 graph to other LiveKit participants (ROS 2 or not) through LiveKit's real-time network.

Topics

Resources

Contributing

Stars

9 stars

Watchers

1 watching

Forks

Repository files navigation

The LiveKit icon, the name of the repository and some sample code in the background.

CI Humble Jazzy Kilted Lyrical

Important

LiveKit Portal for ROS is in early-access. APIs and configuration options may change during this period. Please raise an issue if you encounter bugs or undesired behavior.

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.

Two robots, each running ROS Portal inside its own ROS Graph, join one LiveKit room with an operator app and a recorder. Topics travel as Data Tracks with message schemas, image topics as Video Tracks, and service calls and ROS 2 CLI commands over LiveKit RPC.

Quick Start

  1. Install ROS Portal. Download the .deb for your ROS 2 distro and architecture and install, or skip the download if running from Docker. Install LiveKit CLI and server if running locally, or skip the server installation if connecting to your LiveKit Cloud project.

  2. Configure ROS Portal. Set LiveKit credentials and create a ros_portal.yaml config file for the topics and services to forward.

  3. Run ROS Portal. Start a local LiveKit server or connect to your LiveKit Cloud project (via token environment variables), then run ROS Portal against your ROS graph.

    Or quickly run via Docker for your ROS distribution:

    # Assumptions:
    # LIVEKIT_URL and LIVEKIT_TOKEN are set in the environment
    # 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
    
    # Run the Docker container, passing in relevant environment, volume, and launch arguments
    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

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.

About

ROS Portal connects a ROS 2 graph to other LiveKit participants (ROS 2 or not) through LiveKit's real-time network.

Topics

Resources

Contributing

Stars

9 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages