base-station: Add documentation comments.

base-station/software/src/current.rs

@@ -1,9 +1,15 @@
+//! Cache of the most recently received reports.
+
 use std::collections::HashMap;
 
 use log::error;
 
 use protocol::{Location, Value, ValueType};
 
+/// Cache of the most recently received reports.
+///
+/// To remove the need to query MQTT/InfluxDB, this struct holds the most recently received reports
+/// from the sensors.
 pub struct CurrentValues {
     map: HashMap<Key, i64>,
 }

base-station/software/src/main.rs

@@ -1,3 +1,7 @@
+//! Interface between the NRF24 sensors and MQTT/InfluxDB.
+//!
+//! TODO: Document configuration and hardware setup.
+
 use std::env;
 use std::io;
 use std::sync::Arc;
@@ -55,6 +59,7 @@ async fn main() {
     }
 }
 
+/// Type which implements packet handling and responds to requests from devices.
 struct Application {
     radio: Arc<Mutex<Radio>>,
     publish: Arc<Mutex<Publish>>,
@@ -64,6 +69,8 @@ struct Application {
 }
 
 impl Application {
+    /// Handles a single packet from a device and either sends the data to MQTT/InfluxDB or
+    /// generates a response to the device.
     async fn handle_packet(&mut self, device_id: u8, packet: Packet) {
         // TODO: More packet types to query timeseries database.
         match packet {

base-station/software/src/publish.rs

@@ -1,15 +1,35 @@
+//! Interface to a publish values via MQTT.
+
 use protocol::{Location, Value};
 
+// TODO: Configuration mechanism.
+
+/// Interface to MQTT.
 pub struct Publish {
     // TODO
 }
 
 impl Publish {
+    /// Initializes the connection to MQTT.
+    ///
+    /// The function does not return an error. Instead, the code will automatically retry
+    /// connection in case the connection cannot be established or the server closes the
+    /// connection.
     pub fn init() -> Publish {
         // TODO
         Publish {}
     }
 
+    /// Publishes values received from a device.
+    ///
+    /// If there is no current connection to MQTT and the connection cannot be reestablished before
+    /// the application is stopped, the values are lost. If multiple calls to this function occur
+    /// while there is no current connection to MQTT, only the latest values are published.
+    ///
+    /// # Arguments
+    ///
+    /// * `location` - the location of the device
+    /// * `values` - a list of values to be published
     pub async fn publish(&mut self, _location: Location, _values: &[Value]) {
         // TODO
     }

base-station/software/src/radio.rs

@@ -1,3 +1,5 @@
+//! Wrapper around the NRF24 driver which provides tokio-compatible asynchronous interfaces.
+
 /*use std::convert::TryInto;
 use std::sync::mpsc;
 use std::thread;
@@ -26,15 +28,18 @@ const DISPLAY_ID: u8 = 0x20;
 const WEATHER_STATION_0_ID: u8 = 0x30;
 //const WEATHER_STATION_0_KEY: [u8; 16] = include!("../../../common/weather_station_0_key.txt");
 
+/// Hardware configuration.
 pub struct RadioConfig {
     // TODO
 }
 
+/// Wrapper around the NRF24 radio driver.
 pub struct Radio {
     // TODO
 }
 
 impl Radio {
+    /// Initializes the radio and returns both radio and the stream of incoming packets.
     pub async fn init(
         _config: RadioConfig,
     ) -> Result<(Radio, UnboundedReceiver<(u8, Packet)>), RadioError> {
@@ -42,6 +47,14 @@ impl Radio {
         panic!("Not yet implemented.");
     }
 
+    /// Sends a packet to the specified device.
+    ///
+    /// The function returns immediately, and the packet might or might not be sent successfully.
+    ///
+    /// # Arguments
+    ///
+    /// * `device_id` - the ID of the targeted device
+    /// * `packet` - the packet to send
     pub fn send_packet_async(&mut self, _device_id: u8, _packet: Packet) {
         // TODO
         panic!("Not yet implemented.");

base-station/software/src/spi.rs

@@ -1,9 +1,12 @@
+//! Implementation of `embedded_hal::blocking::spi::Transfer` for `linux_embedded_hal::spidev`.
+
 use std::io;
 
 use embedded_hal::blocking::spi::Transfer;
 use linux_embedded_hal::spidev::Spidev;
 use linux_embedded_hal::spidev::SpidevTransfer;
 
+/// Wrapper around `linux_embedded_hal::spidev::Spidev` which provides `Transfer`.
 pub struct EmbeddedHalSpidev {
     spi: Spidev,
 }

base-station/software/src/tsdb.rs

@@ -1,17 +1,39 @@
+//! Interface to fill/query a timeseries database (InfluxDB).
+
 use std::time::Instant;
 
 use protocol::{Location, Value};
 
+// TODO: Configuration mechanism.
+
+/// Interface to InfluxDB.
 pub struct TimeSeriesDatabase {
     // TODO
 }
 
 impl TimeSeriesDatabase {
+    /// Initializes the connection to InfluxDB.
+    ///
+    /// The function does not return an error. Instead, the code will automatically retry
+    /// connection in case the connection cannot be established or the server closes the
+    /// connection.
     pub fn init() -> TimeSeriesDatabase {
         // TODO
         TimeSeriesDatabase {}
     }
 
+    /// Inserts values into the database.
+    ///
+    /// If there is no current connection to InfluxDB and the connection cannot be reestablished
+    /// before the application is stopped, the values are lost. If multiple calls to this function
+    /// occur while there is no current connection to InfluxDB, the values are queued and all
+    /// values are inserted at a later time.
+    ///
+    /// # Arguments
+    ///
+    /// * `time` - time at which the values were received
+    /// * `location` - location of the device which sent the values
+    /// * `values` - list of values to be inserted into the database
     pub async fn insert(&mut self, _time: Instant, _location: Location, _values: &[Value]) {
         // TODO
     }