From 57345b65982b384f2658dd687477a9a0f0307c4a Mon Sep 17 00:00:00 2001
From: Izaya <redtailedairways@gmail.com>
Date: Fri, 6 Apr 2018 16:42:03 +1000
Subject: [PATCH] wrote some more docs

---
 vTunnel/README.md           |  2 ++
 vTunnel/vtunnel-protocol.md | 57 +++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 vTunnel/vtunnel-protocol.md

diff --git a/vTunnel/README.md b/vTunnel/README.md
index 3335b14..d8110af 100644
--- a/vTunnel/README.md
+++ b/vTunnel/README.md
@@ -4,6 +4,8 @@ vTunnel can be used to add bridging over the internet to any existing OpenOS sof
 
 Despite originally being written for Minitel, vTunnel implements a fully-functional linked card emulator and a server that will run under most unix-likes (OpenBSD is currently somewhat flaky, Linux is recommended).
 
+The protocol is documented [here](vtunnel-protocol.md)
+
 ## Setup
 
 ### Server
diff --git a/vTunnel/vtunnel-protocol.md b/vTunnel/vtunnel-protocol.md
new file mode 100644
index 0000000..1f7b246
--- /dev/null
+++ b/vTunnel/vtunnel-protocol.md
@@ -0,0 +1,57 @@
+# vTunnel - Protocol
+
+vTunnel uses a (relatively) simple protocol to communicate over TCP, encoding packets as strings and adding a tag. The protocol is as follows:
+
+```
+<2 bytes length of packet><1 byte number of segments><2 bytes length of segment><1 byte type><data>
+```
+
+2-byte lengths are encoded as big-endian, as in the following code from interminitel.lua:
+
+```
+function imt.to16bn(n)
+ return string.char(math.floor(n/256))..string.char(math.floor(n%256))
+end
+```
+
+Each packet can have up to 255 segments, or indeed zero.
+
+So, to encode a packet with the field "Hello, world!":
+
+```
+0       \0
+17      \17     first two bytes are length
+1       \1      third is number of segments
+0       \0
+13      \13     length of first segment
+1       \1      type of first segment (string)
+72      H       data from here
+101     e
+108     l
+108     l
+111     o
+44      ,
+32       
+119     w
+111     o
+114     r
+108     l
+100     d
+33      !
+```
+
+## Types
+
+1. string
+2. number
+3. boolean
+4. nil
+
+## Defaults
+
+By default, the bridge server:
+
+- uses port 4096, as Minitel does on OpenComputers networks
+- drops clients after 60 seconds of inactivity
+
+This can be configured by **FIXME.**