Document the protocol

README.md

@@ -12,3 +12,7 @@ through an Arduino micro running a keyer program.
 This program is on github as [vail-adapter](https://github.com/nealey/vail-adapter),
 or [in Arduino Create](https://create.arduino.cc/editor/neale/f94bb765-47bd-4bc4-9cbf-b978f7124bdc).
 
+More Documentation
+-------
+
+* [Vail Protocol](docs/protocol.md)

docs/protocol.md

@@ -0,0 +1,94 @@
+The Vail Protocol
+=============
+
+Vail messages can be encoded with JSON or marshaled into a "binary" format.
+
+Go Definition
+--------------------
+
+```go
+type Message struct {
+	// Timestamp of this message. Milliseconds since epoch.
+	Timestamp int64
+
+	// Message timing in milliseconds.
+	// Timings alternate between tone and silence.
+	// For example, `A` could be sent as [80, 80, 240]
+	Duration []uint16
+}
+```
+
+JSON
+-------
+
+JSON-encoded Vail messages are a direct encoding of the struct:
+
+```json
+{
+    "Timestamp": 1702846980,
+    "Duration": [80, 80, 240]
+}
+```
+
+This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.
+
+
+Binary Marshalling
+---------------------
+
+The binary marshalled version of a Vail message is encoded big-endian:
+
+    00 00 00 00 65 7f 62 04   00 50 00 50 00 f0
+
+Is decoded as:
+
+* Timestamp (int64): `00 00 00 00 65 7f 62 04` = 1702846980
+* Duration ([]uint16):
+  * `00 50` = 80
+  * `00 50` = 80
+  * `00 f0` = 240
+
+This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.
+
+
+WebSockets
+==========
+
+The reference Vail server accepts WebSockets communications to the path `/chat`,
+with the channel sent as the 'repeater' query parameter.
+
+For instance, the "Example" channel is
+wss://vail.woozle.org/chat?repeater=Example
+
+The WebSockets subprotocol may be either:
+
+* `json.vail.woozle.org` for JSON packets
+* `binary.vail.woozle.org` for binary marshalled packets
+
+
+Practical Considerations
+==================
+
+I am a network protocol designer:
+Vail was designed to contend with
+Internet latency and jitter.
+It relies heavily on an accurate Real-Time Clock on each client.
+
+Playback Delay
+------------------
+
+Clients should implement a delay on playback of all recieved messages,
+to allow for network latency and jitter.
+
+I have found that a 2-second delay is usually enough, but people on very high-latency links may need a larger delay.
+
+If the timestamp + delay on a recieved packet is after the current time of day,
+it may be appropriate to increase the delay.
+
+Clock skew
+---------------
+
+On connecting,
+clients will recieve a packet with no Durations.
+Clients should use this timestamp
+to estimate skew between the client and server's clock.