ROS and ROS 2 over rosbridge with no ROS library: a rosbridge v2 client on the browser's WebSocket (ref-counted subscriptions and advertisements, capped jittered reconnect that resubscribes, a send queue, service calls with a timeout, a zero Twist when a velocity publisher stops or the link drops) and pure converters from OccupancyGrid, LaserScan, PointCloud2, JointState and poses to the kit's components, and from a teleop command and a map goal back to Twist and PoseStamped.
npx shadcn add @syncrobotic/ros Overview
The rosbridge v2 client and the message converters behind use-ros, in plain TypeScript: a connection that reconnects and resubscribes, and pure functions from OccupancyGrid, LaserScan, PointCloud2, JointState and poses to the components' props, and from a teleop command or a map goal back to Twist and PoseStamped.
When to use
- Feeding Robot map, Point cloud, Joint state from ROS messages, whatever brought them (rosbridge, Foxglove, a recorded bag, your backend).
- A rosbridge connection outside React: a worker that decodes clouds, a test, a script.
Use something else
- Connecting React components: useRos, which installs this.
Usage rules
- Pure TypeScript, no React and no npm dependency: the rosbridge v2 client (createRosConnection) and the converters. use-ros is the React layer on top.
- The converters follow the components' documented conventions (robot-map's plan coordinates, REP 103, SI units); do not convert again before passing the result on.
- Only JSON (compression "none"): CBOR and PNG compression are not read. Large clouds and maps arrive as base64 or number arrays and are decoded here.
Source
// @syncrobotic/ros v0.27.0 · update: npx shadcn add @syncrobotic/ros --overwrite
/*
ROS and ROS 2 in the browser, without a ROS library: the rosbridge v2 protocol (rosbridge_suite, which serves both ROS 1
and ROS 2) spoken directly over the browser's WebSocket, and pure converters from the messages to the props the kit's
components take. No React here: `use-ros` is the React layer on top.
What the connection does, so an app does not write it again:
- one wire subscription per topic, however many listeners (ref-counted), resent after every reconnect;
- one advertisement per topic, ref-counted the same way, also resent after a reconnect;
- reconnects with capped, jittered exponential backoff, and says which state it is in (connecting, open, closed, error);
- holds publishes and service calls made while it is not open, and sends them once it is;
- service calls with a timeout;
- for velocity topics, a stop (a zero Twist) when the publisher goes away, when the link drops, and when the app asks.
What it cannot do: rosbridge has no watchdog. If the browser freezes or the network drops mid-drive, the last command the
robot received may be a non-zero one, and nothing this file does can reach the robot until the link is back. The robot
must stop by itself when commands stop arriving (a command timeout in its base controller or twist_mux).
*/
// --- Transport ----------------------------------------------------------------------------------------------------
/**
* The parts of a WebSocket the connection uses. The browser's WebSocket fits; a test passes a fake with the same shape.
* Handlers are assigned, never read back, so a socket may type them more narrowly.
*/
export interface RosSocket {
readonly readyState: number
send(data: string): void
close(code?: number, reason?: string): void
onopen: ((event: unknown) => void) | null
onclose: ((event: { code?: number; reason?: string }) => void) | null
onerror: ((event: unknown) => void) | null
onmessage: ((event: { data: unknown }) => void) | null
}
export type RosSocketConstructor = new (url: string) => RosSocket
/**
* - `connecting`: a socket is opening.
* - `open`: messages flow.
* - `error`: the last attempt failed or the link dropped; `retryAt` says when the next attempt starts (none with
* `reconnect: false`).
* - `closed`: not connected because the app has not connected yet, or closed it.
*/
export type RosConnectionState = "connecting" | "open" | "closed" | "error"
export type RosStatus = {
state: RosConnectionState
/** The last thing that went wrong: the socket's error, a failed attempt, or a `status` message rosbridge sent. */
error?: Error
/** Attempts since the connection was last open. 0 while open. */
attempt: number
/** When the next attempt starts, in ms since the epoch, while `state` is `error` and a retry is scheduled. */
retryAt?: number
/** Round trip of the last heartbeat, in ms. Only with `heartbeat`: rosbridge has no ping of its own. */
latencyMs?: number
}
export type RosReconnect = {
/** The first wait, in ms. Default 500. */
minDelayMs?: number
/** The longest wait, in ms. Default 10 000. */
maxDelayMs?: number
/** Each failed attempt multiplies the wait by this. Default 2. */
factor?: number
}
export type RosHeartbeat = {
/** A service that answers quickly. Default `/rosapi/get_time`, which rosbridge_websocket_launch.xml starts. */
service?: string
/** Its type, for rosbridge versions that want it. Default `rosapi/GetTime`. */
type?: string
/** Default 5000. */
intervalMs?: number
/** No answer within this is a dead link: the socket is closed and the connection reconnects. Default 4000. */
timeoutMs?: number
}
export type RosConnectionOptions = {
/** The rosbridge server: `ws://robot.local:9090`. Use `wss://` from a page served over https. */
url: string
/** `true` (the default) reconnects with the default backoff; `false` stays in `error` after a drop. */
reconnect?: boolean | RosReconnect
/**
* Calls a service on an interval to measure latency and to notice a link that died without closing (a half-open TCP
* connection can look open for minutes). Off by default, since the service may not exist.
*/
heartbeat?: boolean | RosHeartbeat
/** A socket still opening after this is given up on and retried. Default 10 000. */
connectTimeoutMs?: number
/** Publishes and calls held while not open, at most. The oldest goes first. Default 100. */
maxQueue?: number
/** A held publish older than this is dropped instead of sent late. Default 5000. */
queueTtlMs?: number
/** The WebSocket constructor. Default: the global one. */
WebSocket?: RosSocketConstructor
/** 0…1, for the backoff's jitter. Default Math.random; a test passes a fixed one. */
random?: () => number
}
export type RosSubscribeOptions = {
/** Ask rosbridge to send at most one message per this many ms (`throttle_rate`). */
throttleMs?: number
/** Messages rosbridge may buffer while throttling (`queue_length`). */
queueLength?: number
}
export type RosCallOptions = {
/** The service type, sent for rosbridge versions that need it to find a service not yet seen. */
type?: string
/** Reject after this many ms. Default 10 000. The clock runs while the call waits for the connection too. */
timeoutMs?: number
}
export type RosPublisherOptions<T> = {
/**
* What to send to stop: on `release()`, on `stop()` and when the link drops, if the last message sent was not a stop.
* Default: a zero Twist for `geometry_msgs/Twist` and `TwistStamped`, nothing for other types. `null` turns it off.
*/
stopMessage?: T | null
/** Whether a message is a stop. Default: deep equality with `stopMessage`, numbers compared as numbers. */
isStop?: (message: T) => boolean
}
export type RosStopReason = "release" | "connection-lost" | "hidden" | "app"
/**
* A publisher on one topic. Nothing is advertised until the first publish; `release()` takes it back, and the next
* publish advertises again, so one object can live through React's StrictMode remount.
*/
export type RosPublisher<T> = {
readonly topic: string
readonly type: string
/**
* Sends the message, or holds it until the connection is open. Returns false when it was dropped: a velocity command
* while not open (never held, so it cannot arrive late), or any non-stop message after a stop until a stop is published
* again (see `stop`).
*/
publish: (message: T) => boolean
/**
* If the last message sent was not a stop, sends the stop message and refuses further non-stop messages until the app
* publishes a stop itself: after the page hid or the link dropped, a drive resumes only from a fresh press, never
* from a stick that was still held.
*/
stop: (reason?: RosStopReason) => void
/** Stops (as `stop`), then unadvertises once no other publisher holds the topic. */
release: () => void
}
export class RosTimeoutError extends Error {
constructor(what: string, ms: number) {
super(`${what}: no answer within ${ms} ms`)
this.name = "RosTimeoutError"
}
}
export class RosServiceError extends Error {
/** What rosbridge sent back as `values`: usually a string saying why. */
readonly values: unknown
constructor(service: string, values: unknown) {
super(`${service} failed${typeof values === "string" && values ? `: ${values}` : ""}`)
this.name = "RosServiceError"
this.values = values
}
}
export class RosConnectionError extends Error {
constructor(message: string) {
super(message)
this.name = "RosConnectionError"
}
}
/** The connection the hooks share. Create it once per rosbridge server. */
export type RosConnection = {
readonly url: string
/** Opens the socket (and keeps reopening it, with `reconnect`). Safe to call again; a no-op while connecting or open. */
connect: () => void
/** Closes the socket and stops reconnecting. Subscriptions and publishers stay registered for the next `connect()`. */
close: () => void
/** Skips the backoff wait and tries now (a Reconnect button). */
reconnectNow: () => void
getStatus: () => RosStatus
subscribeStatus: (listener: () => void) => () => void
/** Listens to a topic; returns the function that stops listening. One wire subscription per topic, however many listeners. */
subscribe: <T = unknown>(topic: string, type: string, listener: (message: T) => void, options?: RosSubscribeOptions) => () => void
/** The last message on a topic someone is subscribed to, or undefined. */
latest: <T = unknown>(topic: string) => T | undefined
/** A ref-counted publisher on a topic. Creating it sends nothing. */
publisher: <T = unknown>(topic: string, type: string, options?: RosPublisherOptions<T>) => RosPublisher<T>
/** Calls a service and resolves with its response `values`. */
call: <Req = unknown, Res = unknown>(service: string, request: Req, options?: RosCallOptions) => Promise<Res>
}
// WebSocket.OPEN, written out so a fake socket and a server-side render need no global.
const OPEN = 1
type Listener = (message: unknown) => void
type Subscription = {
topic: string
type: string
id: string
listeners: Map<Listener, RosSubscribeOptions>
latest?: unknown
/** The options last sent, so a change in what the listeners ask for is sent again under the same id (rosbridge updates it). */
sent?: string
}
type Advertisement = { topic: string; type: string; id: string; holders: number; linger?: ReturnType<typeof setTimeout> }
/** A message waiting for the socket. `stop` never expires: a stop sent late is still safe, and it may be the robot's only one. */
type Held = { at: number; message: Record<string, unknown>; topic?: string; callId?: string; stop?: boolean }
type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout>; sent: boolean; service: string }
const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now())
const TWIST = /^geometry_msgs\/(msg\/)?Twist$/
const TWIST_STAMPED = /^geometry_msgs\/(msg\/)?TwistStamped$/
// A topic's advertisement outlives its last publisher by this long, so a stop published just before is delivered before
// rosbridge tears the publisher down, and a StrictMode remount keeps the same advertisement.
const UNADVERTISE_AFTER_MS = 500
/** The stop message a type gets by default: a zero Twist for the velocity types, nothing for others. */
export function defaultStopMessage(type: string): unknown {
if (TWIST.test(type)) return zeroTwist()
if (TWIST_STAMPED.test(type)) return { header: { frame_id: "" }, twist: zeroTwist() }
return undefined
}
function sameValue(a: unknown, b: unknown): boolean {
if (typeof a === "number" && typeof b === "number") return a === b || (Number.isNaN(a) && Number.isNaN(b))
if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return a === b
const ka = Object.keys(a as object)
const kb = Object.keys(b as object)
if (ka.length !== kb.length) return false
return ka.every((k) => sameValue((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
}
/**
* rosbridge writes NaN and ±Infinity (a LaserScan with no return) as bare tokens on some versions, which is not JSON.
* Only when the plain parse fails, those tokens after a `:`, `,` or `[` become null, which the converters read as NaN.
*/
export function parseRosJson(text: string): unknown {
try {
return JSON.parse(text)
} catch (first) {
const fixed = text.replace(/([:,[]\s*)(-?Infinity|NaN)(?=\s*[,\]}])/g, "$1null")
if (fixed === text) throw first
return JSON.parse(fixed)
}
}
function report(error: unknown) {
// A listener that throws must not stop the others or the socket's handler; the error still reaches the console.
if (typeof reportError === "function") reportError(error)
else setTimeout(() => {
throw error
})
}
/** Creates the connection. Nothing happens on the network until `connect()`. */
export function createRosConnection(options: RosConnectionOptions): RosConnection {
const { url, connectTimeoutMs = 10_000, maxQueue = 100, queueTtlMs = 5_000, random = Math.random } = options
const backoff = options.reconnect === false ? null : { minDelayMs: 500, maxDelayMs: 10_000, factor: 2, ...(options.reconnect === true ? {} : options.reconnect) }
const heartbeat = !options.heartbeat
? null
: { service: "/rosapi/get_time", type: "rosapi/GetTime", intervalMs: 5_000, timeoutMs: 4_000, ...(options.heartbeat === true ? {} : options.heartbeat) }
let socket: RosSocket | null = null
let wanted = false
let status: RosStatus = { state: "closed", attempt: 0 }
let retryTimer: ReturnType<typeof setTimeout> | undefined
let openTimer: ReturnType<typeof setTimeout> | undefined
let beatTimer: ReturnType<typeof setTimeout> | undefined
let seq = 0
const statusListeners = new Set<() => void>()
const subs = new Map<string, Subscription>()
const ads = new Map<string, Advertisement>()
const held: Held[] = []
const pending = new Map<string, Pending>()
const fragments = new Map<string, { total: number; parts: string[]; count: number }>()
/** Publishers that stop on a dropped link: each one's stop() is called when the link is lost. */
const stoppers = new Set<(reason: RosStopReason) => void>()
const nextId = (what: string) => `${what}:${++seq}`
function setStatus(next: Partial<RosStatus>) {
status = { ...status, ...next }
for (const l of [...statusListeners]) {
try {
l()
} catch (e) {
report(e)
}
}
}
const isOpen = () => socket !== null && socket.readyState === OPEN && status.state === "open"
function sendNow(message: Record<string, unknown>) {
socket?.send(JSON.stringify(message))
}
function hold(entry: Held) {
// A topic is state, not a log: a newer message on the same topic replaces the one still waiting.
if (entry.topic !== undefined) {
const i = held.findIndex((h) => h.topic === entry.topic)
if (i >= 0) held.splice(i, 1)
}
held.push(entry)
while (held.length > maxQueue) {
const dropped = held.shift()
if (dropped?.callId) failCall(dropped.callId, new RosConnectionError("Dropped from the send queue: too many messages waiting"))
}
}
function subscribeMessage(sub: Subscription) {
// Several listeners on one topic share the wire subscription: the fastest rate any asks for, the longest queue.
let throttle = Infinity
let queue = 0
for (const o of sub.listeners.values()) {
throttle = Math.min(throttle, Math.max(0, o.throttleMs ?? 0))
queue = Math.max(queue, Math.max(0, o.queueLength ?? 0))
}
const message: Record<string, unknown> = { op: "subscribe", id: sub.id, topic: sub.topic, type: sub.type, compression: "none" }
if (Number.isFinite(throttle) && throttle > 0) message.throttle_rate = Math.round(throttle)
if (queue > 0) message.queue_length = Math.round(queue)
return message
}
function syncSubscription(sub: Subscription) {
const message = subscribeMessage(sub)
const key = JSON.stringify(message)
if (sub.sent === key || !isOpen()) return
sub.sent = key
sendNow(message)
}
function onOpen() {
clearTimeout(openTimer)
setStatus({ state: "open", attempt: 0, retryAt: undefined, error: undefined })
// Order matters: subscriptions and advertisements first, then what was held, so a held stop on a velocity topic goes out
// on its advertisement before anything else does.
for (const sub of subs.values()) {
sub.sent = undefined
syncSubscription(sub)
}
for (const ad of ads.values()) if (ad.holders > 0 || ad.linger) sendNow({ op: "advertise", id: ad.id, topic: ad.topic, type: ad.type })
const cutoff = now() - queueTtlMs
for (const h of held.splice(0)) {
if (h.callId) {
const p = pending.get(h.callId)
if (!p) continue
p.sent = true
} else if (h.at < cutoff && !h.stop) continue
sendNow(h.message)
}
scheduleBeat()
}
function failCall(id: string, error: Error) {
const p = pending.get(id)
if (!p) return
clearTimeout(p.timer)
pending.delete(id)
p.reject(error)
}
function detach(s: RosSocket) {
s.onopen = s.onclose = s.onerror = s.onmessage = null
}
function lost(error: Error) {
clearTimeout(openTimer)
clearTimeout(beatTimer)
if (socket) detach(socket)
socket = null
// Calls already sent will never be answered on this socket.
for (const [id, p] of pending) if (p.sent) failCall(id, new RosConnectionError("The connection closed before the service answered"))
for (const sub of subs.values()) sub.sent = undefined
fragments.clear()
for (const stop of [...stoppers]) stop("connection-lost")
if (!wanted) return setStatus({ state: "closed", error, retryAt: undefined, latencyMs: undefined })
if (!backoff) return setStatus({ state: "error", error, retryAt: undefined, latencyMs: undefined })
const attempt = status.attempt + 1
// Equal jitter: half the wait is fixed, half random, so many tabs that lost the same server do not return in step.
const base = Math.min(backoff.maxDelayMs, backoff.minDelayMs * backoff.factor ** (attempt - 1))
const delay = base / 2 + (random() * base) / 2
setStatus({ state: "error", error, attempt, retryAt: Date.now() + delay, latencyMs: undefined })
retryTimer = setTimeout(open, delay)
}
function open() {
clearTimeout(retryTimer)
retryTimer = undefined
if (!wanted || socket) return
const Ctor = options.WebSocket ?? (globalThis.WebSocket as unknown as RosSocketConstructor | undefined)
if (!Ctor) return setStatus({ state: "error", error: new RosConnectionError("No WebSocket in this environment") })
let s: RosSocket
try {
s = new Ctor(url)
} catch (e) {
// A malformed URL throws at once; it will not get better by retrying.
return setStatus({ state: "error", error: e instanceof Error ? e : new RosConnectionError(String(e)), retryAt: undefined })
}
socket = s
setStatus({ state: "connecting", retryAt: undefined })
openTimer = setTimeout(() => {
if (socket !== s) return
detach(s)
s.close()
lost(new RosConnectionError(`Could not connect to ${url} within ${connectTimeoutMs} ms`))
}, connectTimeoutMs)
s.onopen = () => {
if (socket === s) onOpen()
}
s.onerror = () => {
// The browser says nothing about why; the close that follows carries the code.
if (socket === s && status.state === "open") setStatus({ error: new RosConnectionError(`The connection to ${url} failed`) })
}
s.onclose = (event) => {
if (socket !== s) return
const was = status.state
const code = event?.code
lost(new RosConnectionError(was === "open" ? `Connection to ${url} lost${code ? ` (code ${code})` : ""}` : `Could not connect to ${url}${code ? ` (code ${code})` : ""}`))
}
s.onmessage = (event) => {
if (socket === s) receive(event.data)
}
}
function receive(data: unknown) {
if (typeof data !== "string") {
setStatus({ error: new RosConnectionError("Received a binary message: only JSON (compression \"none\") is supported") })
return
}
let message: unknown
try {
message = parseRosJson(data)
} catch {
setStatus({ error: new RosConnectionError("Received a message that is not JSON") })
return
}
handle(message)
}
function handle(message: unknown) {
if (!message || typeof message !== "object") return
const m = message as Record<string, unknown>
switch (m.op) {
case "publish": {
const sub = typeof m.topic === "string" ? subs.get(m.topic) : undefined
if (!sub) return
sub.latest = m.msg
for (const listener of [...sub.listeners.keys()]) {
try {
listener(m.msg)
} catch (e) {
report(e)
}
}
return
}
case "service_response": {
const id = typeof m.id === "string" ? m.id : undefined
const p = id ? pending.get(id) : undefined
if (!id || !p) return
clearTimeout(p.timer)
pending.delete(id)
// rosbridge for ROS 1 before 0.11 sent no `result`; a response without one is a success.
if (m.result === false) p.reject(new RosServiceError(p.service, m.values))
else p.resolve(m.values)
return
}
case "fragment": {
const id = String(m.id)
const total = Number(m.total)
const num = Number(m.num)
if (!(total > 0 && num >= 0 && num < total) || typeof m.data !== "string") return
const f = fragments.get(id) ?? { total, parts: new Array<string>(total).fill(""), count: 0 }
fragments.set(id, f)
if (!f.parts[num]) f.count++
f.parts[num] = m.data
if (f.count < f.total) return
fragments.delete(id)
try {
handle(parseRosJson(f.parts.join("")))
} catch {
setStatus({ error: new RosConnectionError("A fragmented message did not reassemble") })
}
return
}
case "status": {
// rosbridge's own reports: an unknown type, a failed advertise. They do not change the connection's state.
if (m.level === "error" || m.level === "warning") setStatus({ error: new RosConnectionError(String(m.msg ?? "rosbridge reported an error")) })
return
}
}
}
function scheduleBeat() {
clearTimeout(beatTimer)
if (!heartbeat) return
beatTimer = setTimeout(beat, heartbeat.intervalMs)
}
function beat() {
if (!heartbeat || !isOpen()) return
const s = socket
const start = now()
call(heartbeat.service, {}, { type: heartbeat.type, timeoutMs: heartbeat.timeoutMs }).then(
() => {
if (socket !== s) return
setStatus({ latencyMs: Math.round(now() - start) })
scheduleBeat()
},
(e: unknown) => {
if (socket !== s || !s) return
if (e instanceof RosTimeoutError) {
// No answer from a socket that still says it is open: the link is dead without having closed. Close it so the
// app hears of it and the connection starts over.
detach(s)
s.close()
lost(new RosConnectionError(`No heartbeat from ${url} within ${heartbeat.timeoutMs} ms`))
}
// Any other failure (no rosapi on this robot) ends the heartbeat; the link itself is fine.
},
)
}
function connect() {
wanted = true
if (socket || retryTimer) return
open()
}
function close() {
wanted = false
clearTimeout(retryTimer)
retryTimer = undefined
// Stop what is moving while the socket can still carry it.
if (isOpen()) for (const stop of [...stoppers]) stop("release")
const s = socket
if (s) {
detach(s)
s.close(1000)
}
socket = null
clearTimeout(openTimer)
clearTimeout(beatTimer)
for (const id of [...pending.keys()]) failCall(id, new RosConnectionError("The connection was closed"))
for (const sub of subs.values()) sub.sent = undefined
setStatus({ state: "closed", attempt: 0, retryAt: undefined, latencyMs: undefined })
}
function reconnectNow() {
if (!wanted || socket) return
open()
}
function subscribe<T>(topic: string, type: string, listener: (message: T) => void, opts: RosSubscribeOptions = {}) {
let sub = subs.get(topic)
if (!sub) {
sub = { topic, type, id: nextId(`subscribe:${topic}`), listeners: new Map() }
subs.set(topic, sub)
}
const l = listener as Listener
sub.listeners.set(l, opts)
syncSubscription(sub)
const mine = sub
let done = false
return () => {
if (done) return
done = true
mine.listeners.delete(l)
// Wait a microtask before unsubscribing on the wire: React's StrictMode, or a hook whose options changed, takes a
// listener away and puts one back in the same commit, and that should not cost the server a resubscribe.
queueMicrotask(() => {
if (subs.get(topic) !== mine) return
if (mine.listeners.size > 0) return syncSubscription(mine)
subs.delete(topic)
if (isOpen() && mine.sent) sendNow({ op: "unsubscribe", id: mine.id, topic })
})
}
}
function latest<T>(topic: string) {
return subs.get(topic)?.latest as T | undefined
}
function advertise(topic: string, type: string) {
let ad = ads.get(topic)
if (!ad) {
ad = { topic, type, id: nextId(`advertise:${topic}`), holders: 0 }
ads.set(topic, ad)
if (isOpen()) sendNow({ op: "advertise", id: ad.id, topic, type })
}
if (ad.linger) {
clearTimeout(ad.linger)
ad.linger = undefined
}
ad.holders++
return ad
}
function unadvertise(ad: Advertisement) {
ad.holders = Math.max(0, ad.holders - 1)
if (ad.holders > 0 || ad.linger) return
ad.linger = setTimeout(() => {
ad.linger = undefined
if (ad.holders > 0 || ads.get(ad.topic) !== ad) return
ads.delete(ad.topic)
if (isOpen()) sendNow({ op: "unadvertise", id: ad.id, topic: ad.topic })
}, UNADVERTISE_AFTER_MS)
}
function publisher<T>(topic: string, type: string, opts: RosPublisherOptions<T> = {}): RosPublisher<T> {
const stopMessage = (opts.stopMessage === undefined ? defaultStopMessage(type) : opts.stopMessage) as T | null | undefined
const hasStop = stopMessage !== null && stopMessage !== undefined
const velocity = opts.stopMessage === undefined && (TWIST.test(type) || TWIST_STAMPED.test(type))
const isStop = opts.isStop ?? ((m: T) => hasStop && (velocity ? isZeroTwist(m as RosTwist | { twist: RosTwist }) : sameValue(m, stopMessage)))
let ad: Advertisement | null = null
// Whether the last message sent was not a stop, and whether non-stop messages are refused until a stop comes.
let moving = false
let armed = true
const send = (message: T, stopping: boolean) => {
if (!ad) ad = advertise(topic, type)
// Known to the connection while it has advertised, so a dropped link stops it; release() takes it out.
if (hasStop) stoppers.add(stop)
const wire = { op: "publish", id: ad.id, topic, type, msg: message as unknown }
if (isOpen()) sendNow(wire)
else if (stopping || !hasStop) hold({ at: now(), message: wire, topic, stop: stopping && hasStop })
// A velocity command is never held: sent late, it would drive a robot nobody is steering any more.
else return false
moving = hasStop && !stopping
return true
}
const stop = (reason: RosStopReason = "app") => {
if (!hasStop || !moving) return
if (reason !== "release") armed = false
send(stopMessage as T, true)
}
const self: RosPublisher<T> = {
topic,
type,
publish: (message) => {
if (!hasStop) return send(message, false)
const isAStop = isStop(message)
if (!armed && !isAStop) return false
armed = true
if (isAStop) return send(message, true)
if (!isOpen()) {
// The link is not there to carry it; whatever the robot last heard is out of our hands, so make sure the first
// thing it hears when the link returns is a stop, and wait for the app's own stop before driving again.
if (moving) stop("connection-lost")
else armed = false
return false
}
return send(message, false)
},
stop,
release: () => {
stop("release")
stoppers.delete(stop)
if (ad) unadvertise(ad)
ad = null
moving = false
armed = true
},
}
return self
}
function call<Req, Res>(service: string, request: Req, opts: RosCallOptions = {}): Promise<Res> {
const { timeoutMs = 10_000, type } = opts
return new Promise<Res>((resolve, reject) => {
const id = nextId(`call_service:${service}`)
const message: Record<string, unknown> = { op: "call_service", id, service, args: request ?? {} }
if (type) message.type = type
const timer = setTimeout(() => {
const i = held.findIndex((h) => h.callId === id)
if (i >= 0) held.splice(i, 1)
failCall(id, new RosTimeoutError(service, timeoutMs))
}, timeoutMs)
pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer, sent: false, service })
if (isOpen()) {
pending.get(id)!.sent = true
sendNow(message)
} else hold({ at: now(), message, callId: id })
})
}
return {
url,
connect,
close,
reconnectNow,
getStatus: () => status,
subscribeStatus: (listener) => {
statusListeners.add(listener)
return () => {
statusListeners.delete(listener)
}
},
subscribe,
latest,
publisher,
call,
}
}
// --- Messages ------------------------------------------------------------------------------------------------------
// The ROS message shapes the converters read, as rosbridge sends them in JSON (snake_case, as in the .msg files). Only the
// fields used are typed; a message with more passes.
/** ROS 2 writes `sec`/`nanosec`, ROS 1 `secs`/`nsecs`. */
export type RosTime = { sec: number; nanosec: number } | { secs: number; nsecs: number }
export type RosHeader = { stamp?: RosTime; frame_id?: string }
export type RosVector3 = { x: number; y: number; z: number }
export type RosQuaternion = { x: number; y: number; z: number; w: number }
export type RosPose = { position: { x: number; y: number; z?: number }; orientation: RosQuaternion }
export type RosPoseStamped = { header: RosHeader; pose: RosPose }
/** A pose as any of the messages that carry one: Pose, PoseStamped, PoseWithCovariance, PoseWithCovarianceStamped (/amcl_pose) or Odometry. */
export type RosPoseLike = RosPose | { pose: RosPose } | { pose: { pose: RosPose } }
export type RosTwist = { linear: RosVector3; angular: RosVector3 }
/** `uint8[]` arrives as a base64 string; a client or an older bridge may send a list of numbers. */
export type RosBytes = string | ArrayLike<number>
export type RosOccupancyGrid = {
header?: RosHeader
info: { resolution: number; width: number; height: number; origin: RosPose }
/** `int8[]`: a list of numbers from rosbridge, or base64 from a bridge that encodes it as bytes. */
data: RosBytes
}
export type RosLaserScan = {
header?: RosHeader
angle_min: number
angle_max?: number
angle_increment: number
range_min: number
range_max: number
/** NaN and ±Infinity arrive as null, or as bare tokens that `parseRosJson` turns into null. */
ranges: ArrayLike<number | null>
}
export type RosPointField = { name: string; offset: number; datatype: number; count?: number }
export type RosPointCloud2 = {
header?: RosHeader
height: number
width: number
fields: RosPointField[]
is_bigendian: boolean
point_step: number
row_step: number
data: RosBytes
is_dense?: boolean
}
export type RosJointState = {
header?: RosHeader
name: readonly string[]
position: readonly (number | null)[]
velocity?: readonly (number | null)[]
effort?: readonly (number | null)[]
}
// --- Converters ----------------------------------------------------------------------------------------------------
// Pure functions from ROS messages to the props the components take, by the conventions their docs state (robot-map's
// plan coordinates, point-cloud's REP 103 frame, joint-state's SI units). The output types are written out here rather
// than imported, so this file installs without the components; tests check they stay assignable to the components' types.
/** Bytes from a base64 string or a list of numbers. */
export function rosBytes(data: RosBytes): Uint8Array {
if (typeof data !== "string") return data instanceof Uint8Array ? data : Uint8Array.from(data as ArrayLike<number>)
const text = atob(data)
const out = new Uint8Array(text.length)
for (let i = 0; i < text.length; i++) out[i] = text.charCodeAt(i)
return out
}
/** A header stamp in ms since the epoch (for `updatedAt`), from ROS 1 or ROS 2 time. */
export function stampToMs(stamp: RosTime | undefined): number | undefined {
if (!stamp) return undefined
const s = "sec" in stamp ? stamp.sec : stamp.secs
const ns = "nanosec" in stamp ? stamp.nanosec : stamp.nsecs
return Number.isFinite(s) && Number.isFinite(ns) ? s * 1000 + ns / 1e6 : undefined
}
/** Yaw (rotation about z, counter-clockwise from +x) of a quaternion, in radians. */
export function quaternionToYaw(q: RosQuaternion): number {
return Math.atan2(2 * (q.w * q.z + q.x * q.y), 1 - 2 * (q.y * q.y + q.z * q.z))
}
/** A quaternion turning `yaw` radians about z. */
export function yawToQuaternion(yaw: number): RosQuaternion {
return { x: 0, y: 0, z: Math.sin(yaw / 2), w: Math.cos(yaw / 2) }
}
/** The pose inside a Pose, PoseStamped, PoseWithCovariance(Stamped) or Odometry message. */
export function poseOf(message: RosPoseLike): RosPose {
let m: unknown = message
// Unwrap `pose` until the object has a position: PoseWithCovarianceStamped nests it twice.
for (let i = 0; i < 3 && m && typeof m === "object" && !("position" in m) && "pose" in m; i++) m = (m as { pose: unknown }).pose
return m as RosPose
}
/** The plan in the map frame, as robot-map's `RobotMapFrame` (its `gridToPlan(grid)` gives one for a grid). */
export type RosPlanFrame = { width: number; height: number; origin: { x: number; y: number } }
/** robot-map's `RobotMapPose`: metres from the plan's top-left, y down, heading in degrees clockwise from the top. */
export type RosPlanPose = { x: number; y: number; heading?: number }
/**
* A pose in the ROS map frame on robot-map's plan, by its documented conversion (the same as its `rosToPlan`):
* `x = xRos − originX`, `y = height − (yRos − originY)`, `heading = 90 − yaw × 180 / π`, kept in 0–360.
* The pose must be in the map frame (/amcl_pose is); a pose in `odom` drifts from the map.
*/
export function poseToRobotMapPose(message: RosPoseLike, frame: RosPlanFrame): RosPlanPose {
const pose = poseOf(message)
const yaw = quaternionToYaw(pose.orientation)
return {
x: pose.position.x - frame.origin.x,
y: frame.height - (pose.position.y - frame.origin.y),
heading: (((90 - (yaw * 180) / Math.PI) % 360) + 360) % 360,
}
}
/**
* A goal placed on robot-map (`onGoal`) as a `geometry_msgs/PoseStamped` in the map frame: the inverse of
* `poseToRobotMapPose`. Without a heading the goal faces +x. The stamp is left out unless given, and rosbridge for ROS 2
* fills in the current time; ROS 1 leaves it at zero, which Nav2 and move_base read as "latest".
*/
export function goalToPoseStamped(goal: RosPlanPose, frame: RosPlanFrame, options: { frameId?: string; stamp?: RosTime } = {}): RosPoseStamped {
const yaw = goal.heading === undefined ? 0 : ((90 - goal.heading) * Math.PI) / 180
const header: RosHeader = { frame_id: options.frameId ?? "map" }
if (options.stamp) header.stamp = options.stamp
return {
header,
pose: {
position: { x: goal.x + frame.origin.x, y: frame.origin.y + frame.height - goal.y, z: 0 },
orientation: yawToQuaternion(yaw),
},
}
}
/** robot-map's `RobotMapGrid`. */
export type RosMapGrid = { width: number; height: number; resolution: number; origin: { x: number; y: number }; data: Int8Array }
/**
* A `nav_msgs/OccupancyGrid` as robot-map's `grid` (or `costmap`): row 0 at the bottom, as the message has it; robot-map
* flips it when it draws. `data` becomes an Int8Array whether it came as numbers or base64. The origin's yaw is dropped:
* robot-map takes grids with yaw 0, as map_server and the SLAM packages write them.
* A new array per message: robot-map redraws on a new array, so convert only when a new message arrives.
*/
export function occupancyGridToGrid(message: RosOccupancyGrid): RosMapGrid {
const { width, height, resolution, origin } = message.info
const raw = message.data
let data: Int8Array
if (typeof raw === "string") {
const bytes = rosBytes(raw)
data = new Int8Array(bytes.buffer, bytes.byteOffset, bytes.length)
} else data = Int8Array.from(raw as ArrayLike<number>)
return { width, height, resolution, origin: { x: origin.position.x, y: origin.position.y }, data }
}
/** robot-map's `RobotMapScan`. */
export type RosMapScan = { robotId: string; angleMin: number; angleIncrement: number; ranges: Float32Array; rangeMin: number; rangeMax: number }
/**
* A `sensor_msgs/LaserScan` as one of robot-map's `scans`, drawn from the robot `robotId`. A null range (how JSON carries
* NaN and ±Infinity) becomes NaN, which robot-map skips with the out-of-range readings. The scan must be in the robot's
* base frame (the laser at its centre), as robot-map assumes.
*/
export function laserScanToScan(message: RosLaserScan, robotId: string): RosMapScan {
const { ranges } = message
const out = new Float32Array(ranges.length)
for (let i = 0; i < ranges.length; i++) {
const r = ranges[i]
out[i] = typeof r === "number" ? r : NaN
}
return { robotId, angleMin: message.angle_min, angleIncrement: message.angle_increment, ranges: out, rangeMin: message.range_min, rangeMax: message.range_max }
}
// sensor_msgs/PointField datatypes.
const POINT_FIELD_SIZE: Record<number, number> = { 1: 1, 2: 1, 3: 2, 4: 2, 5: 4, 6: 4, 7: 4, 8: 8 }
function fieldReader(view: DataView, field: RosPointField, little: boolean): (at: number) => number {
const o = field.offset
switch (field.datatype) {
case 1:
return (at) => view.getInt8(at + o)
case 2:
return (at) => view.getUint8(at + o)
case 3:
return (at) => view.getInt16(at + o, little)
case 4:
return (at) => view.getUint16(at + o, little)
case 5:
return (at) => view.getInt32(at + o, little)
case 6:
return (at) => view.getUint32(at + o, little)
case 7:
return (at) => view.getFloat32(at + o, little)
case 8:
return (at) => view.getFloat64(at + o, little)
default:
throw new Error(`PointCloud2 field ${field.name} has unknown datatype ${field.datatype}`)
}
}
/** point-cloud's `points` (x, y, z, metres, REP 103) and, when the cloud has the field, `intensity`, one per point. */
export type RosCloudPoints = { points: Float32Array; intensity?: Float32Array }
/**
* A `sensor_msgs/PointCloud2` as point-cloud's props. Reads x, y, z and the intensity field (by name, `intensity` unless
* given) at their offsets, in any of the PointField datatypes, in the message's byte order, row by row (`row_step`) and
* point by point (`point_step`). Points with a NaN or infinite coordinate are left out whatever `is_dense` says, since
* drivers do not always set it truly. The points stay in the cloud's own frame (`header.frame_id`).
*/
export function pointCloud2ToPoints(message: RosPointCloud2, options: { intensityField?: string | null } = {}): RosCloudPoints {
const field = (name: string) => message.fields.find((f) => f.name === name)
const fx = field("x")
const fy = field("y")
const fz = field("z")
if (!fx || !fy || !fz) throw new Error("PointCloud2 has no x, y and z fields")
const intensityName = options.intensityField === undefined ? "intensity" : options.intensityField
const fi = intensityName ? field(intensityName) : undefined
const bytes = rosBytes(message.data)
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
const little = !message.is_bigendian
const rx = fieldReader(view, fx, little)
const ry = fieldReader(view, fy, little)
const rz = fieldReader(view, fz, little)
const ri = fi ? fieldReader(view, fi, little) : null
// The furthest byte any field reads, so a point cut short at the end of `data` is skipped instead of throwing.
const span = Math.max(...[fx, fy, fz, fi].map((f) => (f ? f.offset + (POINT_FIELD_SIZE[f.datatype] ?? 8) : 0)))
const { width, height, point_step: step } = message
const rowStep = message.row_step || width * step
const total = width * height
const points = new Float32Array(total * 3)
const intensity = ri ? new Float32Array(total) : undefined
let n = 0
for (let row = 0; row < height; row++) {
for (let col = 0; col < width; col++) {
const at = row * rowStep + col * step
if (at + span > bytes.byteLength) break
const x = rx(at)
const y = ry(at)
const z = rz(at)
if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) continue
points[n * 3] = x
points[n * 3 + 1] = y
points[n * 3 + 2] = z
if (intensity && ri) intensity[n] = ri(at)
n++
}
}
return { points: points.slice(0, n * 3), ...(intensity ? { intensity: intensity.slice(0, n) } : {}) }
}
/** joint-state's `JointStateJoint`. */
export type RosJoint = {
name: string
position: number
unit?: "rad" | "m"
lower?: number
upper?: number
velocity?: number
effort?: number
effortLimit?: number
}
/** What the URDF says about a joint, which the message does not carry. */
export type RosJointLimits = Record<string, { unit?: "rad" | "m"; lower?: number; upper?: number; effortLimit?: number }>
/**
* A `sensor_msgs/JointState` as joint-state's `joints`, with the URDF's limits added by name. `order` lists and orders the
* joints to show (the URDF's chain order); without it they come in the message's order. A joint with no finite position is
* left out. Values stay in SI units, as the panel wants them. For robot-model, use its own `jointStateToRecord`.
*/
export function jointStateToJoints(message: RosJointState, options: { limits?: RosJointLimits; order?: readonly string[] } = {}): RosJoint[] {
const { limits = {}, order } = options
const index = new Map(message.name.map((name, i) => [name, i]))
const finite = (v: number | null | undefined) => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
const out: RosJoint[] = []
for (const name of order ?? message.name) {
const i = index.get(name)
if (i === undefined) continue
const position = finite(message.position[i])
if (position === undefined) continue
const joint: RosJoint = { name, position, ...limits[name] }
const velocity = finite(message.velocity?.[i])
const effort = finite(message.effort?.[i])
if (velocity !== undefined) joint.velocity = velocity
if (effort !== undefined) joint.effort = effort
out.push(joint)
}
return out
}
/** A `geometry_msgs/Twist` with every component 0: stop. */
export const zeroTwist = (): RosTwist => ({ linear: { x: 0, y: 0, z: 0 }, angular: { x: 0, y: 0, z: 0 } })
/** Whether a Twist (or a TwistStamped's `twist`) stops: every component 0 or left out, as rosbridge fills missing fields with 0. */
export function isZeroTwist(message: Partial<RosTwist> | { twist: Partial<RosTwist> }): boolean {
if (!message || typeof message !== "object") return false
const t: Partial<RosTwist> = "twist" in message ? message.twist : message
const zero = (v: Partial<RosVector3> | undefined) => !v || ((v.x ?? 0) === 0 && (v.y ?? 0) === 0 && (v.z ?? 0) === 0)
return zero(t.linear) && zero(t.angular)
}
const clamp1 = (v: number) => (Number.isFinite(v) ? Math.min(1, Math.max(-1, v)) : 0)
/**
* teleop-pad's command (`{ linear, angular }`, each −1…1 of top speed, REP 103: forward and left are +) as a
* `geometry_msgs/Twist` for a differential or skid-steer base: `linear.x = linear × maxLinear` (m/s),
* `angular.z = angular × maxAngular` (rad/s). Out-of-range or non-finite values are clamped first. Clamp again on the robot.
*/
export function teleopToTwist(command: { linear: number; angular: number }, limits: { maxLinear: number; maxAngular: number }): RosTwist {
// `|| 0` turns −0 into 0, so a stop is exactly the zero Twist.
return {
linear: { x: clamp1(command.linear) * limits.maxLinear || 0, y: 0, z: 0 },
angular: { x: 0, y: 0, z: clamp1(command.angular) * limits.maxAngular || 0 },
}
}Changelog
- 0.27.02026-11-21First release.