Merge branch 'main' into 83-docs-conio-documentation

CHANGELOG.md

@@ -1,3 +1,10 @@
+## [3.3.2](https://github.com/UCSD-E4E/smartfin-fw3/compare/v3.3.1...v3.3.2) (2024-11-12)
+
+
+### Bug Fixes
+
+* fields inside menu_ documented. revert unintended changes ([fd3ef27](https://github.com/UCSD-E4E/smartfin-fw3/commit/fd3ef27c16882a7c122ad6b22777aba013098a8a))
+
 ## [3.3.1](https://github.com/UCSD-E4E/smartfin-fw3/compare/v3.3.0...v3.3.1) (2024-11-07)
 
 

src/chargeTask.hpp

@@ -26,13 +26,32 @@ class ChargeTask : public Task{
     void init(void);
     /**
      * @brief Charges the device, and exits to CLI on command
-    */
+     * 
+     * @return STATE_CLI when CLI pattern entered or
+     * STATE_DEEP_SLEEP when device not charging
+     */
     STATES_e run(void);
     void exit(void);
 
     private:
+    /**
+     * @brief Buffer for storing command-line input
+     * 
+     * Character array holds input from CLI with a maxiumum size of 'CLI_BUFFER_LEN'
+    */
     char inputBuffer[CLI_BUFFER_LEN];
+    /**
+     * @brief LED status indicator for charging task
+     *
+     * Object defines visual status of device's charging state
+     */
     LEDStatus ledStatus;
+    /**
+     * @brief Timestamp for tracking start of charging process
+     * 
+     * startTime = 0 indicates the device charging since
+     * the powering on of the device
+     */
     system_tick_t startTime;
 };
 #endif

src/fileCLI/fileCLI.hpp

@@ -93,9 +93,21 @@ class FileCLI{
     DIR* dir_stack[FILE_CLI_MAX_DIR_DEPTH];
     char path_stack[FILE_CLI_MAX_DIR_DEPTH][NAME_MAX];
     int current_dir;
+
+    /**
+     * @brief Structure representing a command menu entry for FileCLI.
+     *
+     */
     typedef struct menu_
     {
+        /**
+         * A character representing a user command. Will trigger a specific function.
+         */
         const char cmd;
+        /**
+         * A pointer to a place in flash memory or RAM where a function with properties is held.
+         * Executes the command associated with cmd.
+         */
         void (FileCLI::*fn)(void);
     } menu_t;
     static menu_t fsExplorerMenu[];

src/sleepTask.hpp

@@ -15,13 +15,34 @@ class SleepTask : public Task {
     STATES_e run(void);
     void exit(void);
 
+    /**
+     * @brief Defines possible boot behaviors
+     */
     typedef enum BOOT_BEHAVIOR_
     {
+        /**
+         * @brief Standard boot behavior
+         */
         BOOT_BEHAVIOR_NORMAL=0,
+        /**
+         * @brief Initiate temperature calibration on startup
+         */
         BOOT_BEHAVIOR_TMP_CAL_START=1,
+        /**
+         * @brief Continue temperature calibration sequence
+         */
         BOOT_BEHAVIOR_TMP_CAL_CONTINUE=2,
+        /**
+         * @brief End temperature calibration
+         */
         BOOT_BEHAVIOR_TMP_CAL_END=3,
+        /**
+         * @brief Reattempts data upload
+         */
         BOOT_BEHAVIOR_UPLOAD_REATTEMPT=4,
+        /**
+         * @brief Boot behavior is not specified
+         */
         BOOT_BEHAVIOR_NOT_SET=255
     } BOOT_BEHAVIOR_e;
 
@@ -36,18 +57,28 @@ class SleepTask : public Task {
     static const char* strBootBehavior(BOOT_BEHAVIOR_e behavior);
     /**
      * @brief Updates boot behavior to NVRAM
-    */
-    static void setBootBehavior(BOOT_BEHAVIOR_e);
+     * 
+     * @param behavior Boot Behavior to set
+     */
+    static void setBootBehavior(BOOT_BEHAVIOR_e behavior);
     /**
      * @brief Get's current boot behavior from NVRAM
-    */
+     * 
+     * @return Current Boot Behavior
+     */
     static BOOT_BEHAVIOR_e getBootBehavior(void);
     /**
      * @brief Load boot behavior onto board
-    */
+     */
     static void loadBootBehavior(void);
     private:
+    /**
+     * @brief Stores current Boot Behavior
+     */
     static BOOT_BEHAVIOR_e bootBehavior;
+    /**
+     * @brief Manages LED status display settings
+     */
     LEDStatus ledStatus;
 };
 #endif

src/vers.hpp

@@ -12,7 +12,7 @@
 
 #define FW_MAJOR_VERSION    3
 #define FW_MINOR_VERSION    3
-#define FW_BUILD_NUM        1
+#define FW_BUILD_NUM        2
 #define FW_BRANCH           ""
 
 #if PRODUCT_VERSION_USE_HEX == 1

src/watersensor/waterSensor.hpp

@@ -24,27 +24,61 @@
 #define WATER_SENSOR_HIGH_STATE 1
 #define WATER_SENSOR_LOW_STATE 0
 
+/**
+ * @brief Represents a sensor that detects water presence using a moving window of samples
+ */
 class WaterSensor
 {
 private:
-    // which pin is the water sensor on?
+    /**
+     * @brief Pin that enables the water detection sensor
+     */
     uint8_t water_detect_en_pin;
+    /**
+     * @brief Pin that reads the water detection status
+     */
     uint8_t water_detect_pin;
-    // how many samples to look at for the moving window
+    /**
+     * @brief Size of the moving sample window used for water detection
+     */
     uint8_t moving_window_size;
+    /**
+     * @brief Minimum percentage of high state readings to trigger a change to "out of water"
+     */
     uint8_t low_detect_percentage = DEFAULT_WATER_SENSOR_LOW_PERCENTAGE;
+    /**
+     * @brief Minimum percentage of high state readings to trigger a change to "in water"
+     */
     uint8_t high_detect_percentage = DEFAULT_WATER_SENSOR_HIGH_PERCENTAGE;
-    // how many samples have been taken since a reset (signally a valid measurement)
+    /**
+     * @brief Number of samples taken since the last reset
+     */
     uint8_t samples_taken_since_reset = 0;
-    // sum of the array, initially set to zero.
+    /**
+     * @brief Sum of the current samples in the window
+     */
     uint8_t array_sum = 0;
-    // current location in the array
+    /**
+     * @brief Current position in the array of samples
+     */
     uint8_t array_location = 0;
-    // the last water reading, for hystersis, starting with "out of the water"
+    /**
+     * @brief Previous water detection status used for hystersis
+     */
     uint8_t last_water_detect = 0;
 
 public:
+    /**
+     * @brief Initializes the WaterSensor with specific pins and window size
+     *
+     * @param water_detect_en_pin Pin that enables the water sensor
+     * @param water_detect_pin_to_set Pin that reads the sensor value
+     * @param window_size Size of the moving sample window used for water detection
+     */
     WaterSensor(uint8_t water_detect_en_pin, uint8_t water_detect_pin_to_set, uint8_t window_size);
+    /**
+     * @brief Destroys the WaterSensor instance
+     */
     ~WaterSensor();
 
     // resets the array to zero