First part of protocol documentation.

README.md

@@ -47,6 +47,57 @@ For an Ubuntu host, the following steps can be used:
 
         cargo build --target=arm-unknown-linux-gnueabihf
 
+# Protocol
+
+Packets are up to 32 bytes long. Most bytes are encrypted via XXTEA, except for
+one packet sent to the base station from a device to request a random number. The
+base station then replies with an encrypted packet containing a random salt
+value, and the device uses this salt for all further communication until the next
+reset, increasing the salt value by one for each packet sent. This scheme removes
+the need for the device to generate random numbers, as microcontrollers commonly
+are not capable of generation of high-quality ranodm numbers.
+
+The packet sent from the device to the base station to request a salt consists of
+a single byte with the sender ID and is recognized by the base station by its
+length.
+
+All encrypted packets follow the same scheme, with everything following after the
+salt being encrypted using a per-device XXTEA key hardcoded on the device and
+known to the base station. The packet fields are as follows, with multi-byte
+fields being encoded as little-endian:
+
+1. Device ID (1 byte)
+2. Salt (8 bytes)
+
+   The most significant bit of the salt value is 0 for packets from the device
+   to the base station and 1 for packets from the base station to the device.
+
+All fields from here on are encrypted with XXTEA, using the salt value contained
+in the packet.
+
+
+
+3. Packet type and element count (1 byte)
+
+   The 5 least significant bits of the field encode the packet type, with the
+   following possible values:
+
+   0. Salt: The packet is sent by the base station to the device whenever a
+      1-byte packet containing the device ID is received.
+   1. Report: The packet contains values measured by _this_ node. The element
+      count signals the number of values (of different types) reported by the
+      device.
+   2. GetValues: Sent by a device to request values generated by _other_ sensor
+      nodes from the base station, or to request the current time. The element
+      count signals the number of different values requested.
+   3. Values: Reply to a `GetValues` packet containing the requested information.
+
+4. Packet payload (variable)
+
+   TODO
+
+5. CRC-16-CCITT checksum
+
 # License
 
 The hardware contained in this repository is licensed under the [CERN Open Hardware Licence Version 2 - Weakly Reciprocal](cern_ohl_w_v2.txt), and the software is licensed under the [GNU General Public License v3](gpl-3.0.md).