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
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.
# 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.launch2. 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.
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.
"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
| Message | Topic | Converter | Into |
|---|---|---|---|
| nav_msgs/OccupancyGrid | /map, /global_costmap/costmap | occupancyGridToGrid(msg) | RobotMap grid, costmap |
| sensor_msgs/LaserScan | /scan | laserScanToScan(msg, robotId) | RobotMap scans |
| geometry_msgs/PoseWithCovarianceStamped | /amcl_pose | poseToRobotMapPose(msg, gridToPlan(grid)) | RobotMap robots: x, y, heading |
| geometry_msgs/PoseStamped (out) | /goal_pose | goalToPoseStamped(goal, frame) | from RobotMap onGoal |
| sensor_msgs/PointCloud2 | /points | pointCloud2ToPoints(msg) | PointCloud points, intensity |
| sensor_msgs/JointState | /joint_states | jointStateToJoints(msg, { limits }) | JointState joints |
| sensor_msgs/JointState | /joint_states | jointStateToRecord(msg) (robot-model) | RobotModel joints |
| geometry_msgs/Twist (out) | /cmd_vel | teleopToTwist(command, { maxLinear, maxAngular }) | from TeleopPad onCommand |
| std_msgs/Header | any | stampToMs(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_timeouton ros2_control's diff_drive_controller (0.5 s by default), atimeoutper 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/orTwist TwistStampedtopic 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:, which callstrue /rosapi/) 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.get_time - 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.
| State | Show |
|---|---|
| connecting | The blue spinner and Connecting (Reconnecting after a drop): a process being waited on. |
| open | Connected, with the latency when the heartbeat is on. Calm: no colour. |
| error | Connection lost, grey with the offline shape, and Reconnect. Views keep their last message: say they are not live. |
| closed | Disconnected: the app closed it, or has not connected yet. |
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:): 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."none" - Topics and services. Actions (
send_action_goal), services served by the browser (advertise_service) and QoS profiles are not covered;connection.calland a topic cover Nav2's/goal_poseand most robot APIs. - One message type per topic per connection: the first subscriber's type is used.