Docs M2

Apps/Inc/ReadCarCAN.h

@@ -1,8 +1,11 @@
 /**
  * @file ReadCarCAN.h
- * @brief The Read Car CAN task reads the car’s CANBus for values 
- * relevant to Controls. Currently we parse four types of messages: 
- * BPS trip, BPS contactor state, Supplemental Voltage, and State of Charge.
+ * @brief Reads the car’s CAN bus for values relevant to Controls, and handles ignition sequence logic.
+ * 
+ * Call ChargeEnable_Get() to get whether regen braking / charging is enabled or not. Starting the task will
+ * spawn the watchdog, handle the ignition sequence logic in communication with BPS, and update the display with
+ * the State of Charge and the Supplemental Voltage of the car.
+ * 
  */
 
 #ifndef __READ_CAR_CAN_H
@@ -14,67 +17,41 @@
 #include "CANbus.h"
 
 /**
- * @def SAT_BUF_LENGTH
- * @brief Length of the array and motor PBC saturation buffers
+ * Length of the array and motor precharge-bypass contactor (PBC) saturation buffers
  */
 #define SAT_BUF_LENGTH 5 
 
 /**
- * @def ARRAY_SATURATION_THRESHOLD
- * @brief The Array Saturation Threshold is used to determine if Controls has 
- *          received a sufficient number of BPS's HV Array Enable Messages.
- *          BPS Array Saturation threshold is halfway between 0 and max saturation value.
+ * The Array Saturation Threshold is used to determine if Controls has 
+ * received a sufficient number of BPS's HV Array Enable Messages.
+ * BPS Array Saturation threshold is halfway between 0 and max saturation value.
  */
 #define ARRAY_SATURATION_THRESHOLD (((SAT_BUF_LENGTH + 1) * SAT_BUF_LENGTH) / 4) 
 
 /**
- * @def PLUS_MINUS_SATURATION_THRESHOLD
- * @brief The Plus-Minus Saturation Threshold is used to determine if Controls has
- *         received a sufficient number of BPS's HV Plus-Minus Enable Messages.
- *        BPS Plus-Minus Saturation threshold is halfway between 0 and max saturation value.
+ * The Plus-Minus Saturation Threshold is used to determine if Controls has
+ * received a sufficient number of BPS's HV Plus-Minus Enable Messages.
+ * BPS Plus-Minus Saturation threshold is halfway between 0 and max saturation value.
  */
 #define PLUS_MINUS_SATURATION_THRESHOLD (((SAT_BUF_LENGTH + 1) * SAT_BUF_LENGTH) / 4) 
 
 /**
- * @def CAN_WATCH_TMR_DLY_MS
- * @brief Delay time in milliseconds for the CAN Watchdog Timer
- */
-#define CAN_WATCH_TMR_DLY_MS 500u // 500 ms
-
-/**
- * @def CAN_WATCH_TMR_DLY_TMR_TS
- * @brief Delay time in timer ticks for the CAN Watchdog Timer
+ * Delay time in milliseconds for the CAN Watchdog Timer
  */
-#define CAN_WATCH_TMR_DLY_TMR_TS ((CAN_WATCH_TMR_DLY_MS * OS_CFG_TMR_TASK_RATE_HZ) / (1000u))
+#define CAN_WATCH_TMR_DLY_MS 500u
 
 /**
- * @def PRECHARGE_MOTOR_DELAY
- * @brief Delay time in milliseconds for the Motor Precharge.
+ * Delay time in milliseconds for the Motor Precharge.
  */
 #define PRECHARGE_MOTOR_DELAY 100u
 
 /**
- * @def MOTOR_CONTROLLER_PRECHARGE_BYPASS_DLY_TMR_TS
- * @brief Delay time in timer ticks for the Motor Precharge Bypass Timer
-*/
-#define MOTOR_CONTROLLER_PRECHARGE_BYPASS_DLY_TMR_TS ((PRECHARGE_MOTOR_DELAY * OS_CFG_TMR_TASK_RATE_HZ) / (1000u))
-
-/**
- * @def PRECHARGE_ARRAY_DELAY
- * @brief Delay time in milliseconds for the Array Precharge.
+ * Delay time in milliseconds for the Array Precharge.
  */
 #define PRECHARGE_ARRAY_DELAY 100u
 
 /**
- * @def ARRAY_PRECHARGE_BYPASS_DLY_TMR_TS
- * @brief Delay time in timer ticks for the Array Precharge Bypass Timer
- */
-#define ARRAY_PRECHARGE_BYPASS_DLY_TMR_TS ((PRECHARGE_ARRAY_DELAY * OS_CFG_TMR_TASK_RATE_HZ) / (1000u)) 
-
-/**
- * @enum ReadCarCAN_error_code_t
- * @brief Error codes for ReadCarCAN
- * 
+ * Error codes for ReadCarCAN
  */
 typedef enum {
     /** No error */
@@ -83,7 +60,7 @@ typedef enum {
 	READCARCAN_ERR_CHARGE_DISABLE,
 	/** Didn't receive a BPS charge msg in time **/
     READCARCAN_ERR_MISSED_MSG,
-    /** Ignition is turned to neither (off due to LV) or both at the same time (impossible) are on at  **/
+    /** Ignition is turned to neither (off due to LV) or both are on at the same time (impossible)  **/
 	READCARCAN_ERR_DISABLE_CONTACTORS_MSG,
 	/** Received a BPS trip msg (0 or 1) **/
     READCARCAN_ERR_BPS_TRIP

Apps/Inc/ReadTritium.h

@@ -1,8 +1,11 @@
 /** 
  * @file ReadTritium.h
- * @brief In its current iteration, the Read Tritium task facilitates all received
- * communication from MotorCAN. All messages are forwarded to CarCAN, and velocity and error
- * information are recorded.
+ * @brief Reads messages sent by the Tritium motor controller & handles conditional logic based on the message.
+ * 
+ * Call Motor_RPM_Get() to get the motor velocity in RPM. Call 
+ * Motor_Velocity_Get() to get the motor velocity in m/s. Starting the task will
+ * automatically forward all messages from MotorCAN to CarCAN, detect and handle motor errors,
+ * and forward velocity information to the display.
  * 
  */
 
@@ -14,35 +17,32 @@
 #include "Tasks.h"
 
 /**
- * @enum tritium_error_code_t
- * @brief Motor Error States
- * Read messages from motor in ReadTritium and trigger appropriate 
- * error messages as needed based on bits
+ * Motor Error States
 */
 typedef enum{
-    /** hardware over current error */
+    /** Hardware over current error */
     T_HARDWARE_OVER_CURRENT_ERR = (1<<0), 
-    /** software over current error */
+    /** Software over current error */
     T_SOFTWARE_OVER_CURRENT_ERR = (1<<1),
     /** DC bus over voltage error */
     T_DC_BUS_OVERVOLT_ERR = (1<<2),
-    /** hall sensor error */
+    /** Hall sensor error */
     T_HALL_SENSOR_ERR = (1<<3), 
-    /** watchdog last reset error */
-    T_WATCHDOG_LAST_RESET_ERR = 
-    /** config read error */(1<<4), 
+    /** Watchdog last reset error */
+    T_WATCHDOG_LAST_RESET_ERR = (1<<4), 
+    /** Config read error */
     T_CONFIG_READ_ERR = (1<<5), 
-    /** under voltage lockout error */
+    /** Under voltage lockout error */
     T_UNDER_VOLTAGE_LOCKOUT_ERR = (1<<6),
-    /** desaturation fault error */
+    /** Desaturation fault error */
     T_DESAT_FAULT_ERR = (1<<7), 
-    /** motor over speed error */
+    /** Motor over speed error */
     T_MOTOR_OVER_SPEED_ERR = (1<<8),
-    /** motor controller fails to restart or initialize */
+    /** Motor controller fails to restart or initialize */
     T_INIT_FAIL = (1<<9), 
-    /** motor watchdog trip */
+    /** Motor watchdog trip */
     T_MOTOR_WATCHDOG_TRIP = (1<<15),
-    /** no error */ 
+    /** No error */ 
     T_NONE = 0x00,
 } tritium_error_code_t;
 

Apps/Inc/SendCarCAN.h

@@ -1,9 +1,11 @@
 /**
  * @file SendCarCAN.h
- * @brief The Send Car CAN task is a simple queue consumer task. Multiple 
- * tasks that need to write the the car CAN bus; in order to do this safely, 
- * they append their messages to a CAN queue. The Send Car CAN task simply pends 
- * on this queue and forwards messages to the Car CAN bus when any arrive.
+ * @brief Sends any CarCAN messages put in the queue via SendCarCAN_Put, and handles
+ * transmitting the IO State of the car for telemetry & ignition sequence.
+ * 
+ * Call SendCarCAN_Init() to initialize the queue and semaphore. Call SendCarCAN_Put() to 
+ * put a message in the queue. Starting the SendCarCAN task will send any messages
+ * put in the queue, as well as spawn PutIOState task to forward the IO state.
  * 
 */
 #ifndef __SENDCARCAN_H

Apps/Inc/SendTritium.h

@@ -1,45 +1,39 @@
 /**
  * @file SendTritium.h
- * @brief The SendTritium task currently houses our velocity control code. 
- * It utilizes a FSM to coordinate what messages should be sent to the motor 
- * controller depending on a certain set of input variables. This FSM depends 
- * on data from across the system, such as the [Pedals](../Drivers/Pedals.html), 
- * the [Switches](../Drivers/Minions.html), and the CAN messages from 
- * BPS (indicating whether charging is enabled).
+ * @brief Runs the car's State Machine and sends control messages to the Tritium motor controller. 
+ * 
+ * Starting the SendTritium task will start sending CAN messages 
+ * and running the state machine. For details on the state machine, see
  * 
  */
+
 #ifndef __SENDTRITIUM_H
 #define __SENDTRITIUM_H
 
 #include "common.h"
 
 /**
- * @def SENDTRITIUM_PRINT_MES
- * @brief Print messages for SendTritium.c
+ * Print messages for SendTritium.c
  */
 // #define SENDTRITIUM_PRINT_MES
 
 /**
- * @def SENDTRITIUM_EXPOSE_VARS
- * @brief Expose variables for SendTritium.c
+ * Expose variables for SendTritium.c
  */
 // #define SENDTRITIUM_EXPOSE_VARS
 
 /**
- * @def MOTOR_MSG_PERIOD
- * @brief Period of the motor CAN message in milliseconds
+ * Period of the motor CAN message in milliseconds
  */
 #define MOTOR_MSG_PERIOD 100
 
 /**
- * @def FSM_PERIOD
- * @brief Period of the state machine in milliseconds
+ * Period of the state machine in milliseconds
  */
 #define FSM_PERIOD 100
 
 /**
- * @def DEBOUNCE_PERIOD
- * @brief Period of the debouncer in units of FSM_PERIOD
+ * Period of the debouncer in units of FSM_PERIOD
  */
 #define DEBOUNCE_PERIOD 2
 
@@ -52,17 +46,15 @@
         GEAR(REVERSE_GEAR),   \
 
 /**
- * @enum Gear_t
- * @brief Enumerated list of gears
+ * Gears
 */
 typedef enum GEAR_ENUM {
     FOREACH_Gear(GENERATE_ENUM)
     NUM_GEARS,
 } Gear_t;
 
 /**
- * @enum TritiumStateName_t
- * @brief Enumerated list of states for the FSM
+ * States for the FSM
 */
 typedef enum{
     /** Forward drive state */
@@ -86,8 +78,7 @@ typedef enum{
 } TritiumStateName_t;
 
 /**
- * @struct TritiumState_t
- * @brief Struct containing the state name, state handler, and state decider
+ * Struct containing the state name, state handler, and state decider
  * function for the Tritium FSM
 */
 typedef struct TritiumState{

Apps/Inc/UpdateDisplay.h

@@ -1,7 +1,12 @@
 /**
  * @file UpdateDisplay.h
- * @brief The update display task maintains a queue of command structures, allowing 
- * other tasks to submit commands and sending out commands to the display as time allows.
+ * @brief Maintains a queue of command structures, allowing other tasks to
+ * submit commands and sending out commands to the display as time allows.
+ * 
+ * Once the UpdateDisplay task has been started, call any of the exposed UpdateDisplay 
+ * functions to send a command to the display. Call UpdateDisplay_ClearQueue() to clear the queue.
+ * The macros defined in Display.h can be used to set the values of some of the components with more
+ * explicit naming.
  * 
  */
 
@@ -16,7 +21,6 @@
 #include "Contactors.h"
 
 /**
- * @enum UpdateDisplayError_t
  * @brief Error types for UpdateDisplay application
 */
 typedef enum{
@@ -33,7 +37,6 @@ typedef enum{
 } UpdateDisplayError_t;
 
 /**
- * @enum TriState_t
  * @brief Three states for display elements
 */
 typedef enum{
@@ -47,38 +50,32 @@ typedef enum{
 
 // For cruise control and regen
 /**
- * @def DISP_DISABLED
  * @brief Disabled state for cruise control and regen
 */
 #define DISP_DISABLED STATE_0
 
 /**
- * @def DISP_ENABLED
  * @brief Enabled state for cruise control and regen (able to be used)
 */
 #define DISP_ENABLED STATE_1
 
 /**
- * @def DISP_ACTIVE
  * @brief Active state for cruise control and regen (currently being used)
 */
 #define DISP_ACTIVE STATE_2
 
 // For gear changes
 /**
- * @def DISP_NEUTRAL
  * @brief Neutral state for gear changes
 */
 #define DISP_NEUTRAL STATE_0
 
 /**
- * @def DISP_FORWARD
  * @brief Forward state for gear changes
 */
 #define DISP_FORWARD STATE_1
 
 /**
- * @def DISP_REVERSE
  * @brief Reverse state for gear changes
 */
 #define DISP_REVERSE STATE_2