# WebSocket Data Format

TimePlot's WebSocket source accepts UTF-8 text frames whose contents can be parsed into one of the supported payload shapes below.

## Recommended payload

Send one JSON object per message:

```json
{
  "timestampMs": 1250,
  "value": 0.482
}
```

Fields:

- `value` — required numeric sample value
- `timestampMs` — optional numeric source timestamp in milliseconds

If `timestampMs` is present, TimePlot uses it to preserve the source timing relationship and aligns it onto the app's plot timebase.
If `timestampMs` is omitted, TimePlot stamps the sample at the current plot time when the message arrives.

## Other accepted object keys

TimePlot also accepts these alternate numeric field names:

- value fields: `value`, `y`, `signal`, `data`
- time fields: `timeMs`, `timestampMs`, `timestamp`, `t`

Examples:

```json
{"y": 0.91, "t": 2040}
```

```json
{"signal": -0.13, "timestamp": 9810}
```

## Arrays

A single message may contain an array of supported payloads:

```json
[
  {"timestampMs": 1000, "value": 0.2},
  {"timestampMs": 1100, "value": 0.3},
  {"timestampMs": 1200, "value": 0.5}
]
```

This is useful for batching.

## Bare numeric messages

These also work, though JSON objects are preferred:

```text
0.418
```

or:

```json
42.5
```

These are treated as samples without an explicit timestamp.

## Unsupported / ignored messages

Messages are ignored if TimePlot cannot find a numeric sample value.
Examples of ignored payloads:

- empty strings
- non-numeric strings
- JSON objects without a numeric `value`-like field

## Demo server compatibility

The included demo server sends messages like:

```json
{
  "timestampMs": 1870,
  "value": 0.735812,
  "sequence": 19,
  "profile": "telemetry"
}
```

Extra fields are safe. TimePlot ignores anything it does not need.

## Running the demo server

```bash
bun run ws:demo
```

Environment options:

- `PORT` — default `8080`
- `TIMEPLOT_PROFILE` — `telemetry`, `chirp`, `steps`, or `burst`
- `TIMEPLOT_INTERVAL_MS` — message interval in milliseconds

Example:

```bash
PORT=8090 TIMEPLOT_PROFILE=chirp TIMEPLOT_INTERVAL_MS=50 bun run ws:demo
```

Then set a signal source type to `WebSocket` and point it at:

```text
ws://localhost:8090
```