From cbb7c5d4e3976492db64011454714fc364277d94 Mon Sep 17 00:00:00 2001
From: Christoph Hagen <github@christophhagen.de>
Date: Mon, 5 Jun 2023 17:51:48 +0200
Subject: [PATCH] Add some code comments

---
 src/main.cpp | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/main.cpp b/src/main.cpp
index cad8b4c..ba61048 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -7,7 +7,8 @@
 #include "storage.h"
 #include "temperature.h"
 
-Temperature samples[temperatureSensorCount];
+// The delay to perform when waiting idle (not sleeping) for next measurement 
+constexpr uint32_t delayWaitingForNextMeasurementMS = 50;
 
 // Indicate when the next temperature measurement should be performed
 // Time is measured in seconds since power-on via RTC clock
@@ -48,6 +49,12 @@ uint32_t secondsUntilNextTemperatureMeasurement() {
     return nextTimeToMeasureTemperatureSeconds - currentTime;
 }
 
+/**
+ * @brief Start sleep if next measurement is sufficiently in the future
+ * 
+ * If the measurement is less than one second in the future, don't do anything.
+ * If the device sleeps, then execution starts again in the `setup()` function.
+ */
 void deepSleepUntilNextTemperatureMeasurement() {
     uint32_t seconds = secondsUntilNextTemperatureMeasurement();
     if (seconds == 0) {
@@ -74,10 +81,23 @@ bool wakeupButtonIsPressed() {
     return gpio_get_level(wakeupButtonPin) == 0;
 }
 
+/**
+ * @brief Shift the timestamp into the future where the device is allowed to go to sleep.
+ * 
+ * Updates are performed when the wake button was pressed or a device is connected via bluetooth.
+ */
 void updateStayAwakeTime() {
     sleepStartAfterButtonPressOrConnection = time(NULL) + wakeupDurationAfterButtonPress;
 }
 
+/**
+ * @brief Check if the device should go to sleep
+ * 
+ * Sleeping is allowed if no bluetooth connection exists, or if the last wake button press
+ * was far enough in the past.
+ * @return true Allow the device to go to deep sleep
+ * @return false Keep the device awake
+ */
 bool shouldGoToSleep() {
     if (bluetoothIsConnected()) {
         return false;
@@ -102,7 +122,8 @@ void enableLED() {
 }
 
 void setup() {
-    Serial.begin(serialBaudRate);    
+    // No need for serial output in production
+    //Serial.begin(serialBaudRate);    
     
     // LED useless inside case
     //enableLED();
@@ -134,6 +155,8 @@ void setup() {
 void loop() {
     if (shouldMeasureTemperature()) {
         Serial.println("Measuring");
+
+        Temperature samples[temperatureSensorCount];
         temperaturePerformUpdate(samples);
         saveTemperatures(samples);
         setNextTemperatureMeasurementInterval();
@@ -149,5 +172,5 @@ void loop() {
         // Otherwise control flow starts with setup() again
         deepSleepUntilNextTemperatureMeasurement();
     }
-    delay(50);
+    delay(delayWaitingForNextMeasurementMS);
 }
\ No newline at end of file