1 files changed, 57 insertions, 0 deletions
diff --git a/shared/protocol.md b/shared/protocol.md
new file mode 100644
index 0000000..1e52e42
--- /dev/null
+++ b/shared/protocol.md
@@ -0,0 +1,57 @@
+# Protocol spec
+
+This is a brief overview of the protocol specifications that the weather
+station uses to send and receive data between the weather station and qt
+client. This protocol is text-based, and used over a TCP connection. This
+document will only go into detail about the data sent over this connection, not
+requirements about the connection itself.
+
+The protocol is only used in a request-response fashion, so all commands are
+assumed to be sent by the qt client, and responded to by the weather station.
+
+~Functions for generating commands and parsing incoming data are provided by
+the protocol.c and protocol.h files in this folder.~ A server using these files
+should implement every protocol handler function in a seperate c file, along
+with a data sending function that is also used internally.
+
+- LF for newline instead of CRLF
+- Commands are single-line
+- Spaces used for separating command arguments
+- Commands with malformed data are discarded and return error
+- Response consist of `ok` or `error`, a comma, and the byte length of the
+  remaining response (if any)
+- Numbers are sent as hexadecimal
+
+## Commands
+
+### `last-records <n> <o>`
+
+Returns the last `n` records with offset `<o>` in csv format. The first line
+has the csv table header, with the fields `id`, `temperature`, `humidity`, and
+`atmospheric_pressure`. The rest of the response consists of 1 record per line.
+The amount of records is limited to the amount of valid records in the backlog
+buffer. When the amount of returned records is 0, the response consists of the
+csv header, but without any following records.
+
+Offset `<o>` is a positive integer, representing the starting point for the
+most recent record that is returned, this will get subtracted from the id of
+the most recent record. E.g. if the last record has id `00f0`, and a request is
+sent with parameters `n=3` and `o=5`, the records with id's `00eb`, `00ea`, and
+`00e9` will be returned.
+
+## Example transaction
+
+In the following example, newlines are indicated by `<0a>`, request by lines
+starting with `<`, and response by lines starting with `>`.
+
+```
+< last-records 5 0<0a>
+> ok,73<0a>
+> id,temperature,humidity,atmospheric_pressure<0a>
+> 10dc,2f,c5,7f<0a>
+> 10dd,30,c6,7f<0a>
+> 10de,31,c7,7f<0a>
+> 10df,35,ca,7e<0a>
+> 10e0,34,c9,7e<0a>
+```
+