137 lines
5.9 KiB
Markdown
137 lines
5.9 KiB
Markdown
# Robovoice DHCP Tunnel Protocol
|
||
|
||
## Overview
|
||
|
||
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] --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:** 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
|
||
|
||
## Wire format
|
||
|
||
All messages are plain text, newline-terminated (`\n`). Every message starts
|
||
with the 6-byte magic `HKMSTR` to distinguish our traffic from real DHCP.
|
||
|
||
### Client → Server
|
||
|
||
**NOP (heartbeat while PTT held):**
|
||
```
|
||
HKMSTR <session> <nonce>\n
|
||
```
|
||
Sent every 50ms while PTT is held. The session is an incrementing unsigned
|
||
integer that identifies the current PTT utterance (incremented on each PTT
|
||
press). The nonce is an incrementing unsigned integer that makes each
|
||
datagram unique. The server should echo the session back in replies. Both
|
||
are discarded by the server for protocol logic — the server tracks liveness
|
||
via "did anything arrive recently."
|
||
|
||
**OFF (PTT released):**
|
||
```
|
||
HKMSTR:OFF <session> <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
|
||
|
||
The server echoes the session ID from the NOPs in all replies. The client
|
||
drops any reply with a stale session ID.
|
||
|
||
**Partial segment (completed VAD segment):**
|
||
```
|
||
HKMSTR:P <session> <text>\n
|
||
```
|
||
A completed, VAD-separated utterance segment. The client starts TTS
|
||
synthesis immediately and buffers the audio output, but does **not** play
|
||
it yet. Playback starts when `:F` arrives (or timeout).
|
||
|
||
**Final (all done):**
|
||
```
|
||
HKMSTR:F <session> <text>\n
|
||
```
|
||
Signals that all segments have been sent. May be empty
|
||
(`HKMSTR:F <session>\n`). Triggers playback of all buffered audio on the
|
||
client. If `<text>` is non-empty, the client synthesizes it before playing.
|
||
|
||
The purpose of this design is to minimize latency: TTS synthesis runs in
|
||
parallel with recording, so by the time `:F` arrives, audio is already
|
||
buffered and playback starts immediately.
|
||
|
||
## Server state machine
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ │
|
||
▼ │
|
||
┌──────────┐ first NOP ┌──────────────┐ │
|
||
│ IDLE │ ──────────► │ RECORDING │ │
|
||
└──────────┘ └──────────────┘ │
|
||
│ │ │
|
||
OFF │ │ 150ms │
|
||
recv'd │ │ silence │
|
||
▼ ▼ │
|
||
┌─────────────┐ │
|
||
│ PROCESSING │ │
|
||
└─────────────┘ │
|
||
│ │
|
||
send │ │
|
||
:P/:F │ │
|
||
▼ │
|
||
back to IDLE ──────────┘
|
||
```
|
||
|
||
- **IDLE → RECORDING:** first NOP received, start mic capture
|
||
- **RECORDING:** VAD detects completed segments → send `HKMSTR:P <text>`
|
||
- **RECORDING → PROCESSING:** OFF received, OR 150ms since last NOP
|
||
- **PROCESSING → IDLE:** send remaining segments as `:P`, then `HKMSTR:F`
|
||
|
||
## Client playback model
|
||
|
||
1. `:P` arrives → start TTS synthesis immediately, buffer audio (don't play).
|
||
Reset 250ms segment timer.
|
||
2. More `:P` arrive → keep synthesizing and buffering, reset timer each time.
|
||
3. `:F` arrives → play all buffered audio immediately, cancel timer.
|
||
4. If `:F` doesn't arrive within 250ms of the last `:P` → play buffered audio
|
||
early. If more `:P` arrive after early playback, synthesis continues and
|
||
new audio is appended to the output — not a failure.
|
||
5. `:F` may be empty — it just signals "all segments sent, start/confirm playback."
|
||
|
||
## Timing
|
||
|
||
| 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 |
|
||
|
||
## Why this works
|
||
|
||
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
|