/ros2-web-integration

name: ros2-web-integration
description: >
  Patterns and best practices for integrating ROS2 systems with web technologies including REST APIs,
  WebSocket bridges, and browser-based robot interfaces. Use this skill when building web dashboards
  for robots, streaming camera feeds to browsers, exposing ROS2 services as REST endpoints, or
  implementing bidirectional WebSocket communication between web UIs and ROS2 nodes. Trigger whenever
  the user mentions rosbridge, rosbridge_suite, roslibjs, FastAPI with ROS2, Flask with rclpy,
  WebSocket for robot telemetry, MJPEG streaming, WebRTC for robots, REST API wrapping ROS2 services,
  web-based robot control, browser robot interface, robot dashboard, CORS configuration for robots,
  or any web-to-ROS2 bridge pattern. Also trigger for authentication on robot web interfaces, rate
  limiting sensor streams, video streaming from robot cameras to browsers, or running async web
  frameworks alongside the ROS2 executor. Covers rosbridge_suite, FastAPI, Flask, WebSocket, and
  WebRTC approaches.

ROS2 Web Integration Skill

When to Use This Skill

• Building a web dashboard to monitor or control a robot running ROS2
• Streaming camera feeds (MJPEG, WebRTC, compressed WebSocket) from a robot to a browser
• Exposing ROS2 services and actions as REST API endpoints
• Implementing bidirectional WebSocket communication between a web UI and ROS2 nodes
• Setting up rosbridge_suite for quick prototyping or foxglove integration
• Writing a custom FastAPI or Flask bridge to ROS2 for production deployments
• Adding authentication, rate limiting, or CORS to robot web interfaces
• Running an async web server (uvicorn) alongside the rclpy executor without deadlocks
• Publishing teleop commands from a browser joystick to cmd_vel
• Serving ROS2 parameter configuration pages or diagnostic dashboards over HTTP

Architecture Overview

Comparison Table

| Feature | rosbridge_suite | Custom FastAPI Bridge | Custom Flask Bridge | |---|---|---|---| | Latency | ~5-15ms (WebSocket) | ~2-5ms (WebSocket), ~10-30ms (REST) | ~10-50ms (REST only without extensions) | | Throughput | Medium (JSON serialization overhead) | High (binary WebSocket, async) | Low-Medium (sync, GIL-bound) | | Auth | Basic (rosauth, limited) | Full (JWT, OAuth2, API keys) | Full (Flask-Login, JWT) | | Complexity | Low (launch and connect) | Medium (must manage two event loops) | Medium (must manage threading) | | Video Streaming | Requires separate web_video_server | Native (MJPEG, WebSocket binary) | MJPEG via generator responses | | Production Ready | No (exposes full topic graph) | Yes | Yes (with gunicorn) | | When to Use | Prototyping, foxglove, quick demos | Production APIs, high-perf streaming | Simple internal tools, legacy systems |

When to Use rosbridge vs Custom Bridge

Use **rosbridge_suite** when:

• You need a working bridge in under 10 minutes
• The client is foxglove, webviz, or another rosbridge-aware tool
• Security is not a concern (local network, demo environment)
• You do not need custom business logic between web and ROS2

Use a **custom bridge** (FastAPI/Flask) when:

• You need authentication, authorization, or rate limiting
• You want to expose only specific topics/services (not the entire ROS2 graph)
• You need to transform or aggregate data before sending to the client
• You need REST endpoints for integration with non-WebSocket clients
• You are streaming video and need control over encoding and quality
• The system is deployed in production or on a public network

Pattern 1: rosbridge_suite

Installation and Launch

# Install rosbridge_suite
sudo apt install ros-${ROS_DISTRO}-rosbridge-suite

# Launch with default settings (port 9090)
ros2 launch rosbridge_server rosbridge_websocket_launch.xml

# Launch with custom port and SSL
ros2 launch rosbridge_server rosbridge_websocket_launch.xml \
    port:=9091 \
    ssl:=true \
    certfile:=/etc/ssl/certs/robot.pem \
    keyfile:=/etc/ssl/private/robot.key

# Launch with authentication (rosauth)
ros2 launch rosbridge_server rosbridge_websocket_launch.xml \
    authenticate:=true

JavaScript Client (roslibjs)

// Connect to rosbridge WebSocket
const ros = new ROSLIB.Ros({ url: 'ws://robot-host:9090' });

ros.on('connection', () => console.log('Connected to rosbridge'));
ros.on('error', (err) => console.error('Connection error:', err));
ros.on('close', () => console.log('Connection closed'));

// Subscribe to compressed camera images
const imageTopic = new ROSLIB.Topic({
  ros: ros,
  name: '/camera/image/compressed',
  messageType: 'sensor_msgs/msg/CompressedImage',
  // Throttle to 10 Hz to avoid flooding the browser
  throttle_rate: 100,
  // Queue size of 1 — drop stale frames
  queue_size: 1
});

imageTopic.subscribe((msg) => {
  // msg.data is base64-encoded JPEG
  const imgElement = document.getElementById('camera-feed');
  imgElement.src = 'data:image/jpeg;base64,' + msg.data;
});

// Call a ROS2 service
const getMapSrv = new ROSLIB.Service({
  ros: ros,
  name: '/map_server/map',
  serviceType: 'nav_msgs/srv/GetMap'
});

getMapSrv.callService(new ROSLIB.ServiceRequest({}), (result) => {
  console.log('Map received:', result.map.info.width, 'x', result.map.info.height);
}, (error) => {
  console.error('Service call failed:', error);
});

// Publish velocity commands from a virtual joystick
const cmdVelTopic = new ROSLIB.Topic({
  ros: ros,
  name: '/cmd_vel',
  messageType: 'geometry_msgs/msg/Twist'
});

function sendVelocity(linearX, angularZ) {
  const twist = new ROSLIB.Message({
    linear: { x: linearX, y: 0.0, z: 0.0 },
    angular: { x: 0.0, y: 0.0, z: angularZ }
  });
  cmdVelTopic.publish(twist);
}

// Publish at 10 Hz while joystick is active; stop on release
let joystickInterval = null;
function onJoystickMove(lx, az) {
  if (!joystickInterval) {
    joystickInterval = setInterval(() => sendVelocity(lx, az), 100);
  }
}
function onJoystickRelease() {
  cle