
# 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?


