fixed requested changes

lib/shared_data/include/SharedDataTypes.h

@@ -5,7 +5,7 @@
 #include "SysClock.h"
 #include "SharedFirmwareTypes.h"
 
-/// @brief defines modes of torque limit to be processed in torque limit map for exact values
+/// @brief Defines modes of torque limit to be processed in torque limit map for exact values.
 enum class TorqueLimit_e
 {
     TCMUX_FULL_TORQUE = 0,
@@ -50,15 +50,19 @@ struct DrivetrainDynamicReport_s
     float measuredTorqueCurrents[NUM_MOTORS];
     float measuredMagnetizingCurrents[NUM_MOTORS];
 };
-/// @brief stores two arrays of size equal to the amount of motors: speed setpoints and necessary torque to reach those setpoints 
+/// @brief Stores setpoints for a command to the Drivetrain, containing speed and torque setpoints for each motor. 
+/// The Speeds unit is rpm and are the targeted speeds for each wheel of the car.
+/// The torques unit is nm and is the torque requested from the motors to reach such speeds.
+/// One can use the arrays with FR(Front Left), FL(Front Left), RL(Rear Left), RR(Rear Right)  to access or modify the respective set points. eg. speeds_rpm[FR] = 0.0;
+/// Their indexes are defined in utility.h as follows: FL = 0, FR = 1, RL = 2, RR = 3.
 struct DrivetrainCommand_s
 {
     float speeds_rpm[NUM_MOTORS];
     float torqueSetpoints[NUM_MOTORS]; // FIXME: misnomer. This represents the magnitude of the torque the inverter can command to reach the commanded speed setpoint
 };
 
 /// @brief Packages drivetrain command with ready boolean to give feedback on controller successfully evaluating
-///@note returned by all car controllers evaluate method 
+/// @note returned by all car controllers evaluate method 
 struct TorqueControllerOutput_s
 {
     DrivetrainCommand_s command;
@@ -84,7 +88,7 @@ struct VectornavData_s
     xyz_vec<float> angular_rates;
 };
 
-/// @brief Defins errors for TC Mux to use to maintain system safety
+/// @brief Defines errors for TC Mux to use to maintain system safety
 enum class TorqueControllerMuxError
 {
     NO_ERROR = 0,

lib/systems/include/BaseController.h

@@ -2,7 +2,7 @@
 #define BASECONTROLLER
 #include "SharedDataTypes.h"
 
-/// @brief definition for a drivetrain command with no torque
+/// @brief defines namespace for definition of a drivetrain command with no torque for clearer code in the Muxer
 namespace BaseControllerParams
 {
     const DrivetrainCommand_s TC_COMMAND_NO_TORQUE = {
@@ -12,13 +12,13 @@ namespace BaseControllerParams
 }
 /**
  * @brief Base class for all controller
- * @note required method(s): evaluate
+ *        required method(s): evaluate
  */
 class Controller
 {
 public:
-    /// @brief ticks specific controller/system it belongs to
-    /// @param SharedCarState_s state 
+    /// @brief This ticks specific controller/system it belongs to. This is called in the Muxer whenever the drivetrain command is obtained.
+    /// @param state with all sensor information to properly define torque set points
     /// @return TorqueControllerOutput_s
     virtual TorqueControllerOutput_s evaluate(const SharedCarState_s &state) = 0;
 };

lib/systems/include/BaseLaunchController.h

@@ -5,7 +5,10 @@
 #include <algorithm>
 #include <math.h> 
 
-/// @brief Modes to guide tick behavior and progression 
+/// @brief Modes to define launch behavior, where each one waits for acceleration request threshold to move to next mode
+/// LAUNCH_NOT_READY keeps speed at 0 and makes sure pedals are not pressed
+/// LAUNCH_READY keeps speed at 0 and makes sure break is not pressed
+/// LAUNCHING uses respective algorithm to set speed set point and requests torque from motors to reach it
 enum class LaunchStates_e
 {
     NO_LAUNCH_MODE,
@@ -41,7 +44,7 @@ class BaseLaunchController : public virtual Controller
 
 public:
     /// @brief Constructor for template launch controller
-    /// @param initial_speed_target unused right now
+    /// @param initial_speed_target used only in simple launch controller algorithm
     /// @note requires one method: calc_launch_algo
     BaseLaunchController(int16_t initial_speed_target)
         : init_speed_target_(initial_speed_target)
@@ -51,22 +54,17 @@ class BaseLaunchController : public virtual Controller
     }
 
     /// @brief ticks launch controller to progress through launch states when conditions are met
-    /// @param SysTick_s &tick 
-    /// @param PedalsSystemData_s &pedalsData 
-    /// @param float[] wheel_rpms 
-    /// @param VectornavData_s &vn_data 
     void tick(const SysTick_s &tick,
               const PedalsSystemData_s &pedalsData,
               const float wheel_rpms[],
               const VectornavData_s &vn_data);
     LaunchStates_e get_launch_state() { return launch_state_; }
-    /// @brief calculates how speed target is set among launch controllers
-    /// @param VectornavData_s &vn_data 
-    /// @note has important variation in launch controller tick as the launch controllers share a tick method
+    /// @brief calculates how speed target, the speed the car is trying to achieve during launch, is set and/or increased during launch
+    /// @param vn_data vector data like speed and coordinates
+    /// @note defines important variation in launch controller tick/evaluation as the launch controllers share a tick method defined in this parent class implementation
+    /// @note all launch algorithms are implemented in LaunchControllerAlgos.cpp
     virtual void calc_launch_algo(const VectornavData_s &vn_data) = 0;
-    /// @brief ticks launch controller
-    /// @param SharedCarState_s &state 
-    /// @return TorqueControllerOutput_s
+    /// @note refer to parent class
     TorqueControllerOutput_s evaluate(const SharedCarState_s &state) override;
 };
 #endif // __BASELAUNCHCONTROLLER_H__

lib/systems/include/CASESystem.h

@@ -148,17 +148,17 @@ class CASESystem
 
     DrivetrainCommand_s get_current_drive_command() { return current_command_; }
 
-    /// @brief uses pedal data to determine the requested torque by the car
-    /// @param PedalsSystemData_s &pedals_data 
-    /// @param float max_torque 
-    /// @param float max_regen_torque
-    /// @param float max_rpm 
+    /// @brief uses pedal data to determine the torque to be requested from the motors
+    /// @param pedals_data has accel and regen percent 
+    /// @param max_torque not used right now
+    /// @param max_regen_torque used for calculation of torque request
+    /// @param max_rpm not used right now
     /// @return float representing the calculated request
     float calculate_torque_request(const PedalsSystemData_s &pedals_data, float max_torque, float max_regen_torque, float max_rpm);
 
     /// @brief retrieves rpm setpoint based on final torque value
     /// @param float final_torque 
-    /// @return The maximum RPM from the configuration if torque is positive, otherwise 0.
+    /// @return The maximum RPM from the case configuration if torque is positive, otherwise 0.
     float get_rpm_setpoint(float final_torque)
     {
         if (final_torque > 0)

lib/systems/include/Controllers/CASEControllerWrapper.h

@@ -5,17 +5,17 @@
 #include "CASESystem.h"
 
 template <typename message_queue>
+/// @brief makes CASE system a part of Controller hierarchy for use in TC Mux
 class TorqueControllerCASEWrapper : public virtual Controller
 {
 public:
     TorqueControllerCASEWrapper() = delete;
-    /// @brief makes CASE system apart of Controller hierarchy for use in TC Mux
-    /// @param case_instance 
+    /// @param case_instance provide current instance to ensure there are not duplicates of this system as it needs to stay updated for MCU to get data.
     TorqueControllerCASEWrapper(CASESystem<message_queue> *case_instance) : case_instance_(case_instance)
     {
     }
     /// @brief packages CASE system command into Torque Controller Output
-    /// @param SharedCarState_s &state
+    /// @param state this state is updated by the CASE system in main repeatedly
     /// @return TorqueControllerOutput_s
     TorqueControllerOutput_s evaluate(const SharedCarState_s &state) override
     {

lib/systems/include/Controllers/LoadCellVectoringController.h

@@ -57,7 +57,7 @@ class TorqueControllerLoadCellVectoring : public virtual Controller
         writeout_.command = BaseControllerParams::TC_COMMAND_NO_TORQUE;
         writeout_.ready = false;
     }
-    /// @brief default contructor with balanced dfault values: rearTorqueScale = 1.0, regenTorqueScale = 1.0
+    /// @brief default contructor with balanced default values: rearTorqueScale = 1.0, regenTorqueScale = 1.0
     TorqueControllerLoadCellVectoring() : TorqueControllerLoadCellVectoring(1.0, 1.0) {}
 
     /// @brief Calculates speed set point based on normal force applied to wheels individually
@@ -68,9 +68,7 @@ class TorqueControllerLoadCellVectoring : public virtual Controller
         const SysTick_s &tick,
         const PedalsSystemData_s &pedalsData,
         const LoadCellInterfaceOutput_s &loadCellData);
-    /// @brief ticks controller
-    /// @param SharedCarState_s &state 
-    /// @return TorqueControllerOutput_s
+    /// @note refer to parent class
     TorqueControllerOutput_s evaluate(const SharedCarState_s &state) override;
 };
 

lib/systems/include/Controllers/SimpleController.h

@@ -28,12 +28,10 @@ class TorqueControllerSimple : public Controller
         writeout_.command = BaseControllerParams::TC_COMMAND_NO_TORQUE;
         writeout_.ready = true;
     }
-    /// @brief calculates torqe output based off max torque and simple torque scaling metric defined in constructor
-    /// @param PedalsSystemData_s &pedalsData 
+    /// @brief calculates torqe output based off max torque and simple torque scaling metric defined in constructor and adjusts writeout_ accordingly
+    /// @param pedalsData controller calculates acceleration request from the pedals based off of this data
     void tick(const PedalsSystemData_s &pedalsData);
-    /// @brief ticks controller
-    /// @param SharedCarState_s &state 
-    /// @return TorqueControllerOutput_s
+    /// @note refer to parent class
     TorqueControllerOutput_s evaluate(const SharedCarState_s &state) override;
 };
 

lib/systems/include/Controllers/SimpleLaunchController.h

@@ -19,7 +19,7 @@ class TorqueControllerSimpleLaunch : public virtual BaseLaunchController
 public:
     /*!
         SIMPLE LAUNCH CONTROLLER
-        @brief launch controller is based off of a specified launch rate and an initial speed target
+        @brief this launch controller is based off of a specified launch rate and an initial speed target
         It will ramp up the speed target linearlly over time to accelerate
         @param launch_rate specified launch rate in m/s^2
         @param initial_speed_target the initial speed commanded to the wheels
@@ -30,8 +30,8 @@ class TorqueControllerSimpleLaunch : public virtual BaseLaunchController
 
     /// @brief base constrcutor with default values: Default_Launch_Rate = 11.76, DEFAULT_LAUNCH_SPEED_TARGET = 1500(rpm)
     TorqueControllerSimpleLaunch() : TorqueControllerSimpleLaunch(SLParams::DEFAULT_LAUNCH_RATE, SLParams::DEFAULT_LAUNCH_SPEED_TARGET) {}
-    /// @brief Increases speed target during launch linearly
-    /// @param VectornavData_s &vn_data 
+    /// @brief Increases speed target during launch linearly based off launch rate provided in the constructor
+    /// @param vn_data this data is not necessary for this controller but is supplied according to the interface
     void calc_launch_algo(const VectornavData_s &vn_data) override;
 };
 #endif // __SIMPLELAUNCHCONTROLLER_H__

lib/systems/include/TorqueControllerMux.h

@@ -46,6 +46,8 @@
 //      - [ ] write testing code for this in separate environment
 
 
+/// @brief Contains a max speed for mode changes(5 m/s), a max torque delta for mode change(.5 nm) and a max power limit(63000 W).
+///        These values are used in the event that no value is provided for them in the constructor. 
 namespace TC_MUX_DEFAULT_PARAMS
 {
     constexpr const float MAX_SPEED_FOR_MODE_CHANGE = 5.0;        // m/s
@@ -109,6 +111,7 @@ class TorqueControllerMux
     /// @param max_change_speed the max speed difference between the requested controller output and the actual speed of each wheel that if the controller has a diff larger than the mux will not switch to the requested controller
     /// @param max_torque_pos_change_delta same as speed but evaluated between the controller commanded torques defaults to TC_MUX_DEFAULT_PARAMS::MAX_TORQUE_DELTA_FOR_MODE_CHANGE
     /// @param max_power_limit the max power limit defaults to TC_MUX_DEFAULT_PARAMS::MAX_POWER_LIMIT
+    /// @note TC Mux must be created with at least 1 controller.
     explicit TorqueControllerMux(std::array<Controller *, num_controllers> controller_pointers,
                           std::array<bool, num_controllers> mux_bypass_limits,
                           float max_change_speed = TC_MUX_DEFAULT_PARAMS::MAX_SPEED_FOR_MODE_CHANGE,
@@ -131,7 +134,7 @@ class TorqueControllerMux
     /// @param requested_controller_type the requested controller type from the dial state
     /// @param controller_command_torque_limit the torque limit state enum set by dashboard
     /// @param input_state the current state of the car
-    /// @return the current drivetrain command to be sent to the drivetrain
+    /// @return the current DrivetrainCommand_s to be sent to the drivetrain
     DrivetrainCommand_s getDrivetrainCommand(ControllerMode_e requested_controller_type,
                                              TorqueLimit_e controller_command_torque_limit,
                                              const SharedCarState_s &input_state);