Document the protocol

This commit is contained in:
Neale Pickett 2023-12-17 14:27:04 -07:00
parent 55b222d784
commit 92b109b933
2 changed files with 98 additions and 0 deletions

View File

@ -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), 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). or [in Arduino Create](https://create.arduino.cc/editor/neale/f94bb765-47bd-4bc4-9cbf-b978f7124bdc).
More Documentation
-------
* [Vail Protocol](docs/protocol.md)

94
docs/protocol.md Normal file
View File

@ -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.