Description of the basic synchronized network protocol.

documentation/protocol.md

@@ -0,0 +1,108 @@
+
+# Protocol
+
+The base station communicates with the sensor nodes via radio. This document
+describes the different layers of the protocol used. The names of the layers
+roughly follow the OSI model, although some of the OSI layers are not required
+for the scenario.
+
+## Physical Layer
+
+The devices communicate via NRF24L01 radio modules.
+
+TODO:
+* Data rate?
+* Frequency?
+
+## Data Link Layer
+
+The protocol uses the NRF24L01 Enhanced ShockBurst mode for reliable
+transmission of packets. To ensure minimum power consumption in all nodes
+(including the base station), the nodes are synchronized and wake up only once
+per update period and transition back to sleep as quickly as possible. The
+following protocol is used to implement such a behavior:
+
+### Base Station
+
+The base station wakes up once per update period and executes the following:
+
+1. The base station sends one packet to each known connected sensor node and
+   then waits at most TODO microseconds for a reply from the node. If no reply
+   arrives, the node is marked as inactive, which might trigger updates to the
+   user interface to signal the connection state. Inactive nodes may be dropped
+   if new nodes connect.
+
+2. The base station may send further packets to the connected sensor nodes.
+
+3. The base station optionally sends a packet to signal that it listens for new
+   unknown sensor nodes and then listens for packets for TODO microseconds. If,
+   during this interval, a packet from a new node is received, the procedure for
+   a new node as described below is executed. After a new node is connected, the
+   base station repeats step 3 and sends another packet signaling that it
+   listens for connections.
+
+   The base station may always listen for new nodes,
+   letting the user afterwards select which connections to keep
+   and which to drop again, or listening for new nodes may be dependend on a
+   button press, after which the base station accepts new nodes for a
+   pre-defined time.
+
+##### Connection Setup
+
+TODO
+
+### Sensor Node
+
+As long as a sensor node is not synchronized to a base station, it executes the
+following steps:
+
+1. The sensor node continuously listens for packets.
+
+2. If a packet is received which indicates that a base station listens for new
+   connections, the sensor node waits for a random time between TODO and TODO
+   microseconds and then sends a packet back to initiate connection setup. The
+   node proceeds as described below.
+
+3. If the node has previously stored connection information and receives a
+   packet from the corresponding base station directed at the node, the node
+   uses the arrival time of the packet to synchronize with the base station and
+   then responds to the packet, proceeding with the protocol for synchronized
+   nodes below.
+
+4. The node may implement duty cycling to reduce power consumption during long
+   periods without synchronization to a base station: Between phases of
+   listening for packets, the node may sleep for some time. Each period of
+   listening must last longer than an update period to ensure that no available
+   base stations are missed. In setups where base stations only listen for new
+   devices when activated by the user, the sleeping period must not be longer
+   than the duration during which the base station listens for new nodes.
+
+Once a sensor node is synchronized to a base station, it repeatedly executes the
+following steps:
+
+1. The node takes the time of the first packet received during the last update
+   period and calculates the expected time of the next packet by adding the
+   update period to the time. The node then subtracts 1% of an update period to
+   compensate any clock skew. The node then sleeps until the calculated time and
+   starts to listen for packets for 5% of the update period. The arrival time of
+   the first packet directed at the node received during this time is taken as
+   the basis for the next wakeup time calculation.
+
+2. If the node receives a packet directed at the node, it processes the packet.
+   If no packet was received for TODO microseconds, the node continues with step
+   1 to go to sleep again.
+
+3. If no packet directed at the node was received during the time span, the node
+   assumes that it lost synchronization to the base station and starts again
+   with the steps above for this situation.
+
+##### Connection Setup
+
+TODO
+
+## Presentation Layer
+
+TODO:
+* Encryption?
+
+