v0.6: DHCP tunnel transport with NOP heartbeat protocol
This commit is contained in:
+93
-52
@@ -1,70 +1,111 @@
|
||||
# Robovoice TCP STT Protocol
|
||||
# Robovoice DHCP Tunnel Protocol
|
||||
|
||||
## Overview
|
||||
|
||||
Robovoice acts as a **client**: it connects to a remote STT server over TCP,
|
||||
sends control messages when the user presses/releases the PTT key, and
|
||||
receives transcript messages back. The STT server captures audio from a
|
||||
microphone, runs speech recognition (Moonshine), and sends transcripts back
|
||||
over the same connection.
|
||||
Robovoice communicates with a remote STT server by tunneling through the
|
||||
DHCP UDP ports (68→67). This exploits a common killswitch exception: VPN
|
||||
software (e.g. WireGuard) blocks all traffic except DHCP, which is allowed
|
||||
for network connectivity maintenance.
|
||||
|
||||
```
|
||||
[Robovoice client] --TCP--> [STT server :5210]
|
||||
│ │
|
||||
├── {"event":"on"}\n ──────►│
|
||||
│ ├── capture audio
|
||||
├── {"event":"off"}\n ──────►│
|
||||
│ ├── run STT
|
||||
│◄── {"final":true,...}\n ──┤
|
||||
[Robovoice client] --broadcast UDP :68→:67--> [STT server]
|
||||
[Robovoice client] <--unicast UDP :67→:68-- [STT server]
|
||||
```
|
||||
|
||||
The client broadcasts NOP heartbeats while PTT is held. The server starts
|
||||
recording on the first NOP and stops when it receives OFF or when 150ms
|
||||
pass with no NOPs.
|
||||
|
||||
## Transport
|
||||
|
||||
- **Protocol:** TCP (reliable, ordered, connection-oriented)
|
||||
- **Server endpoint:** configurable in Robovoice UI (default `127.0.0.1:5210`)
|
||||
- **Framing:** newline-delimited JSON (NDJSON) — each message is a single
|
||||
UTF-8 JSON object terminated by `\n`
|
||||
- **Auto-reconnect:** if the connection drops, Robovoice retries every 3
|
||||
seconds until the server is available
|
||||
- **Protocol:** UDP (connectionless, unreliable)
|
||||
- **Client → Server:** broadcast, source port 68, dest port 67
|
||||
- **Server → Client:** unicast, source port 67, dest port 68
|
||||
- **Client binds:** to a specific LAN interface IP on port 68 (with
|
||||
`SO_REUSEADDR` to coexist with the Windows DHCP service)
|
||||
- **No connection state** — purely fire-and-forget datagrams
|
||||
|
||||
## Control messages (client → server)
|
||||
## Wire format
|
||||
|
||||
Sent by Robovoice when the user presses/releases the PTT key.
|
||||
All messages are plain text, newline-terminated (`\n`). Every message starts
|
||||
with the 6-byte magic `HKMSTR` to distinguish our traffic from real DHCP.
|
||||
|
||||
```json
|
||||
{"event": "on"}
|
||||
### Client → Server
|
||||
|
||||
**NOP (heartbeat while PTT held):**
|
||||
```
|
||||
HKMSTR <nonce>\n
|
||||
```
|
||||
Sent every 50ms while PTT is held. The nonce is an incrementing unsigned
|
||||
integer that makes each datagram unique. The server discards it — it's
|
||||
purely for packet uniqueness, not for any protocol logic.
|
||||
|
||||
**OFF (PTT released):**
|
||||
```
|
||||
HKMSTR:OFF <nonce>\n
|
||||
```
|
||||
Sent once when PTT is released. This is the fast-stop signal. If lost, the
|
||||
150ms timeout acts as a backstop.
|
||||
|
||||
### Server → Client
|
||||
|
||||
**Partial transcript:**
|
||||
```
|
||||
HKMSTR:P <text>\n
|
||||
```
|
||||
Intermediate recognition result. Fire-and-forget. Client logs it but does
|
||||
not act on it.
|
||||
|
||||
**Final transcript:**
|
||||
```
|
||||
HKMSTR:F <text>\n
|
||||
```
|
||||
Complete utterance. Client feeds this to the TTS engine.
|
||||
|
||||
## Server state machine
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ │
|
||||
▼ │
|
||||
┌──────────┐ first NOP ┌──────────────┐ │
|
||||
│ IDLE │ ──────────► │ RECORDING │ │
|
||||
└──────────┘ └──────────────┘ │
|
||||
│ │ │
|
||||
OFF │ │ 150ms │
|
||||
recv'd │ │ silence │
|
||||
▼ ▼ │
|
||||
┌─────────────┐ │
|
||||
│ PROCESSING │ │
|
||||
└─────────────┘ │
|
||||
│ │
|
||||
STT │ │
|
||||
done │ │
|
||||
▼ │
|
||||
send HKMSTR:F ─────────┘
|
||||
```
|
||||
|
||||
```json
|
||||
{"event": "off"}
|
||||
```
|
||||
- **IDLE → RECORDING:** first NOP received, start mic capture
|
||||
- **RECORDING → PROCESSING:** OFF received, OR 150ms since last NOP
|
||||
- **PROCESSING → IDLE:** STT done, send `HKMSTR:F <text>`
|
||||
|
||||
| Field | Type | Description |
|
||||
|---------|--------|------------------------------------|
|
||||
| `event` | string | `"on"` (PTT pressed) or `"off"` (PTT released) |
|
||||
## Timing
|
||||
|
||||
## Transcript messages (server → client)
|
||||
| Parameter | Value | Purpose |
|
||||
|-----------|-------|---------|
|
||||
| NOP interval | 50ms | Heartbeat frequency while PTT held |
|
||||
| Silence timeout | 150ms | Stop recording if no NOPs (3 missed = lost OFF) |
|
||||
| NOP bandwidth | ~20 msg/s × ~20 bytes | ~400 bytes/s — negligible |
|
||||
|
||||
Sent by the server back to Robovoice over the same TCP connection.
|
||||
## Why this works
|
||||
|
||||
```json
|
||||
{"final": false, "text": "hello world"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"final": true, "text": "hello world how are you"}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---------|---------|----------|--------------------------------------------------|
|
||||
| `final` | bool | yes | `true` = final result, `false` = partial |
|
||||
| `text` | string | yes | The transcript text (may be empty for partials) |
|
||||
|
||||
### Semantics
|
||||
|
||||
- **`final: false`** — intermediate recognition result (partial). Robovoice
|
||||
logs these but does not act on them (only `final` triggers TTS).
|
||||
- **`final: true`** — complete utterance. Robovoice feeds this to the TTS
|
||||
engine and speaks it.
|
||||
|
||||
Malformed JSON or unknown field values are silently dropped by the client.
|
||||
1. **Outbound broadcast `:68→:67` to `255.255.255.255`** passes the
|
||||
WireGuard WFP killswitch (DHCP exception matches this exact pattern)
|
||||
2. **Inbound `:67→:68`** has no address restriction in the WFP rule, so
|
||||
unicast replies pass through
|
||||
3. **Binding to a specific interface IP** (not `0.0.0.0`) wins unicast
|
||||
delivery over the Windows DHCP client service
|
||||
4. **NOP spam** ensures the ON message gets through even at 5% packet loss
|
||||
(3 consecutive NOPs = ~0.01% drop probability)
|
||||
5. **150ms timeout** is the backstop for lost OFF — at 50ms intervals, 3
|
||||
consecutive NOPs must all be lost to false-stop
|
||||
|
||||
Reference in New Issue
Block a user