Updating docs

src/hardware/clock.rs

@@ -1,3 +1,9 @@
+//! Booster system clock setup and management routines.
+//!
+//! # Copyright
+//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved
+//! Unauthorized usage, editing, or copying is strictly prohibited.
+//! Proprietary and confidential.
 use minimq::embedded_time::{
     clock::{Clock, Error},
     fraction::Fraction,
@@ -6,10 +12,23 @@ use minimq::embedded_time::{
 
 use core::convert::TryInto;
 
+/// The SystemTimer is the main timekeeping mechanism for the device.
+///
+/// # Note
+/// At current configurations, the timer overflows every 2^32 10KHz ticks, which corresponds to
+/// approximately just shy of every 5 days.
 #[derive(Copy, Clone, Debug, Default)]
 pub struct SystemTimer {}
 
 impl SystemTimer {
+    /// Initialize the SystemTimer for use in time keeping.
+    ///
+    /// # Note
+    /// The system timer is always configured for 10KHz.
+    ///
+    /// # Args
+    /// * `regs` - The TIM2 register block.
+    /// * `clocks` - The configured RCC clocks.
     pub fn initialize(regs: stm32f4xx_hal::stm32::TIM2, clocks: &stm32f4xx_hal::rcc::Clocks) {
         // Reset and enable the timer in the RCC.
         let rcc = unsafe { &*stm32f4xx_hal::stm32::RCC::ptr() };
@@ -49,6 +68,9 @@ impl Clock for SystemTimer {
         let regs = unsafe { &*stm32f4xx_hal::stm32::TIM2::ptr() };
 
         // The TIM2 peripheral is a 32-bit counter.
+        // Note: We silently ignore overflows of the CNT register because `embedded-time` will
+        // automatically handle overflowed tick counts as long as the space between them is less
+        // than ~2.5 days.
         Ok(Instant::new(regs.cnt.read().bits()))
     }
 }

src/net/mod.rs

@@ -1,3 +1,9 @@
+//! Booster network management definitions
+//!
+//! # Copyright
+//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved
+//! Unauthorized usage, editing, or copying is strictly prohibited.
+//! Proprietary and confidential.
 use crate::hardware::NetworkStack;
 
 use crate::delay::AsmDelay;
@@ -7,10 +13,15 @@ mod shared;
 mod telemetry;
 
 use mqtt_control::ControlState;
-
 use shared::NetworkManager;
+
 type NetworkStackProxy = shared::NetworkStackProxy<'static, NetworkStack>;
 
+/// Container structure for holding all network devices.
+///
+/// # Note
+/// All devices accessing the shared stack must be contained within a single structure to prevent
+/// potential pre-emption when using the `shared` network stack.
 pub struct NetworkDevices {
     pub controller: mqtt_control::ControlState,
     pub telemetry: telemetry::TelemetryClient,
@@ -21,6 +32,13 @@ pub struct NetworkDevices {
 }
 
 impl NetworkDevices {
+    /// Construct all of Booster's Network devices.
+    ///
+    /// # Args
+    /// * `broker` - The broker IP address for MQTT.
+    /// * `stack` - The network stack to use for communications.
+    /// * `identifier` - The unique identifier of this device.
+    /// * `delay` - A delay mechanism.
     pub fn new(
         broker: minimq::embedded_nal::IpAddr,
         stack: NetworkStack,
@@ -38,6 +56,11 @@ impl NetworkDevices {
         }
     }
 
+    /// Process the network stack.
+    ///
+    /// # Note
+    /// This function must be called periodically to handle ingress/egress of packets and update
+    /// state management.
     pub fn process(&mut self) -> bool {
         self.telemetry.process();
 

src/net/shared.rs

@@ -1,3 +1,13 @@
+//! Booster shared network stack management
+//!
+//! # Note
+//! Portions of this file are taken from the
+//! [`smoltcp-nal`](https://github.com/quartiq/smoltcp-nal/blob/main/src/shared.rs)
+//!
+//! # Copyright
+//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved
+//! Unauthorized usage, editing, or copying is strictly prohibited.
+//! Proprietary and confidential.
 use minimq::embedded_nal;
 use shared_bus::{AtomicCheckMutex, BusMutex};
 

src/net/telemetry.rs

@@ -1,16 +1,28 @@
+//! Booster telemetry client management
+//!
+//! # Copyright
+//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved
+//! Unauthorized usage, editing, or copying is strictly prohibited.
+//! Proprietary and confidential.
 use super::NetworkStackProxy;
 use crate::hardware::{clock::SystemTimer, Channel};
-
 use core::fmt::Write;
 use heapless::String;
 use serde::Serialize;
 
+/// Telemetry reporting MQTT client.
 pub struct TelemetryClient {
     mqtt: minimq::Minimq<NetworkStackProxy, SystemTimer, 512, 1>,
     prefix: String<128>,
 }
 
 impl TelemetryClient {
+    /// Construct the telemetry client.
+    ///
+    /// # Args
+    /// * `broker` - The Booster MQTT broker IP address.
+    /// * `stack` - A reference to the shared network stack.
+    /// * `identifier` - The unique Booster ID.
     pub fn new(
         broker: minimq::embedded_nal::IpAddr,
         stack: NetworkStackProxy,
@@ -28,6 +40,11 @@ impl TelemetryClient {
         }
     }
 
+    /// Publish telemetry for a specific channel.
+    ///
+    /// # Args
+    /// * `channel` - The channel that telemetry is being reported for.
+    /// * `telemetry` - The associated telemetry of the channel to report.
     pub fn report_telemetry(&mut self, channel: Channel, telemetry: &impl Serialize) {
         let mut topic: String<64> = String::new();
         write!(&mut topic, "{}/ch{}", self.prefix, channel as u8).unwrap();
@@ -47,10 +64,10 @@ impl TelemetryClient {
             .unwrap();
     }
 
-    // Update the telemetry client.
-    //
-    // # Note
-    // This must be called periodically to advance the MQTT state machine.
+    /// Update the telemetry client.
+    ///
+    /// # Note
+    /// This must be called periodically to advance the MQTT state machine.
     pub fn process(&mut self) {
         self.mqtt
             .poll(|_client, _topic, _message, _properties| {})