Updating net module

src/bin/dual-iir.rs

@@ -141,7 +141,7 @@ const APP: () = {
 
     #[task(priority = 1, resources=[mqtt_settings, afes, iir_ch])]
     fn settings_update(mut c: settings_update::Context) {
-        let settings = &c.resources.mqtt_settings.mqtt_interface.settings;
+        let settings = &c.resources.mqtt_settings.mqtt.settings;
 
         // Update the IIR channels.
         c.resources.iir_ch.lock(|iir| *iir = settings.iir_ch);

src/bin/lockin-external.rs

@@ -205,7 +205,7 @@ const APP: () = {
 
     #[task(priority = 1, resources=[mqtt_settings, settings, afes])]
     fn settings_update(mut c: settings_update::Context) {
-        let settings = &c.resources.mqtt_settings.mqtt_interface.settings;
+        let settings = &c.resources.mqtt_settings.mqtt.settings;
 
         c.resources.afes.0.set_gain(settings.afe[0]);
         c.resources.afes.1.set_gain(settings.afe[1]);

src/net/mod.rs

@@ -4,16 +4,21 @@ use crate::hardware::{
 
 use miniconf::{minimq, MqttInterface};
 
+/// Potential actions for firmware to take.
 pub enum Action {
+    /// Indicates that firmware can sleep for the next event.
     Sleep,
+
+    /// Indicates that settings have updated and firmware needs to propogate changes.
     UpdateSettings,
 }
 
+/// MQTT settings interface.
 pub struct MqttSettings<S>
 where
     S: miniconf::Miniconf + Default,
 {
-    pub mqtt_interface: MqttInterface<S, NetworkStack, minimq::consts::U256>,
+    pub mqtt: MqttInterface<S, NetworkStack, minimq::consts::U256>,
     clock: CycleCounter,
     phy: EthernetPhy,
     network_was_reset: bool,
@@ -23,6 +28,14 @@ impl<S> MqttSettings<S>
 where
     S: miniconf::Miniconf + Default,
 {
+    /// Construct a new MQTT settings interface.
+    ///
+    /// # Args
+    /// * `stack` - The network stack to use for communication.
+    /// * `client_id` - The ID of the MQTT client. May be an empty string for auto-assigning.
+    /// * `prefix` - The MQTT device prefix to use for this device.
+    /// * `phy` - The PHY driver for querying the link state.
+    /// * `clock` - The clock to utilize for querying the current system time.
     pub fn new(
         stack: NetworkStack,
         client_id: &str,
@@ -30,7 +43,7 @@ where
         phy: EthernetPhy,
         clock: CycleCounter,
     ) -> Self {
-        let mqtt_interface = {
+        let mqtt = {
             let mqtt_client = {
                 minimq::MqttClient::new(MQTT_BROKER.into(), client_id, stack)
                     .unwrap()
@@ -40,17 +53,22 @@ where
         };
 
         Self {
-            mqtt_interface,
+            mqtt,
             clock,
             phy,
             network_was_reset: false,
         }
     }
 
+    /// Update the MQTT interface and service the network
+    ///
+    /// # Returns
+    /// An option containing an action that should be completed as a result of network servicing.
     pub fn update(&mut self) -> Option<Action> {
         let now = self.clock.current_ms();
 
-        let sleep = match self.mqtt_interface.network_stack().poll(now) {
+        // First, service the network stack to process and inbound and outbound traffic.
+        let sleep = match self.mqtt.network_stack().poll(now) {
             Ok(updated) => !updated,
             Err(err) => {
                 log::info!("Network error: {:?}", err);
@@ -58,20 +76,21 @@ where
             }
         };
 
-        // If the PHY indicates there's no more ethernet link, reset the network stack and close all
+        // If the PHY indicates there's no more ethernet link, reset the DHCP server in the network
-        // sockets.
+        // stack.
         if self.phy.poll_link() == false {
             // Only reset the network stack once per link reconnection. This prevents us from
             // sending an excessive number of DHCP requests.
             if !self.network_was_reset {
                 self.network_was_reset = true;
-                self.mqtt_interface.network_stack().handle_link_reset();
+                self.mqtt.network_stack().handle_link_reset();
             }
         } else {
             self.network_was_reset = false;
         }
 
-        match self.mqtt_interface.update() {
+        // Finally, service the MQTT interface and handle any necessary messages.
+        match self.mqtt.update() {
             Ok(true) => Some(Action::UpdateSettings),
             Ok(false) if sleep => Some(Action::Sleep),
             Ok(_) => None,