it's fine if sd doesn't sd (#52)

MIDAS/docs/Doxyfile

@@ -1038,7 +1038,7 @@ FILE_PATTERNS          = *.c \
 # be searched for input files as well.
 # The default value is: NO.
 
-RECURSIVE              = NO
+RECURSIVE              = YES
 
 # The EXCLUDE tag can be used to specify files and/or directories that should be
 # excluded from the INPUT source files. This way you can easily exclude a
@@ -1431,15 +1431,15 @@ HTML_COLORSTYLE        = DARK
 # Minimum value: 0, maximum value: 359, default value: 220.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_HUE    = 305
+HTML_COLORSTYLE_HUE    = 216
 
 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors
 # in the HTML output. For a value of 0 the output will use gray-scales only. A
 # value of 255 will produce the most vivid colors.
 # Minimum value: 0, maximum value: 255, default value: 100.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_SAT    = 255
+HTML_COLORSTYLE_SAT    = 98
 
 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the
 # luminance component of the colors in the HTML output. Values below 100
@@ -1450,7 +1450,7 @@ HTML_COLORSTYLE_SAT    = 255
 # Minimum value: 40, maximum value: 240, default value: 80.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_GAMMA  = 80
+HTML_COLORSTYLE_GAMMA  = 52
 
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that

MIDAS/src/hal.h

@@ -13,51 +13,56 @@
 #include "Queue.h"
 
 /**
- *  The size of a thread stack, in bytes.
+ * The size of a thread stack, in bytes.
  */
 #define STACK_SIZE 8192
 
 /**
- * The two cores we have: 
- * SENSOR_CORE will hold all of the sensor tasks writing to the struct
- * DATA_CORE will have all of the tasks reading from the struct for data logging, along with GPS
-*/
+ * The ESP32 has two physical cores, which will each be dedicated to one group of threads.
+ * The SENSOR_CORE runs the threads which write to the sensor_data struct (mostly sensor polling threads).
+ */
 #define SENSOR_CORE ((BaseType_t) 0)
+
+/**
+ * The ESP32 has two physical cores, which will each be dedicated to one group of threads.
+ * The DATA_CORE runs the GPS thread, as well as the threads which read from the sensor_data struct (e.g. SD logging).
+ */
 #define DATA_CORE ((BaseType_t) 1)
 
 /**
- * Macro for declaring the functionality of a thread.
+ * Macro for declaring a thread. Creates a function with the name suffixed with `_thread`, annotated with [[noreturn]].
  *
  * @param name The name of the task.
  * @param param The single parameter to input into the thread.
  */
 #define DECLARE_THREAD(name, param) [[noreturn]] void name##_thread(param)
 
 /**
- * Macro for creating the thread itself. This is a statement and has no return value.
+ * Macro for creating and starting a thread declared with `DECLARE_THREAD`. This is a statement and has no return value.
  * Never put this in a scope that will end before the thread should.
  *
- * @param name name of the thread
- * @param core core for the task to be pinned to
- * @param arg config arguments for the task to take in
+ * @param name Name of the thread.
+ * @param core Core for the task to be pinned to, either `SENSOR_CORE` or `DATA_CORE`.
+ * @param arg Argument passed in to the `param` argument of `DECLARE_THREAD`.
+ * @param prio Priority of the thread.
  */
 #define START_THREAD(name, core, arg, prio) StaticTask_t name##_task;                \
                                       static unsigned char name##_stack[STACK_SIZE];            \
                                       xTaskCreateStaticPinnedToCore(((TaskFunction_t) name##_thread), #name, STACK_SIZE, arg, tskIDLE_PRIORITY + prio, name##_stack, &name##_task, core)
-/**
+/*
  * Parameters for xTaskCreateStaticPinnedToCore are as follows in parameter order:
- * Function to be run by the thread, this contains a `while(true)` loop
- * Name of thread
- * Size of the stack for each thread in words (1 word = 4 bytes)
- * Arguments to be passed into the function, this will generally eb the config file
- * Priority of the task, in allmost all cases, this will be the idle priority plus one
- * The actual stack memory to use
- * A handle to reference the task with
- * The core to pin the task to
+ *  - Function to be run by the thread, this contains a `while(true)` loop
+ *  - Name of thread
+ *  - Size of the stack for each thread in words (1 word = 4 bytes)
+ *  - Arguments to be passed into the function, this will generally eb the config file
+ *  - Priority of the task, in allmost all cases, this will be the idle priority plus one
+ *  - The actual stack memory to use
+ *  - A handle to reference the task with
+ *  - The core to pin the task to
  */
 
 /**
- * delays a task for a certain amount of time in milliseconds
- * @param millis the time to delay in milliseconds
+ * @brief Delays the running thread.
+ * @param millis The time to delay in milliseconds.
 */
 #define THREAD_SLEEP(millis) vTaskDelay(pdMS_TO_TICKS(millis))

MIDAS/src/hardware/GPSSensor.cpp

@@ -1,26 +1,28 @@
-#include "sensors.h"
-#include "pins.h"
+#include <Wire.h>
+
 #include "MicroNMEA.h"
 #include "teseo_liv3f_class.h"
+
+#include "pins.h"
+#include "sensors.h"
 #include "sensor_data.h"
-#include <Wire.h>
 
-TeseoLIV3F teseo(&Wire, GPS_RESET, GPS_ENABLE);     //singleton for the teseo gps
+TeseoLIV3F teseo(&Wire, GPS_RESET, GPS_ENABLE);     // singleton for the teseo gps
 
 /**
  * @brief Initializes GPS, returns NoError
  * 
  * @return Error code
-*/
+ */
 ErrorCode GPSSensor::init() {
-    teseo.init();       //function always returns ok for some reason
+    teseo.init();       // always returns ok for some reason
 
     return ErrorCode::NoError;
 }
 
 
-// This is needed because GPS doesn't provide unix time and just gives
-// dd mm yy
+// This is needed because GPS doesn't provide unix time and just gives dd mm yy
+// 'needed' is a strong word
 const uint16_t months[12] = {
     0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334
 };
@@ -34,7 +36,7 @@ inline bool is_leapyear(int year) {
  * @brief Reads the GPS data from the sensor (lat, long, altitude, sat count, etc)
  * 
  * @return GPS data packet
-*/
+ */
 GPS GPSSensor::read() {
     teseo.update();
     GPGGA_Info_t gpgga_message = teseo.getGPGGAData();

MIDAS/src/hardware/Magnetometer.cpp

@@ -1,36 +1,27 @@
-#include "sensors.h"
 #include <Adafruit_LIS3MDL.h>
+
+#include "sensors.h"
 #include "hal.h"
 
 Adafruit_LIS3MDL LIS3MDL;           // global static instance of the sensor
 
-/**
- * @brief Initializes the magnetometer sensor
- * 
- * @return Error Code
-*/
 ErrorCode MagnetometerSensor::init() {
-    if (!LIS3MDL.begin_SPI(LIS3MDL_CS)) { //Checks if sensor is connected
+    if (!LIS3MDL.begin_SPI(LIS3MDL_CS)) {                     // Checks if sensor is connected
         return ErrorCode::MagnetometerCouldNotBeInitialized;
     }
-    LIS3MDL.setOperationMode(LIS3MDL_CONTINUOUSMODE);//reading continously
-    LIS3MDL.setDataRate(LIS3MDL_DATARATE_155_HZ);//sets datarate to 155hz
-    LIS3MDL.setRange(LIS3MDL_RANGE_4_GAUSS);//earth is 1/2 gauss, can detect high current
+    LIS3MDL.setOperationMode(LIS3MDL_CONTINUOUSMODE);         // Reading continuously, instead of single-shot or off
+    LIS3MDL.setDataRate(LIS3MDL_DATARATE_155_HZ);
+    LIS3MDL.setRange(LIS3MDL_RANGE_4_GAUSS);                  // Earth's magnetic field is 1/2 gauss, can detect high current
     return ErrorCode::NoError;
 }
 
-/**
- * @brief Reads and returns the data from the sensor
- * 
- * @return a magnetometer packet with current flux in all three axes
-*/
 Magnetometer MagnetometerSensor::read() {
     // read from aforementioned global instance of sensor
     LIS3MDL.read();
 
     float mx = LIS3MDL.x_gauss;
     float my = LIS3MDL.y_gauss;
     float mz = LIS3MDL.z_gauss;
-    Magnetometer reading {mx, my, mz};
+    Magnetometer reading{mx, my, mz};
     return reading;
 }

MIDAS/src/hardware/Pyro.cpp

@@ -5,69 +5,65 @@
 
 #include "TCAL9539.h"
 
-#define MAXIMUM_TILT_ANGLE (M_PI/9) // 20 degrees
+#define MAXIMUM_TILT_ANGLE (M_PI/9)    // 20 degrees
 
 /**
- * @brief Helper function: Determines if the orientation is within an acceptable range to fire the second stage igniter.
- * 
- * @return Boolean indication no error if true, error if false
-*/
-bool gpio_error_to_fail_flag(GpioError error_code) {
+ * @brief Returns true if the error_code signals failure.
+ */
+bool error_is_failure(GpioError error_code) {
     return error_code != GpioError::NoError;
 }
 
 /**
- * @brief Determines if orientation is in an acceptable range to fire second stage
+ * @brief Determines if orientation is in an acceptable range to ignite second stage.
  * 
- * @return boolean indicating an acceptable range, true if acceptable, false if not
-*/
+ * @return True if acceptable, false if not.
+ */
 bool can_fire_igniter(Orientation orientation) {
     // This needs to be fleshed out. The sensor may not report angles in 'world space', so we need to determine
     // if the orientation of the rocket depends on other angles
 //    return std::abs(orientation.pitch) < MAXIMUM_TILT_ANGLE && std::abs(orientation.yaw) < MAXIMUM_TILT_ANGLE;
+    (void) orientation;
     return true;
 }
 
 
 /**
- * @brief "Initializes" the pyro thread. The main initialization will be done by the GPIO expander, so the pyro thread doesn't have to do anything special.
- * 
- * @return Error code
-*/
+ * @brief Initializes the pyro thread. The main initialization will be done by the GPIO expander, so the pyro thread doesn't
+ *        have to do anything special and will always return NoError.
+ */
 ErrorCode Pyro::init() {
     bool has_failed_gpio_init = false;
 
     // global arm
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYRO_GLOBAL_ARM_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYRO_GLOBAL_ARM_PIN, OUTPUT));
 
     // arm pins
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROA_ARM_PIN, OUTPUT));
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROB_ARM_PIN, OUTPUT));
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROC_ARM_PIN, OUTPUT));
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROD_ARM_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROA_ARM_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROB_ARM_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROC_ARM_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROD_ARM_PIN, OUTPUT));
 
     // fire pins
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROA_FIRE_PIN, OUTPUT));
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROB_FIRE_PIN, OUTPUT));
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROC_FIRE_PIN, OUTPUT));
-    has_failed_gpio_init |= gpio_error_to_fail_flag(gpioPinMode(PYROD_FIRE_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROA_FIRE_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROB_FIRE_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROC_FIRE_PIN, OUTPUT));
+    has_failed_gpio_init |= error_is_failure(gpioPinMode(PYROD_FIRE_PIN, OUTPUT));
 
 //    if (has_failed_gpio_init) {
 //        return ErrorCode::PyroGPIOCouldNotBeInitialized;
 //    } else {
-    return ErrorCode::NoError;
+    return ErrorCode::NoError;   // GPIO Driver always claimes it errored even when it doesn't.
 //    }
 }
 
 #ifdef IS_SUSTAINER
 
 /**
- * Upper stage only!
+ * @brief Upper stage only! Fires channels by setting their pin on the GPIO.
  * 
- * @brief Fires channels by setting their pin on the GPIO.
- * 
- * @return A new pyro struct, with data depending on whether or not each pyro channel should be firing.
-*/
+ * @return A pyro struct indicating which pyro channels are armed and/or firing.
+ */
 PyroState Pyro::tick(FSMState fsm_state, Orientation orientation) {
     PyroState new_pyro_state = PyroState();
 

MIDAS/src/hardware/sensors.h

@@ -6,63 +6,63 @@
 
 /**
  * @struct LowG interface
-*/
+ */
 struct LowGSensor {
     ErrorCode init();
     LowGData read();
 };
 
 /**
  * @struct HighG interface
-*/
+ */
 struct HighGSensor {
     ErrorCode init();
     HighGData read();
 };
 
 /**
  * @struct Magnetometer interface
-*/
+ */
 struct MagnetometerSensor {
     ErrorCode init();
     Magnetometer read();
 };
 
 /**
  * @struct Barometer interface
-*/
+ */
 struct BarometerSensor {
     ErrorCode init();
     Barometer read();
 };
 
 /**
  * @struct LowGLSM interface
-*/
+ */
 struct LowGLSMSensor {
     ErrorCode init();
     LowGLSM read();
 };
 
 /**
  * @struct Continuity interface
-*/
+ */
 struct ContinuitySensor {
     ErrorCode init();
     Continuity read();
 };
 
 /**
  * @struct Voltage interface
-*/
+ */
 struct VoltageSensor {
     ErrorCode init();
     Voltage read();
 };
 
 /**
  * @struct BNO interface
-*/
+ */
 struct OrientationSensor {
     Orientation initial_orientation;
     uint8_t initial_flag;
@@ -72,7 +72,7 @@ struct OrientationSensor {
 
 /**
  * @struct GPS interface
-*/
+ */
 struct GPSSensor {
     ErrorCode init();
     GPS read();
@@ -81,7 +81,7 @@ struct GPSSensor {
 
 /**
  * @struct Pyro interface
-*/
+ */
 struct Pyro {
     ErrorCode init();
     PyroState tick(FSMState fsm_state, Orientation orientation);