Skip to content
Design System
GitHub

Connect to ROS

Feed the robotics components from ROS 1 or ROS 2 through rosbridge, with no ROS library: one connection that reconnects, hooks for topics, publishers and services, converters from each message to a component's props, and a drive link that stops safely.

Live example

Disconnectedws://robot.local:9090

Loading the map

Loading the map

Hold to drive. Release to stop. Arrow keys or W A S D drive while held. Space stops.

Hold to drive

Arm · UR10e

Loading joint states…

The code below, running against a rosbridge simulated in this page (no robot, no network). Drive with the pad or the arrow keys, set a goal on the map, or drop the link to watch it reconnect and stop.

1. Start rosbridge on the robot

rosbridge_suite serves ROS topics and services over a WebSocket as JSON, for ROS 1 and ROS 2 alike. From a page served over https, put it behind a TLS proxy and use wss://: browsers block ws:// from secure pages.

Terminal
# On the robot (ROS 2). Listens on ws://<robot>:9090 and starts rosapi beside it.
sudo apt install ros-$ROS_DISTRO-rosbridge-suite
ros2 launch rosbridge_server rosbridge_websocket_launch.xml

# ROS 1
roslaunch rosbridge_server rosbridge_websocket.launch

2. Install

use-ros brings ros, the client and the converters. No npm package is added: the protocol is spoken directly over the browser's WebSocket.

Terminal
npx shadcn add @syncrobotic/use-ros @syncrobotic/robot-map @syncrobotic/teleop-pad @syncrobotic/joint-state

3. Wire the components

One RosProvider per robot; each hook subscribes while its component is on screen, and two components on one topic share one subscription. Convert a message once per message, in a useMemo keyed on it.

app/robot/robot-page.tsx
"use client"

import * as React from "react"
import { Crosshair, RotateCw } from "lucide-react"
import { RosProvider, useRosConnection, useRosPublisher, useRosStatus, useRosTopic } from "@/hooks/use-ros"
import {
  goalToPoseStamped,
  jointStateToJoints,
  laserScanToScan,
  occupancyGridToGrid,
  poseToRobotMapPose,
  stampToMs,
  teleopToTwist,
  type RosJointLimits,
  type RosJointState,
  type RosLaserScan,
  type RosOccupancyGrid,
  type RosPoseLike,
  type RosPoseStamped,
  type RosTwist,
} from "@/lib/ros"
import { StatusGlyph } from "@/components/status-glyph"
import { TeleopPad, type TeleopCommand } from "@/components/teleop-pad"
import { Button } from "@/components/ui/button"
import { JointState } from "@/components/ui/joint-state"
import { gridToPlan, RobotMap, RobotMapList, type RobotMapPose, type RobotMapRobot } from "@/components/ui/robot-map"
import { Spinner } from "@/components/ui/spinner"

// A robot's page fed from its rosbridge: the map, its pose and its laser scan on RobotMap, a goal sent from the map, the
// pad driving /cmd_vel, and the arm's /joint_states. The docs page shows this file as it is and runs it against a
// rosbridge played in the browser.

/** The connection in words and shape: the blue spinner only while connecting, grey when lost, and a way to try now. */
export function RosConnectionLine() {
  const status = useRosStatus()
  const ros = useRosConnection()
  const word = {
    open: "Connected",
    connecting: status.attempt > 0 ? "Reconnecting" : "Connecting",
    error: "Connection lost",
    closed: "Disconnected",
  }[status.state]
  return (
    <div className="flex min-h-(--h-sm) flex-wrap items-center gap-x-3 gap-y-1 text-sm">
      <p role="status" className="flex items-center gap-2">
        {status.state === "connecting" ? (
          <span aria-hidden="true" className="flex">
            <Spinner className="size-4 text-info" delay={0} />
          </span>
        ) : (
          <StatusGlyph status={status.state === "open" ? "active" : "offline"} />
        )}
        <span className={status.state === "open" ? "font-medium" : "text-muted-foreground"}>{word}</span>
        <span className="font-mono text-xs text-muted-foreground">
          {ros.url}
          {status.state === "open" && status.latencyMs !== undefined && ` · ${status.latencyMs} ms`}
        </span>
      </p>
      {(status.state === "error" || status.state === "closed") && (
        <Button variant="outline" size="sm" onClick={ros.reconnectNow}>
          <RotateCw aria-hidden="true" />
          Reconnect
        </Button>
      )}
    </div>
  )
}

/** The map, where the robot is and what its laser sees; in goal mode a click sends it a Nav2 goal on /goal_pose. */
export function SiteMap({ robotId = "amr-7", name = "AMR-07" }: { robotId?: string; name?: string }) {
  const map = useRosTopic<RosOccupancyGrid>("/map", "nav_msgs/OccupancyGrid")
  const amcl = useRosTopic<RosPoseLike>("/amcl_pose", "geometry_msgs/PoseWithCovarianceStamped")
  // People read a scan; nobody steers by it at 40 Hz. Five a second is plenty and spares the link.
  const scan = useRosTopic<RosLaserScan>("/scan", "sensor_msgs/LaserScan", { throttleMs: 200 })
  const sendGoal = useRosPublisher<RosPoseStamped>("/goal_pose", "geometry_msgs/PoseStamped")
  const [selected, setSelected] = React.useState<string | null>(null)
  const [picking, setPicking] = React.useState(false)
  const [goal, setGoal] = React.useState<RobotMapPose | null>(null)

  // Each conversion runs once per message: robot-map draws the grid again for every new array.
  const grid = React.useMemo(() => (map ? occupancyGridToGrid(map) : undefined), [map])
  const frame = React.useMemo(() => (grid ? gridToPlan(grid) : undefined), [grid])
  const scans = React.useMemo(() => (scan ? [laserScanToScan(scan, robotId)] : []), [scan, robotId])
  const robots = React.useMemo<RobotMapRobot[]>(
    () => (frame && amcl ? [{ id: robotId, name, status: "normal", statusLabel: "Ready", ...poseToRobotMapPose(amcl, frame) }] : []),
    [frame, amcl, robotId, name],
  )

  const onGoal = (g: RobotMapPose) => {
    if (!frame) return
    setGoal(g)
    setPicking(false)
    sendGoal(goalToPoseStamped(g, frame))
  }

  return (
    <div className="flex min-w-0 flex-col gap-3">
      <div className="flex justify-end">
        <Button variant="outline" size="sm" onClick={() => setPicking((p) => !p)} disabled={!frame}>
          <Crosshair aria-hidden="true" />
          {picking ? "Cancel goal" : "Set a goal"}
        </Button>
      </div>
      <RobotMap
        label="Map of the warehouse"
        grid={grid}
        scans={scans}
        robots={robots}
        loading={!grid}
        selectedId={selected}
        onSelect={setSelected}
        mode={picking ? "goal" : "view"}
        goal={goal}
        onGoal={onGoal}
      />
      <RobotMapList label="Robots in the warehouse" robots={robots} loading={!grid} selectedId={selected} onSelect={setSelected} />
    </div>
  )
}

/** The pad on /cmd_vel. The publisher sends a zero Twist on unmount, on a hidden page and when the link drops. */
export function Drive({ name = "AMR-07" }: { name?: string }) {
  const publish = useRosPublisher<RosTwist>("/cmd_vel", "geometry_msgs/Twist")
  const [refused, setRefused] = React.useState(false)
  const onCommand = (c: TeleopCommand) => {
    // Your robot's top speeds. Clamp on the robot too: never trust the client alone.
    const sent = publish(teleopToTwist(c, { maxLinear: 0.8, maxAngular: 1.5 }))
    // Not sent: the link is down, or it came back while the stick was still held. Lifting the finger sends a stop and
    // re-arms the pad, so a drive never resumes by itself.
    setRefused(!sent)
  }
  return (
    <div className="flex flex-col gap-2">
      <TeleopPad onCommand={onCommand} labels={{ name: `Drive ${name}` }} />
      <p className="flex min-h-5 items-center gap-2 text-sm" aria-live="polite">
        {refused && (
          <>
            <StatusGlyph status="warning" />
            Not sent: let go and hold again to drive
          </>
        )}
      </p>
    </div>
  )
}

// The URDF's limits for each joint, which /joint_states does not carry.
const limits: RosJointLimits = {
  shoulder_pan_joint: { lower: -6.28, upper: 6.28 },
  shoulder_lift_joint: { lower: -6.28, upper: 6.28 },
  elbow_joint: { lower: -3.14, upper: 3.14 },
  wrist_1_joint: { lower: -6.28, upper: 6.28 },
  wrist_2_joint: { lower: -6.28, upper: 6.28 },
  wrist_3_joint: { lower: -6.28, upper: 6.28 },
}

/** The arm's joints against their limits; the message's stamp tells a still arm from a silent one. */
export function Arm() {
  const msg = useRosTopic<RosJointState>("/joint_states", "sensor_msgs/JointState")
  const joints = React.useMemo(() => (msg ? jointStateToJoints(msg, { limits }) : []), [msg])
  return <JointState label="Arm · UR10e" joints={joints} loading={!msg} updatedAt={stampToMs(msg?.header?.stamp)} />
}

/** The page: one connection for everything on it. */
export function RobotPage() {
  return (
    <RosProvider url="ws://robot.local:9090">
      <div className="@container flex flex-col gap-4">
        <RosConnectionLine />
        <div className="grid gap-6 @3xl:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
          <SiteMap />
          <Drive />
        </div>
        <Arm />
      </div>
    </RosProvider>
  )
}

From message to component

MessageTopicConverterInto
nav_msgs/OccupancyGrid/map, /global_costmap/costmapoccupancyGridToGrid(msg)RobotMap grid, costmap
sensor_msgs/LaserScan/scanlaserScanToScan(msg, robotId)RobotMap scans
geometry_msgs/PoseWithCovarianceStamped/amcl_poseposeToRobotMapPose(msg, gridToPlan(grid))RobotMap robots: x, y, heading
geometry_msgs/PoseStamped (out)/goal_posegoalToPoseStamped(goal, frame)from RobotMap onGoal
sensor_msgs/PointCloud2/pointspointCloud2ToPoints(msg)PointCloud points, intensity
sensor_msgs/JointState/joint_statesjointStateToJoints(msg, { limits })JointState joints
sensor_msgs/JointState/joint_statesjointStateToRecord(msg) (robot-model)RobotModel joints
geometry_msgs/Twist (out)/cmd_velteleopToTwist(command, { maxLinear, maxAngular })from TeleopPad onCommand
std_msgs/HeaderanystampToMs(msg.header.stamp)updatedAt (stale detection)

rosbridge sends uint8[] (PointCloud2 data) as base64 and int8[] (OccupancyGrid data) as numbers; NaN and ±Infinity in a LaserScan arrive as null. The converters read all of these. Poses must be in the map frame; a scan is drawn from the robot's centre.

Driving safely over a browser

  • rosbridge has no watchdog. If the tab freezes, the laptop sleeps or the network drops mid-drive, the last command the robot received may be a moving one, and nothing in the browser can reach it until the link is back. The robot must stop by itself when commands stop arriving: cmd_vel_timeout on ros2_control's diff_drive_controller (0.5 s by default), a timeout per input in twist_mux, or your base driver's own. TeleopPad sends ten commands a second while held, so a timeout of three periods (300 ms) never trips while someone is driving.
  • useRosPublisher on a geometry_msgs/Twist or TwistStamped topic sends a zero Twist when the component unmounts, when the page is hidden, and when the connection closes, if its last command was not already a stop.
  • A drive command is never queued: while the link is down it is dropped (publish returns false), so a command cannot arrive late and move a robot nobody is steering any more. The stop sent on a dropped link is queued instead, never expires, and is the first thing the robot hears when the link returns.
  • After a dropped link or a hidden page, drive commands are refused until the app publishes a stop. TeleopPad publishes one when the finger lifts, so the operator lets go and presses again: a stick still held when the link returns does not drive. Say so on screen when publish returns false.
  • The heartbeat (heartbeat: true, which calls /rosapi/get_time) notices a link that died without closing, which a WebSocket can take minutes to report, and shows the latency. Turn it on wherever someone drives.
  • None of this is an emergency stop. Keep the robot's own stop (a hardware button, a safety PLC) for that; StopButton on screen sends a request, as everything here does.

Connection state

useRosStatus() gives the state, the last error, the attempt and, with the heartbeat, the latency. Show it in words and shape wherever a robot is driven or watched. After a drop the connection waits up to 0.5 s, then up to 1, 2, 4 and 8 s, never more than 10 s, each wait a random point in its upper half so many tabs do not return together; it subscribes and advertises again on every new socket.

StateShow
connectingThe blue spinner and Connecting (Reconnecting after a drop): a process being waited on.
openConnected, with the latency when the heartbeat is on. Calm: no colour.
errorConnection lost, grey with the offline shape, and Reconnect. Views keep their last message: say they are not live.
closedDisconnected: the app closed it, or has not connected yet.

API

API
// @/lib/ros: no React, no dependencies
createRosConnection({ url, reconnect?, heartbeat?, connectTimeoutMs?, maxQueue?, queueTtlMs?, WebSocket? }): RosConnection
  connection.connect() / close() / reconnectNow()
  connection.getStatus(): { state: "connecting" | "open" | "closed" | "error"; error?; attempt; retryAt?; latencyMs? }
  connection.subscribe(topic, type, listener, { throttleMs?, queueLength? }): () => void
  connection.publisher(topic, type, { stopMessage?, isStop? }): { publish(msg): boolean; stop(); release() }
  connection.call(service, request, { type?, timeoutMs? }): Promise<response>

// @/hooks/use-ros
<RosProvider url="ws://robot:9090" reconnect? heartbeat?>   or   <RosProvider connection={connection}>
useRosStatus(): RosStatus
useRosTopic<T>(name, type, { throttleMs?, queueLength?, enabled? }): T | undefined
useRosPublisher<T>(name, type, { stopMessage? }): (message: T) => boolean
useRosService<Req, Res>(name, type?, { timeoutMs? }): (request: Req) => Promise<Res>

Each item's page has its source: useRos and ROS.

Not covered

  • JSON only (compression: "none"): CBOR, CBOR-RAW and PNG compression are not read. Clouds and maps arrive as base64 or number arrays and are decoded in the browser; throttle large topics.
  • Topics and services. Actions (send_action_goal), services served by the browser (advertise_service) and QoS profiles are not covered; connection.call and a topic cover Nav2's /goal_pose and most robot APIs.
  • One message type per topic per connection: the first subscriber's type is used.