Merge branch 'main' into ci/platform_mods

CHANGELOG.md

@@ -1,3 +1,28 @@
+# [3.4.0](https://github.com/UCSD-E4E/smartfin-fw3/compare/v3.3.3...v3.4.0) (2024-12-06)
+
+
+### Features
+
+* integrated water sensor into data collection ([19bee51](https://github.com/UCSD-E4E/smartfin-fw3/commit/19bee5190dec2b74050a940a6e61bb2def8d7ca2))
+* integrated water sensor into data collection ([#146](https://github.com/UCSD-E4E/smartfin-fw3/issues/146)) ([5e3ad08](https://github.com/UCSD-E4E/smartfin-fw3/commit/5e3ad08988300a0d64b60a0f7ca46c31b25a7497))
+
+## [3.3.3](https://github.com/UCSD-E4E/smartfin-fw3/compare/v3.3.2...v3.3.3) (2024-11-22)
+
+
+### Bug Fixes
+
+* Adds cstdarg include ([1ea0cc8](https://github.com/UCSD-E4E/smartfin-fw3/commit/1ea0cc8a4fb4795d1d6840bc629c41659805b8cc))
+* Adds cstdarg include ([#124](https://github.com/UCSD-E4E/smartfin-fw3/issues/124)) ([ffd41d7](https://github.com/UCSD-E4E/smartfin-fw3/commit/ffd41d7ec059ed799ddd2ff8d225641ae0b47a5c))
+* Switches to limits.h ([ee94566](https://github.com/UCSD-E4E/smartfin-fw3/commit/ee945662148bf821dabdfe3fc71311e718f389c7))
+* Switches to limits.h ([#129](https://github.com/UCSD-E4E/smartfin-fw3/issues/129)) ([379bcae](https://github.com/UCSD-E4E/smartfin-fw3/commit/379bcae1a4cb84f044ee2d4f2685df5f4ec72817))
+
+## [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/cellular/dataCollection.cpp

@@ -79,7 +79,7 @@ void SS_ensemble10Func()
         lng = pData->location[1];
     }
 
-    water = 0; // TODO - waiting on water sensor integration
+    water = pSystemDesc->pWaterSensor->getCurrentReading();
 
     // Accumulate measurements
     pData->temperature += temp;

src/cellular/dataUpload.hpp

@@ -36,17 +36,51 @@
  */
 #define DU_UPLOAD_MAX_REATTEMPTS    5
 
-
-class DataUpload : public Task{
-    public:
+/**
+ * @class DataUpload
+ * @brief Handles the data upload task.
+ *
+ * This class implements the task methods and internal states
+ * required for data uploading.
+ */
+class DataUpload : public Task
+{
+public:
+    /**
+     * @brief Initializes the data upload task.
+     */
     void init(void);
+
+    /**
+     * @brief Executes the data upload task logic.
+     *
+     * @return The next state after executing the task.
+     */
     STATES_e run(void);
+
+    /**
+     * @brief Cleans up resources and exits the task.
+     */
     void exit(void);
 
-    private:
+private:
+    //! Flag to indicate successful initialization.
     int initSuccess;
+    //! Tracks the last connection attempt time.
     system_tick_t lastConnectTime;
+
+    /**
+     * @brief State to transition to upon task exit.
+     *
+     * @return The exit state.
+     */
     STATES_e exitState(void);
+
+    /**
+     * @brief Checks if data can be uploaded.
+     *
+     * @return The current state indicating upload readiness.
+     */
     STATES_e can_upload(void);
 };
 #endif

src/cellular/ensembleTypes.hpp

@@ -26,6 +26,9 @@ typedef enum EnsembleID_
 }EnsembleID_e;
 
 #pragma pack(push, 1)
+/**
+ * @brief struct to contain header info for an ensemble
+ */
 typedef struct EnsembleHeader_
 {
     unsigned int ensembleType : 4;

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/cli/cliDebug.cpp

@@ -32,7 +32,9 @@
 
 #include "Particle.h"
 
-
+/**
+ * @brief Command line debugging menu
+ */
 const Menu_t CLI_debugMenu[] = 
 {
     {1, "Display Fault Log", &CLI_displayFLOG, MENU_CMD},

src/cli/conio.cpp

@@ -1,11 +1,10 @@
 /**
-* Project smartfin-fw3
-* @file conio.hpp
-* Description: Particle serial input and output for command line use
-* @author @emilybthorpe
-* @date Jul 20 2023
-*/
-
+ * Project smartfin-fw3
+ * @file conio.hpp
+ * Description: Particle serial input and output for command line use
+ * @author Emily B. Thorpe <[email protected]>
+ * @date Jul 20 2023
+ */
 
 #include "conio.hpp"
 

src/cli/conio.hpp

@@ -4,6 +4,10 @@
 #include <cstdarg>
 #include <stdint.h>
 
+/**
+ * @brief int length of character array SF_OSAL_printfBuffer
+ *
+ */
 #define SF_OSAL_PRINTF_BUFLEN   1536
 
 #ifdef __cplusplus
@@ -42,11 +46,12 @@ extern "C"
      * @brief Gets user input lin
      * @param buffer buffer to write too
      * @param buflen length of buffer
+     * @return length of the user input line
      */
     int SF_OSAL_getline(char *buffer, int buflen);
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif
+#endif

src/cli/menuItems/debugCommands.hpp

@@ -36,9 +36,8 @@ void CLI_testHasData(void);
  * @brief Delete all files
 */
 void CLI_wipeFileSystem(void);
-/*
- * @brief Monitors temperature sensor
- * 
+/**
+ * @brief Monitor temperature sensor
  */
 void CLI_monitorTempSensor(void);
 /**

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

@@ -11,8 +11,8 @@
 #include "product.hpp"
 
 #define FW_MAJOR_VERSION    3
-#define FW_MINOR_VERSION    3
-#define FW_BUILD_NUM        1
+#define FW_MINOR_VERSION    4
+#define FW_BUILD_NUM        0
 #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