Agent Skills › lichtblick-suite/lichtblick › websocket-connection

websocket-connection

GitHub

处理机器人或仿真器到可视化的实时数据流。涵盖Foxglove WebSocket协议握手、订阅管理、二进制消息传输及RAF帧同步，利用Worker线程优化性能并实现自动重连。

.github/skills/websocket-connection/SKILL.md lichtblick-suite/lichtblick

Trigger Scenarios

建立WebSocket实时连接解析Foxglove协议消息配置Worker通信与状态发射

Install

npx skills add lichtblick-suite/lichtblick --skill websocket-connection -g -y

More Options

Non-standard path

npx skills add https://github.com/lichtblick-suite/lichtblick/tree/develop/.github/skills/websocket-connection -g -y

Use without installing

npx skills use lichtblick-suite/lichtblick@websocket-connection

指定 Agent (Claude Code)

npx skills add lichtblick-suite/lichtblick --skill websocket-connection -a claude-code -g -y

安装 repo 全部 skill

npx skills add lichtblick-suite/lichtblick --all -g -y

预览 repo 内 skill

npx skills add lichtblick-suite/lichtblick --list

SKILL.md

Frontmatter

{
    "name": "websocket-connection",
    "description": "Deep WebSocket connection knowledge: FoxgloveWebSocketPlayer state machine, WorkerSocketAdapter postMessage protocol, the Foxglove WebSocket protocol handshake, RAF-based state emission, and reconnection."
}

WebSocket Connection Skill

The real-time data path from a robot/simulation/bridge to visualization.

Architecture

Foxglove WebSocket Server (robot/bridge)
    │  WebSocket protocol
    ▼
WorkerSocketAdapter (Worker thread)
    │  postMessage (raw, not Comlink)
    ▼
FoxgloveWebSocketPlayer (main thread)
    │
    ▼
MessagePipeline → Panels

Core Files

File	Role
`packages/suite-base/src/players/FoxgloveWebSocketPlayer/index.ts`	Player implementation for WebSocket connections
`packages/suite-base/src/players/FoxgloveWebSocketPlayer/WorkerSocketAdapter.ts`	Offloads WebSocket I/O to a Worker
`packages/suite-base/src/players/FoxgloveWebSocketPlayer/worker.ts`	Worker-side WebSocket handling

Foxglove WebSocket Protocol

Connection Lifecycle

Server sends serverInfo (capabilities, session ID)
Server sends advertise with available channels (topic + schema)
Client sends subscribe with channel IDs
Server streams messageData binary frames
Client can publish messages back to the server

Key Operations

serverInfo — server capabilities, session ID
advertise / unadvertise — channel availability (topics can appear/disappear)
subscribe / unsubscribe — client topic selection
messageData — binary message payload with channel ID + timestamp
time — server clock synchronization
parameterValues — server parameters

FoxgloveWebSocketPlayer

Message Processing

Messages arrive as binary frames via WebSocket
Deserialized on the main thread (unlike file-based players, which decode in a Worker)
Accumulated in a parsedMessages queue
Queue flushed on requestAnimationFrame → emits state to the pipeline

Connection Management

Auto-reconnect with exponential backoff
Handles advertise/unadvertise dynamically
Subscription changes are sent immediately to the server (no debounce)

State Emission

requestAnimationFrame-driven flush of the message queue
Coalesces all messages received between frames into one state update (max ~60 updates/sec)
Prevents UI thrashing during high-frequency bursts

WorkerSocketAdapter

The WebSocket connection lives in a dedicated Worker
Avoids main-thread blocking during TLS handshake / large frame parsing
Communicates with the main thread via raw postMessage (not Comlink)
Binary frames are transferred (zero-copy) using Transferable ArrayBuffers

Performance Notes

Main-thread deserialization — current limitation; high message rates can drop frames
RAF-based flush — batches messages per animation frame
Binary transfer — ArrayBuffer transferred from the Worker (zero-copy)
Subscription filtering — only subscribed topics are sent → reduces bandwidth
Backpressure — if the main thread can't keep up, messages queue in the Worker