simon
41a66d4417
Replace separate accel/tap commands and messages with set_input_stream and input pushes that combine accel and tap per client, including pre_fetch timing. Co-authored-by: Cursor <cursoragent@cursor.com>
274 lines
7.8 KiB
Markdown
274 lines
7.8 KiB
Markdown
# WebSocket API
|
||
|
||
`go run . -port /dev/ttyUSB0 serve` exposes the WebSocket enpoint
|
||
|
||
| URL | Port (default) | Role |
|
||
|-----|----------------|------|
|
||
| `ws://localhost:8081/ws` | External API (`-api-addr`) | Request/response commands + optional **input** push stream |
|
||
|
||
---
|
||
|
||
## External API (`:8081/ws`)
|
||
|
||
### Connection flow
|
||
|
||
1. Connect → server sends **`hello`** (receive off; lists available commands).
|
||
2. Send JSON commands → server replies with a matching `*_status` or `client_list` message (one reply per command).
|
||
3. After `set_stream` with `enable: true`, the server may send **`input`** messages **without** a prior command (push stream).
|
||
|
||
Commands and stream pushes are multiplexed on one socket. While streaming, always parse `type` and branch (status vs sample vs error).
|
||
|
||
### Two layers (firmware vs host)
|
||
|
||
| Layer | Commands | Effect |
|
||
|-------|----------|--------|
|
||
| **Firmware (ESP-NOW)** | `set_input_stream`, `set_tap_notify` | Per `client_id`: slave sends accel samples and/or tap events to the master |
|
||
| **This connection (host)** | `set_stream` | Whether **you** receive push JSON, at what rate (`interval_ms`, 1 ms … 10 s), and how early the UART read starts (`pre_fetch`) |
|
||
|
||
- **UART polling** runs only if at least one connection has `receive_input: true` (`set_stream`) **and** at least one slave streams input (`set_input_stream`) or has tap notify enabled (`set_tap_notify`).
|
||
- **`set_tap_notify` alone** configures which tap kinds the slave reports; it does **not** enable host push by itself — you still need `set_stream`.
|
||
|
||
Typical sequence:
|
||
|
||
1. `list_clients` → slave IDs
|
||
2. Per slave: `set_input_stream` and/or `set_tap_notify` as needed
|
||
3. `set_stream` with `"enable": true`
|
||
4. Read **`input`** messages in a loop
|
||
|
||
There is **no per-slave filter** on push messages: each `input` contains all cached slaves. Filter by `client_id` in your app.
|
||
|
||
---
|
||
|
||
## Push stream messages
|
||
|
||
These are the samples you get after enabling receive. Timing is per WebSocket connection:
|
||
|
||
- **`interval_ms`** — minimum time between consecutive `input` pushes on this socket.
|
||
- **`pre_fetch`** — milliseconds **before** each scheduled push when the host sends the UART cache read, so the master has time to collect data from all slaves before the JSON goes out.
|
||
|
||
The server UART poll uses the **minimum** `interval_ms` among all subscribers with `receive_input: true`.
|
||
|
||
### `input` (type `"input"`)
|
||
|
||
Sent when `set_stream` has `enable: true` and the poll tick fires for this connection (after the UART read started `pre_fetch` ms earlier). Each message combines the latest accel cache and visible tap state for every slave slot on the master.
|
||
|
||
**Success** — all slaves with a cache entry (not only those with `valid: true`):
|
||
|
||
```json
|
||
{
|
||
"type": "input",
|
||
"t": 1716900123456789012,
|
||
"success": true,
|
||
"clients": [
|
||
{
|
||
"client_id": 16,
|
||
"valid": true,
|
||
"x": 12,
|
||
"y": -34,
|
||
"z": 16384,
|
||
"accel_age_ms": 8,
|
||
"tap_kind": "single",
|
||
"tap_age_ms": 3
|
||
},
|
||
{
|
||
"client_id": 42,
|
||
"valid": false,
|
||
"tap_kind": "none"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| Field | Meaning |
|
||
|-------|---------|
|
||
| `t` | Unix timestamp in **nanoseconds** when the host read the cache |
|
||
| `success` | `true` if `CACHE_STATUS` succeeded |
|
||
| `clients[]` | One entry per slave slot in the master cache |
|
||
| `client_id` | ESP-NOW client id (same as `list_clients`) |
|
||
| `valid` | `false` if no accel sample yet or stale; omit `x`/`y`/`z` when false |
|
||
| `x`, `y`, `z` | Raw accelerometer LSB (BMA456, ±2 g scale on the pod) |
|
||
| `accel_age_ms` | Milliseconds since the master received this accel sample |
|
||
| `tap_kind` | `"none"`, `"single"`, `"double"`, or `"triple"` |
|
||
| `tap_age_ms` | Milliseconds since the tap was seen in the master cache; omit when `tap_kind` is `"none"` |
|
||
|
||
Tap events stay visible for **`tap_display_min_ms`** (2000 ms, also in `hello`) after the API first saw them, even if the hardware age grows.
|
||
|
||
**Failure** (e.g. UART busy):
|
||
|
||
```json
|
||
{
|
||
"type": "input",
|
||
"t": 1716900123456789012,
|
||
"success": false,
|
||
"error": "uart busy"
|
||
}
|
||
```
|
||
|
||
No `clients` array on failure.
|
||
|
||
---
|
||
|
||
## Commands (request → response)
|
||
|
||
Send one JSON object per message. Field `type` selects the command.
|
||
|
||
### `hello` (server → client, on connect)
|
||
|
||
```json
|
||
{
|
||
"type": "hello",
|
||
"serial_port": "/dev/ttyUSB0",
|
||
"interval_ms": 16,
|
||
"pre_fetch_ms": 2,
|
||
"tap_display_min_ms": 2000,
|
||
"note": "set_tap_notify configures slave S/D/T only; set_stream enables input polling/push on this connection",
|
||
"commands": [
|
||
"list_clients",
|
||
"set_stream", "get_stream",
|
||
"set_input_stream", "get_input_stream",
|
||
"set_tap_notify", "get_tap_notify",
|
||
"set_led_ring", "get_battery"
|
||
]
|
||
}
|
||
```
|
||
|
||
### `list_clients`
|
||
|
||
Request: `{"type":"list_clients"}`
|
||
|
||
Response `client_list`:
|
||
|
||
```json
|
||
{
|
||
"type": "client_list",
|
||
"success": true,
|
||
"clients": [
|
||
{
|
||
"id": 16,
|
||
"mac": "aa:bb:cc:dd:ee:10",
|
||
"version": 1,
|
||
"available": true,
|
||
"used": true,
|
||
"last_ping": 1234,
|
||
"last_success_ping": 1200,
|
||
"input_stream": false,
|
||
"tap_notify_single": false,
|
||
"tap_notify_double": false,
|
||
"tap_notify_triple": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### `set_stream` / `get_stream` (receive input on this connection)
|
||
|
||
```json
|
||
{"type":"set_stream","enable":true,"interval_ms":32,"pre_fetch":2}
|
||
{"type":"get_stream"}
|
||
```
|
||
|
||
| Field | Meaning |
|
||
|-------|---------|
|
||
| `enable` | Turn push stream on/off for this connection |
|
||
| `interval_ms` | Minimum time between `input` pushes (1 … 10000) |
|
||
| `pre_fetch` | Milliseconds before each push when the host starts the UART cache read; optional, default in `hello` (`pre_fetch_ms`) |
|
||
|
||
Response `stream_status`:
|
||
|
||
```json
|
||
{"type":"stream_status","receive_input":true,"interval_ms":32,"pre_fetch":2,"success":true}
|
||
```
|
||
|
||
### `set_input_stream` / `get_input_stream` (firmware, per slave)
|
||
|
||
`client_id` required (> 0). Enables accel streaming from the slave to the master.
|
||
|
||
```json
|
||
{"type":"set_input_stream","client_id":16,"enable":true}
|
||
{"type":"get_input_stream","client_id":16}
|
||
```
|
||
|
||
Response `input_stream_status`:
|
||
|
||
```json
|
||
{"type":"input_stream_status","client_id":16,"enabled":true,"success":true}
|
||
```
|
||
|
||
### `set_tap_notify` / `get_tap_notify` (firmware, per slave)
|
||
|
||
Per client: `single`, `double_tap`, `triple` required on set.
|
||
|
||
```json
|
||
{"type":"set_tap_notify","client_id":16,"single":true,"double_tap":false,"triple":false}
|
||
```
|
||
|
||
Broadcast: `"all_clients": true` with the three booleans.
|
||
|
||
Response `tap_notify_status`:
|
||
|
||
```json
|
||
{
|
||
"type": "tap_notify_status",
|
||
"client_id": 16,
|
||
"success": true,
|
||
"single": true,
|
||
"double_tap": false,
|
||
"triple": false
|
||
}
|
||
```
|
||
|
||
### `set_led_ring`
|
||
|
||
Control the LED ring on the master or a slave.
|
||
|
||
```json
|
||
{"type":"set_led_ring","mode":"color","client_id":16,"r":255,"g":0,"b":0,"intensity":128}
|
||
{"type":"set_led_ring","mode":"digit","client_id":0,"digit":3,"r":0,"g":255,"b":0}
|
||
{"type":"set_led_ring","mode":"find-me","all_clients":true,"slaves_only":true}
|
||
```
|
||
|
||
| `mode` | Notes |
|
||
|--------|--------|
|
||
| `clear` | Turn off |
|
||
| `color` | Full ring RGB + `intensity` |
|
||
| `progress` | `progress` 0–100 |
|
||
| `digit` | `digit` 0–10 |
|
||
| `blink` | `blink_ms`, `blink_count` |
|
||
| `find-me` | Locate pod |
|
||
|
||
Use `client_id` (`0` = master) or `all_clients` (+ optional `slaves_only`) for broadcast.
|
||
|
||
Response `led_ring_status`:
|
||
|
||
```json
|
||
{"type":"led_ring_status","success":true,"mode":5,"client_id":16,"slaves_updated":1}
|
||
```
|
||
|
||
### `get_battery`
|
||
|
||
Read cached battery samples from the master. Slaves push battery every **30 s**; this command reads the master cache.
|
||
|
||
```json
|
||
{"type":"get_battery","all_clients":true}
|
||
{"type":"get_battery","client_id":16}
|
||
```
|
||
|
||
Default if omitted: all clients.
|
||
|
||
Response `battery_status`:
|
||
|
||
```json
|
||
{
|
||
"type": "battery_status",
|
||
"success": true,
|
||
"samples": [
|
||
{
|
||
"client_id": 16,
|
||
"lipo1": {"valid": true, "voltage_mv": 3850, "percent": 71},
|
||
"lipo2": {"valid": false},
|
||
"age_ms": 1200
|
||
}
|
||
]
|
||
}
|
||
```
|