docs: improve mqtt_example code docs

Author: j-g00da

mqtt_example/sdkconfig.defaults

@@ -8,3 +8,6 @@ CONFIG_ESP_MAIN_TASK_STACK_SIZE=8000
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=y
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL=y
 CONFIG_ESP_TLS_PSK_VERIFICATION=y
+
+# Enable debug logs
+# CONFIG_LOG_MAXIMUM_LEVEL=4

mqtt_example/src/battery.rs

@@ -97,6 +97,8 @@ mod capacity_curve {
     }
 }
 
+/// Spawns a thread, that periodically reads battery voltage using ADC,
+/// transforms it into battery level and sends it to mpsc channel.
 pub fn spawn_reader_thread<'scope, T>(
     scope: &'scope Scope<'scope, '_>,
     adc: impl Peripheral<P = T::Adc> + 'scope + Send,

mqtt_example/src/controls.rs

@@ -34,6 +34,8 @@ impl<'controls, SELECT: InputPin, ENTER: InputPin> Controls<'controls, SELECT, E
         })
     }
 
+    /// Spawns a thread that reads key presses,
+    /// transforms them into `DeviceEvent`s and sends to mpsc channel.
     pub fn spawn_thread<'scope>(
         mut self,
         scope: &'scope Scope<'scope, '_>,
@@ -50,6 +52,12 @@ impl<'controls, SELECT: InputPin, ENTER: InputPin> Controls<'controls, SELECT, E
                 let notifier_enter = notification.notifier();
 
                 // Usage of interrupts is currently unsafe.
+                // We have to make sure, notifiers don't outlive the current task (thread).
+                //
+                // We are using notifiers instead of mpsc directly,
+                // as the callback closure inside `subscribe`
+                // is moved into ISR (Interrupt Service Routine),
+                // and the list of allowed APIs there is heavily restricted.
                 unsafe {
                     self.btn_select
                         .subscribe(move || {
@@ -63,6 +71,8 @@ impl<'controls, SELECT: InputPin, ENTER: InputPin> Controls<'controls, SELECT, E
                         .unwrap();
                 }
                 loop {
+                    // We have to re-enable interrupts each time,
+                    // as they are automatically disabled when interrupt happens.
                     self.enable_interrupts().unwrap();
                     let btn_num = notification.wait(delay::BLOCK).unwrap().get();
                     match btn_num {

mqtt_example/src/mqtt.rs

@@ -14,6 +14,7 @@ pub fn configure() -> anyhow::Result<(EspMqttClient<'static>, EspMqttConnection)
     let mqtt_config = MqttClientConfiguration {
         username: Some(MQTT_USER),
         password: Some(MQTT_PASSWORD),
+        // Enable MQTTS (MQTT with TLS)
         crt_bundle_attach: Some(esp_crt_bundle_attach),
         keep_alive_interval: Some(Duration::from_secs(10)),
         reconnect_timeout: Some(Duration::from_secs(10)),
@@ -26,6 +27,7 @@ pub fn configure() -> anyhow::Result<(EspMqttClient<'static>, EspMqttConnection)
     Ok((mqtt_client, mqtt_connection))
 }
 
+/// Spawns a thread, that receives mqtt messages, parses them and sends to mpsc channel.
 pub fn spawn_receiver_thread<'scope>(
     scope: &'scope Scope<'scope, '_>,
     mut mqtt_connection: EspMqttConnection,
@@ -55,6 +57,7 @@ pub fn spawn_receiver_thread<'scope>(
         })
 }
 
+/// Retries subscribing to topic until mqtt connection is established and subscription succeeds.
 pub fn try_until_subscribed(mqtt_client: &mut EspMqttClient, topic: &str) {
     loop {
         if let Err(_e) = mqtt_client.subscribe(topic, QoS::ExactlyOnce) {