Comments final (#51)

* commented fsm and half of hardware folder

* some comments

* final comments

* fixed spelling errors

* updated kalman filter

* updated readme

* forgor commas

* forgor colon

* fucked up dash

---------

Co-authored-by: Aidan Costello <[email protected]>
Co-authored-by: aidancostello <[email protected]>

MIDAS/src/Buffer.h

@@ -3,11 +3,24 @@
 #include <cstdlib>
 #include <array>
 
+/**
+ * @class Buffer
+ * 
+ * @brief Templeted buffer to quickly calculate averages and derivatives for the FSM
+ * 
+ * @tparam T type of data to hold in the buffer
+ * @tparam BUFFER_SIZE size of the buffer
+*/
 template<typename T, size_t BUFFER_SIZE>
 struct Buffer {
 public:
     Buffer() = default;
 
+    /**
+     * @brief Append data to the end of the circular buffer
+     * 
+     * @param element Element to add to thebuffer
+    */
     void push(T const& element) {
         buffer[tail_idx] = element;
         tail_idx++;
@@ -20,6 +33,13 @@ struct Buffer {
 
     }
 
+    /**
+     * @brief Reads newest value into the buffer
+     * 
+     * @param item reference in which to store the most recent reading
+     * 
+     * @return boolean indicating a successful read
+    */
     bool read(T& item) {
         if (count == 0) {
             return false;
@@ -28,6 +48,13 @@ struct Buffer {
         return true;
     }
 
+   /**
+     * @brief Reads oldest value into the buffer
+     * 
+     * @param item reference in which to store the oldest reading
+     * 
+     * @return boolean indicating a successful read
+    */
     bool read_oldest(T&item) {
         if (count == 0) {
             return false;
@@ -53,6 +80,11 @@ struct Buffer {
 
 
 private:
+    /**
+     * @brief gets oldest index in the circular buffer
+     * 
+     * @return the oldest indext in the buffer
+    */
     size_t oldest_idx() {
         if (tail_idx < count) {
             return tail_idx + BUFFER_SIZE - count;
@@ -61,6 +93,11 @@ struct Buffer {
         }
     }
 
+    /**
+     * @brief gets newest index in the circular buffer
+     * 
+     * @return the newest index in the buffer
+    */
     size_t newest_idx() {
         if (tail_idx == 0) {
             return BUFFER_SIZE - 1;

MIDAS/src/Mutex.h

@@ -10,7 +10,7 @@
 
 
 /**
- * A mutex which holds a single value.
+ * @brief A mutex which holds a single value.
  *
  * @tparam T The type of the value to hold. Should have copy semantics.
  */
@@ -45,7 +45,7 @@ struct Mutex {
     }
 
     /**
-     * Read the current value in the mutex (will spin until it acquires the lock).
+     * @brief Read the current value in the mutex (will spin until it acquires the lock).
      *
      * @return The value in the mutex.
      */
@@ -61,11 +61,20 @@ struct Mutex {
         return ret;
     }
 
+    /**
+     * @brief Read the current value in the mutex, will not acquire lock
+     *
+     * @return The value in the mutex.
+     */
     T read_unsync() {
         return data;
     }
 
-
+    /**
+     * @brief reads value in mutex, will acquire lock
+     * 
+     * @param ptr buffer to store data in
+    */
     void read2(T* ptr) {
         if (!mutex_handle || mutex_handle != check) {
             Serial.println("Aw shucks");
@@ -78,7 +87,7 @@ struct Mutex {
     }
 
     /**
-     * Update the value in the mutex (will spin until it acquires the lock).
+     * @brief Update the value in the mutex (will spin until it acquires the lock).
      *
      * @param value What to update the mutex to.
      */

MIDAS/src/Queue.h

@@ -9,12 +9,12 @@
 #endif
 
 /**
- * The default maximum length for a Queue.
+ * @brief The default maximum length for a Queue.
  */
 #define QUEUE_LENGTH 128
 
 /**
- * A Thread-safe Queue containing a single data type.
+ * @brief A Thread-safe Queue containing a single data type.
  *
  * @tparam T The data type stored in the queue.
  * @tparam length The maximum length of the queue. Defaults to QUEUE_LENGTH.
@@ -37,7 +37,7 @@ class Queue {
     Queue(Queue&&) = delete;
 
     /**
-     * Put a value in the queue. If the queue is full or timed out, do nothing.
+     * @brief Put a value in the queue. If the queue is full or timed out, do nothing.
      *
      * @param value The value to put in the queue.
      */
@@ -49,7 +49,7 @@ class Queue {
     }
 
     /**
-     * Fetch a value from the queue.
+     * @brief Fetch a value from the queue.
      *
      * @param out Where to put the value from the queue. It is undefined if there is no value in the queue, or if the queue timed out.
      * @return True if there was a value in the queue that was read into `out`, false otherwise.

MIDAS/src/buzzer.cpp

@@ -3,17 +3,29 @@
 #define BUZZER_PIN (48)
 #define BUZZER_CHANNEL (1)
 
+/**
+ * @brief starts playing a new song
+ * 
+ * @param tune Song to be played
+ * @param length Length of song to be played
+*/
 void BuzzerController::play_tune(Sound* tune, uint32_t length) {
     current_tune_ = tune;
     index_ = 0;
     length_ = length;
     new_tune_started = true;
 }
 
+/**
+ * @brief public interface to tick the buzzer
+*/
 void BuzzerController::tick() {
     tick_sounds();
 }
 
+/**
+ * @brief ticks the bizzer, plays next note/ starts new song if applicable
+*/
 void BuzzerController::tick_sounds() {
     if (current_tune_ == nullptr) {
         return;
@@ -46,6 +58,11 @@ void BuzzerController::tick_sounds() {
     }
 }
 
+/**
+ * @brief Initializes buzzer
+ * 
+ * @return Error code
+*/
 ErrorCode BuzzerController::init() {
     // ledcDetachPin(BUZZER_PIN);  // this probably isn't necessary but who am I do question the knowledge of github
     pinMode(BUZZER_PIN, OUTPUT);
@@ -54,6 +71,9 @@ ErrorCode BuzzerController::init() {
     return NoError;
 }
 
+/**
+ * @brief notes to use for creating a song, along with a tempo
+*/
 #define MS_PER_4BEAT 6000
 
 #define rest Sound{0, 10}
@@ -72,6 +92,9 @@ ErrorCode BuzzerController::init() {
 #define d4_2fifth Sound{294, static_cast<uint8_t>(0.1 * MS_PER_4BEAT)}
 #define f_nat_4_2fifth Sound{350, static_cast<uint8_t>(0.1 * MS_PER_4BEAT)}
 
+/**
+ * @brief free bird solo song, to be played on startup/ second stage iginition
+*/
 Sound free_bird[FREE_BIRD_LENGTH] = {/*measure 1*/ d4_eight, g4_eight, d4_eight,
     /*measure 2*/ f_nat_4_eight, g4_eight, f_nat_4_quart, rest, f_nat_4_quart, rest, f_nat_4_eight, d4_eight
 };

MIDAS/src/buzzer.h

@@ -4,13 +4,22 @@
 #include "hal.h"
 #include "errors.h"
 
-
+/**
+ * @struct Sound
+ * 
+ * @brief contains information for a single note to play on the buzzer
+*/
 struct Sound {
 public:
     uint32_t frequency;
     uint8_t duration_ms;
 };
 
+/**
+ * @struct BuzzerController
+ * 
+ * @brief wraps the buzzer functionality
+*/
 struct BuzzerController {
 private:
     Sound* current_tune_ = nullptr;

MIDAS/src/data_logging.cpp

@@ -2,9 +2,15 @@
 #include "log_format.h"
 #include "log_checksum.h"
 
+/**
+ * @brief Forward decleration of the ID recieving function
+*/
 template<typename T>
 constexpr ReadingDiscriminant get_discriminant();
 
+/**
+ * @brief macro to associate a certain sensor with a specific number ID
+*/
 #define ASSOCIATE(ty, id) template<> constexpr ReadingDiscriminant get_discriminant<ty>() { return ReadingDiscriminant::id; }
 
 ASSOCIATE(LowGData, ID_LOWG)
@@ -20,7 +26,12 @@ ASSOCIATE(FSMState, ID_FSM)
 ASSOCIATE(KalmanData, ID_KALMAN)
 ASSOCIATE(PyroState, ID_PYRO)
 
-
+/**
+ * @brief writes a reading, with its ID, timestamp, and data to a specific sink
+ * 
+ * @param sink the LogSink to write to
+ * @param reading the data to read
+*/
 template<typename T>
 void log_reading(LogSink& sink, Reading<T>& reading) {
     ReadingDiscriminant discriminant = get_discriminant<T>();
@@ -29,6 +40,14 @@ void log_reading(LogSink& sink, Reading<T>& reading) {
     sink.write((uint8_t*) &reading.data, sizeof(T));
 }
 
+/**
+ * @brief writes a SensorData's entire queue reading to a sink
+ * 
+ * @param sink the LogSink to write to
+ * @param sensor_data the sensor data, with queue, to write from
+ * 
+ * @return the number of packets written to the LogSink
+*/
 template<typename T>
 uint32_t log_from_sensor_data(LogSink& sink, SensorData<T>& sensor_data) {
     Reading<T> reading;
@@ -40,11 +59,22 @@ uint32_t log_from_sensor_data(LogSink& sink, SensorData<T>& sensor_data) {
     return read;
 }
 
+/**
+ * @brief Initializes a specific LogSink
+ * 
+ * @param sink the LogSink to initialize
+*/
 void log_begin(LogSink& sink) {
     uint32_t checksum = LOG_CHECKSUM;
     sink.write((uint8_t*) &checksum, 4);
 }
 
+/**
+ * @brief logs all sensor data from the rocket
+ * 
+ * @param sink the LogSink to write data to
+ * @param data the rocket which holds all the sensor data to write
+*/
 void log_data(LogSink& sink, RocketData& data) {
     log_from_sensor_data(sink, data.low_g);
     log_from_sensor_data(sink, data.low_g_lsm);
@@ -63,6 +93,15 @@ void log_data(LogSink& sink, RocketData& data) {
 #ifndef SILSIM
 #define MAX_FILES 999
 
+/**
+ * @brief names a new file for a log sink depending on the files currently on said LogSink
+ * 
+ * @param fileName buffer to write the file name to
+ * @param fileExtensionParam the file extension required for the file
+ * @param fs the FileSystem to check files off of
+ * 
+ * @return buffer contianing string of file name
+*/
 char* sdFileNamer(char* fileName, char* fileExtensionParam, FS& fs) {
     char fileExtension[strlen(fileExtensionParam) + 1];
     strcpy(fileExtension, fileExtensionParam);

MIDAS/src/data_logging.h

@@ -12,7 +12,9 @@
 #endif
 
 /**
- * Protocol for a sink, which is implemented as an SD card in hardware.
+ * @class LogSink
+ * 
+ * @brief Protocol for a sink, which is implemented as an SD card in hardware.
  */
 class LogSink {
 public:

MIDAS/src/errors.cpp

@@ -27,6 +27,11 @@
 #include <TCAL9539.h>
 #include "hardware/pins.h"
 
+/**
+ * @brief writes LEDS to indicate errors as described above
+ * 
+ * @param error Error Code to indicate
+*/
 void update_error_LED(ErrorCode error) {
     switch (error) {
         case LowGCouldNotBeInitialized:

MIDAS/src/errors.h

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @enum ErrorCode
+ * 
+ * @brief list of all error codes that can arise
+*/
 enum ErrorCode {
     NoError = 0,
     LowGCouldNotBeInitialized = 1,