# @foxglove/ws-protocol-examples

> Foxglove WebSocket protocol examples

Latest version **0.10.0** (published 2025-03-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @foxglove/ws-protocol-examples
pnpm add @foxglove/ws-protocol-examples
yarn add @foxglove/ws-protocol-examples
bun add @foxglove/ws-protocol-examples
```

Provides the command `ws-protocol-examples`.

## Health

**Score 45/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.10.0 |
| Published | 2025-03-13 |
| First published | 2021-12-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 18 |
| Dependencies | 17 |
| Unpacked size | 465.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 150 |
| Author | Foxglove Technologies |
| Maintainers | foxglovebot, amacneil |
| Keywords | foxglove, websocket, robotics, ros, ros2 |

## Links

- npm: https://www.npmjs.com/package/@foxglove/ws-protocol-examples
- Repository: https://github.com/foxglove/ws-protocol
- Homepage: https://foxglove.dev/
- Issues: https://github.com/foxglove/ws-protocol/issues
- npm.io page: https://npm.io/package/@foxglove/ws-protocol-examples

## Dependencies (17)

- [ws](https://npm.io/package/ws.md) ^8.17.1
- [boxen](https://npm.io/package/boxen.md) ^7.1.1
- [debug](https://npm.io/package/debug.md) ^4
- [tslib](https://npm.io/package/tslib.md) ^2.8.1
- [commander](https://npm.io/package/commander.md) ^11.1.0
- [pureimage](https://npm.io/package/pureimage.md) ^0.4.13
- [@mcap/core](https://npm.io/package/@mcap/core.md) ^2.1.5
- [protobufjs](https://npm.io/package/protobufjs.md) ^7.2.6
- [eventemitter3](https://npm.io/package/eventemitter3.md) ^5.0.1
- [promise-queue](https://npm.io/package/promise-queue.md) ^2.2.5
- [@foxglove/rostime](https://npm.io/package/@foxglove/rostime.md) ^1.1.2
- [@foxglove/schemas](https://npm.io/package/@foxglove/schemas.md) ^1.6.4
- [@foxglove/wasm-lz4](https://npm.io/package/@foxglove/wasm-lz4.md) ^1.0.2
- [@foxglove/wasm-zstd](https://npm.io/package/@foxglove/wasm-zstd.md) ^1.0.1
- [@foxglove/ws-protocol](https://npm.io/package/@foxglove/ws-protocol.md) 0.8.0
- [@foxglove/rosmsg-serialization](https://npm.io/package/@foxglove/rosmsg-serialization.md) ^2.0.3
- [@foxglove/rosmsg2-serialization](https://npm.io/package/@foxglove/rosmsg2-serialization.md) ^2.0.4

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.10.0 (latest) — 2025-03-13
- 0.9.0 — 2025-01-27
- 0.8.2 — 2024-06-14
- 0.8.1 — 2024-05-14
- 0.8.0 — 2024-05-03
- 0.7.1 — 2024-03-08
- 0.7.0 — 2024-01-31
- 0.6.1 — 2023-11-28
- 0.6.0 — 2023-04-27
- 0.5.0 — 2023-02-16
- 0.4.0 — 2023-01-11
- 0.3.0 — 2023-01-11
- 0.2.0 — 2023-01-10
- 0.1.0 — 2022-12-05
- 0.0.10 — 2022-11-23
- … 9 more at https://npm.io/package/@foxglove/ws-protocol-examples/versions

## README

# Foxglove WebSocket examples

This package provides example server and client implementations of the [Foxglove WebSocket protocol](https://github.com/foxglove/ws-protocol). The protocol enables [Foxglove](https://foxglove.dev/) to ingest arbitrary “live” streamed data.

To list all possible actions, run the following command:

```
$ npx @foxglove/ws-protocol-examples@latest --help
```

## Example servers

Run the `sysmon` example server, which uses JSON-encoded data to transmit system monitoring information like memory and CPU usage:

```
$ npx @foxglove/ws-protocol-examples@latest sysmon
```

Run the `image-server` example server, which uses JSON-encoded data to transmit images:

```
$ npx @foxglove/ws-protocol-examples@latest image-server
```

Run the `mcap-play` example server, which plays back recorded data from a local [MCAP](https://mcap.dev) file:

```
$ npx @foxglove/ws-protocol-examples@latest mcap-play <file> [--rate 1.0] [--loop]
```

_Note:_ You must exit each server (<kbd>control</kbd> + <kbd>c</kbd>) before starting up another.

To see data from any server, open [Foxglove](https://app.foxglove.dev/~/view?ds=foxglove-websocket&ds.url=ws://localhost:8765/) with a Foxglove WebSocket connection to `ws://localhost:8765/`:

<img width="500" alt="Foxglove displaying memory and CPU usage from the system monitor example" src="https://user-images.githubusercontent.com/14237/145313065-85c05645-6b29-4eb2-a498-849c83f8792d.png">
<img width="500" alt="Foxglove displaying images from the image server example" src="https://user-images.githubusercontent.com/14237/146500927-4a1408c7-0725-49e7-8185-71b0280c0a8b.png">

## Example clients

Run a simple example client that subscribes to messages with the `protobuf` or `json` encoding:

```
$ npx @foxglove/ws-protocol-examples@latest simple-client ws://localhost:8765
```

Run a client that advertises the `/chatter` topic and publishes messages to it with `json` or `ros1` encoding:

```
$ npx @foxglove/ws-protocol-examples@latest publish-client -e json ws://localhost:8765
```

Connect to a server and record message data into an [MCAP](https://mcap.dev) file:

```
$ npx @foxglove/ws-protocol-examples@latest mcap-record ws://localhost:8765 -o <file.mcap>
```

## Development

This package lives inside a monorepo that uses [yarn workspaces](https://yarnpkg.com/features/workspaces), so most commands (other than `yarn install`) should be prefixed with `yarn workspace @foxglove/ws-protocol-examples ...`.

- `yarn install` – Install development dependencies
- `yarn workspace @foxglove/ws-protocol-examples version --patch` (or `--minor` or `--major`) – Increment the version number and create the appropriate git tag
- `yarn workspace @foxglove/ws-protocol-examples run-example --help` – Run the example scripts

---
_Source: https://npm.io/package/@foxglove/ws-protocol-examples · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
