Added documentation

manual/manual.typ

@@ -0,0 +1,165 @@
+#import "@preview/ilm:1.4.1": *
+#import "@preview/fletcher:0.5.8" as fletcher: diagram, node, edge, shapes
+
+#show link: underline
+#show link: set text(fill: blue)
+
+#set text(lang: "en")
+
+#show: ilm.with(
+  title: [SchoolBOX WS],
+  author: "Jurn Wubben",
+  date: datetime.today(),
+  abstract: [Websocket comminucation between the SchoolBox device and the associated server.],
+  figure-index: (enabled: false),
+  table-index: (enabled: false),
+  listing-index: (enabled: false)
+)
+// #show link: set text(stroke: blue)
+
+// #show: mantys(
+//   name: "SchoolBOX WS",
+//   version: "0.0.1",
+//   authors: (
+//     "Jurn Wubben",
+//   ),
+//   license: "MIT",
+//   description: "Websocket comminucation between the SchoolBox device and the associated server.",
+//   repository: "https://git.jsw.tf/jsw/schoolbox-ws",
+
+//   title: "SchoolBox WS",
+//   date: datetime.today(),
+// )
+
+= Messages
+== Heartbeat
+=== Server
+<ping>```json
+{"c": "ping"}
+```
+<pongmissed>```json
+{"e": 0, "info": "Pong missed"}
+```
+
+=== Device
+<pong>```json
+{"c": "pong"}
+```
+
+== Registration
+=== Server
+<reg_pin>```json
+{"c": "reg_pin", "d": {"pin": 1234}} // Pin is an integer.
+```
+<reg_ok>```json
+{"c": "reg_ok"}
+```
+
+=== Device
+<reg_start>```json
+{"c": "reg_start"}
+```
+
+
+== Authentication
+=== Server
+<auth_nonce>```json
+{"c": "auth_nonce", "d": {"nonce": "random_string"}}
+```
+<auth_ok>```json
+{"c": "auth_ok"}
+```
+<auth_error_id>```json
+{"e": 1, "info": "Invalid packet, wrong ID."}
+```
+<auth_error_sig>```json
+{"e": 2, "info": "Invalid signature."} // the info doesn't matter
+```
+<auth_error_takeover>```json
+{"e": 3, "info": "Logged in at other place."} // the info doesn't matter
+```
+
+=== Device
+<auth_start>```json
+{"c": "auth_start"}
+```
+<auth_validate>```json
+{"c": "auth_validate", "d": {"signature": "HMAC hash of nonce"}}
+```
+
+== Session
+=== Server
+<session_start>```json
+{"c": "session_start", "d": {"text": "Question?"}}
+```
+<session_stop>```json
+{"c": "session_stop"}
+```
+
+=== Device
+<session_vote>```json
+{"c": "session_vote", "d": {"vote": 1}} // Vote is an integer in the range of 1..5
+```
+
+
+= General flow
+#let arrLine = (arr) => {
+	for (i, el) in arr.enumerate() {
+		if i == 0 or i == arr.len() {
+			continue
+		}
+		edge(arr.at(i - 1), el, "-|>")
+	}
+}
+
+#let l = link;
+
+#align(center, diagram(
+	node-stroke: 1pt,
+
+	node((1,0), [New connection], corner-radius: 2pt, extrude: (0, 3), name: <flow_new>),
+
+	node((3, 0), l(<ping>)[ping], name: <flow_ping>),
+	node((3, 1), l(<pong>)[pong], stroke: blue, name: <flow_pong>),
+
+	node((0,1), l(<reg_start>)[reg_start], name: <flow_reg_start>, stroke: blue),
+	node((0,2), l(<reg_pin>)[reg_pin], name: <flow_reg_pin>),
+	node((0,3), l(<reg_ok>)[reg_ok], name: <flow_reg_ok>),
+	node((0,4), [Disconnect], name: <flow_disconnect>, corner-radius: 2pt, extrude: (0, 3)),
+
+	node((2,1), l(<auth_start>)[auth_start], name: <flow_auth_start>, stroke: blue),
+	node((1,1), l(<auth_error_id>)[auth error id], name: <flow_auth_error_id>),
+	node((2,2), l(<auth_nonce>)[auth_nonce], name: <flow_auth_nonce>),
+	node((1,3), l(<auth_error_sig>)[auth error signature], name: <flow_auth_error_sig>),
+	node((2,3), l(<auth_validate>)[auth_validate], name: <flow_auth_validate>, stroke: blue),
+	node((2,4), l(<auth_ok>)[auth_ok], name: <flow_auth_ok>),
+	node((1,5), [Logged in], corner-radius: 2pt, extrude: (0, 3), name: <flow_loggedin>),
+
+	edge(<flow_ping>, <flow_pong>, "<|-|>", label: [Every 30s]),
+
+	edge(<flow_new>, "l", <flow_reg_start>, "-|>"),
+	edge(<flow_new>, "r", <flow_auth_start>, "-|>"),
+	edge(<flow_auth_start>, <flow_auth_error_id>, "-|>"),
+	edge(<flow_auth_error_id>, <flow_auth_start>, "-|>", bend: 18deg),
+	edge(<flow_auth_validate>, <flow_auth_error_sig>, "-|>"),
+	edge(<flow_auth_error_sig>, <flow_auth_start>, "-|>", bend: 23deg),
+	edge(<flow_auth_ok>, "d", <flow_loggedin>, "-|>"),
+
+	arrLine((<flow_reg_start>, <flow_reg_pin>, <flow_reg_ok>, <flow_disconnect>)),
+	arrLine((<flow_auth_start>, <flow_auth_nonce>, <flow_auth_validate>, <flow_auth_ok>)),
+
+	node((0,6), l(<session_start>)[session_start], name: <flow_session_start>),
+	node((0,7), l(<session_vote>)[session_vote], name: <flow_session_vote>),
+	node((0,8), l(<session_stop>)[session_stop], name: <flow_session_stop>),
+
+	node((2, 6), l(<auth_error_takeover>)[auth takeover error], corner-radius: 2pt, extrude: (0, 3), name: <flow_session_takeover>),
+
+	edge(<flow_loggedin>, "l", <flow_session_start>, "-|>"),
+	edge(<flow_session_start>, <flow_session_vote>,  "-|>"),
+	edge(<flow_session_vote>,  <flow_session_stop>,  "-|>"),
+	edge((0, 7), (0, 7),  "--|>", bend: 300deg, loop-angle: 200deg),
+	edge(<flow_session_stop>, "r", <flow_loggedin>,  "-|>"),
+
+	edge(<flow_loggedin>, "r", <flow_session_takeover>, "-|>")
+	
+))