Comments (#53)

---------

Co-authored-by: cjsport11 <cjsport11@gmial.com>
Co-authored-by: THERocky <101498190+Rocky14683@users.noreply.github.com>
Co-authored-by: Andrew Lu <lu987@purdue.edu>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

include/VOSS/chassis/AbstractChassis.hpp

@@ -49,15 +49,18 @@ class AbstractChassis {
               voss::Flags flags = voss::Flags::NONE,
               voss::AngularDirection direction = voss::AngularDirection::AUTO,
               double exitTime = 22500);
+
     void turn(double target, double max = 100.0,
               voss::Flags flags = voss::Flags::NONE,
               voss::AngularDirection direction = voss::AngularDirection::AUTO,
               double exitTime = 22500);
+
     void
     turn_to(Point target, controller_ptr controller, double max = 100.0,
             voss::Flags flags = voss::Flags::NONE,
             voss::AngularDirection direction = voss::AngularDirection::AUTO,
             double exitTime = 22500);
+
     void
     turn_to(Point target, double max = 100.0,
             voss::Flags flags = voss::Flags::NONE,

src/VOSS/chassis/AbstractChassis.cpp

@@ -28,6 +28,7 @@ void AbstractChassis::move_task(controller_ptr controller, double max,
             this->task_running = false;
         });
 
+    // Early exit for async movement
     if (flags & voss::Flags::ASYNC) {
         return;
     }
@@ -57,12 +58,14 @@ void AbstractChassis::turn_task(controller_ptr controller, double max,
             this->task_running = false;
         });
 
+    // Early exit for async movement
     if (flags & voss::Flags::ASYNC) {
         return;
     }
     this->task->join();
 }
 
+// Overloaded constructors move functions to allow for different parameters
 void AbstractChassis::move(Point target, double max, voss::Flags flags,
                            double exitTime) {
     this->move(target, this->default_controller, max, flags, exitTime);

src/VOSS/chassis/DiffChassis.cpp

@@ -4,6 +4,7 @@
 
 namespace voss::chassis {
 
+// Limits acceleration by slew step
 double DiffChassis::slew(double target, bool is_left) {
     double step = this->slew_step;
     double current =
@@ -22,6 +23,8 @@ double DiffChassis::slew(double target, bool is_left) {
     return current;
 }
 
+// Overloaded constructor for creating differential chassis with different
+// controller layouts
 DiffChassis::DiffChassis(std::initializer_list<int8_t> left_motors,
                          std::initializer_list<int8_t> right_motors,
                          controller_ptr default_controller, double slew_step,
@@ -54,6 +57,8 @@ void DiffChassis::set_brake_mode(pros::motor_brake_mode_e mode) {
     this->right_motors->set_brake_mode(mode);
 }
 
+// Evoke the chassis to move according to how it was set up using the
+// constructor, returns true if movement is complete
 bool DiffChassis::execute(DiffChassisCommand cmd, double max) {
     return std::visit(
         overload{
@@ -81,6 +86,9 @@ bool DiffChassis::execute(DiffChassisCommand cmd, double max) {
 
                 return false;
             },
+            // Logic allowing for individual movements within a chain of
+            // movements to be registered at completed even though robot may
+            // still be moving
             [this, max](diff_commands::Chained& v) -> bool {
                 double v_max = std::max(fabs(v.left), fabs(v.right));
                 if (v_max > max) {
@@ -98,6 +106,9 @@ bool DiffChassis::execute(DiffChassisCommand cmd, double max) {
 
                 return true;
             },
+            // Logic to brake one side of the drive alloing for a turn around
+            // the side of the robot and returning true when the turn is
+            // finished
             [this, max](diff_commands::Swing& v) {
                 double v_max = std::max(fabs(v.left), fabs(v.right));
                 if (v.right == 0) {

src/VOSS/controller/AbstractController.cpp

@@ -9,6 +9,8 @@ AbstractController::AbstractController(
     this->l = l;
 }
 
+// Set desired postion with x, y, and heading
+// Relative target position WIP
 void AbstractController::set_target(Pose target, bool relative) {
     if (relative) {
         Point p = l->get_position();         // robot position
@@ -21,6 +23,7 @@ void AbstractController::set_target(Pose target, bool relative) {
     }
 }
 
+// Set desired orientation
 void AbstractController::set_angular_target(double angular_target,
                                             bool relative) {
     angular_target = voss::to_radians(angular_target);

src/VOSS/controller/BoomerangControllerBuilder.cpp

@@ -1,9 +1,9 @@
 #include "VOSS/controller/BoomerangControllerBuilder.hpp"
 
-#include <utility>
 #include "VOSS/controller/BoomerangController.hpp"
 #include "VOSS/localizer/AbstractLocalizer.hpp"
 #include "VOSS/utils/angle.hpp"
+#include <utility>
 
 namespace voss::controller {
 

src/VOSS/controller/PIDController.cpp

@@ -3,8 +3,8 @@
 #include "VOSS/chassis/ChassisCommand.hpp"
 #include "VOSS/utils/angle.hpp"
 #include <cmath>
-#include <utility>
 #include <memory>
+#include <utility>
 
 namespace voss::controller {
 
@@ -15,6 +15,14 @@ PIDController::PIDController(std::shared_ptr<localizer::AbstractLocalizer> l)
 
 chassis::DiffChassisCommand PIDController::get_command(bool reverse,
                                                        bool thru) {
+    // Runs in background of move commands
+    // distance formula to find the distance between the robot and the target
+    // position distance error is distance ArcTan is used to find the angle
+    // between the robot and the target position This difference is the angle
+    // error Power applied to the motors based on type of movement and error
+    // Dependant on the weight of the constants and the errors
+    // Controller exits when robot settled for a designated time duration or
+    // accurate to a specified tolerance
     counter += 10;
     int dir = reverse ? -1 : 1;
     Point current_pos = this->l->get_position();
@@ -99,6 +107,7 @@ chassis::DiffChassisCommand PIDController::get_command(bool reverse,
 
         ang_speed = angular_pid(angle_error);
     }
+    // Runs at the end of a through movement
     if (chainedExecutable) {
         return chassis::DiffChassisCommand{chassis::diff_commands::Chained{
             dir * std::fmax(lin_speed, this->min_vel) - ang_speed,
@@ -112,6 +121,12 @@ chassis::DiffChassisCommand PIDController::get_command(bool reverse,
 chassis::DiffChassisCommand
 PIDController::get_angular_command(bool reverse, bool thru,
                                    voss::AngularDirection direction) {
+    // Runs in the background of turn commands
+    // Error is the difference between the target angle and the current angle
+    // ArcTan is used to find the angle between the robot and the target
+    // position Output is proportional to the error and the weight of the
+    // constant Controller exits when robot settled for a designated time
+    // duration or accurate to a specified tolerance
     counter += 10;
     double current_angle = this->l->get_orientation_rad();
     double target_angle = 0;
@@ -164,7 +179,8 @@ PIDController::get_angular_command(bool reverse, bool thru,
     return chassis::DiffChassisCommand{
         chassis::diff_commands::Voltages{-ang_speed, ang_speed}};
 }
-
+// What is calculating the required motor power for a linear movement
+// Returns value for motor power with type double
 double PIDController::linear_pid(double error) {
     total_lin_err += error;
 
@@ -175,7 +191,8 @@ double PIDController::linear_pid(double error) {
 
     return speed;
 }
-
+// What is calculating the required motor power for a turn
+// Returns value for motor power with type double
 double PIDController::angular_pid(double error) {
     total_ang_err += error;
 
@@ -187,6 +204,7 @@ double PIDController::angular_pid(double error) {
     return speed;
 }
 
+// Function to reset every variable used in the PID controller
 void PIDController::reset() {
     this->prev_lin_err = 0;
     this->total_lin_err = 0;

src/VOSS/controller/PIDControllerBuilder.cpp

@@ -1,9 +1,9 @@
 #include "VOSS/controller/PIDControllerBuilder.hpp"
 
-#include <utility>
 #include "VOSS/controller/PIDController.hpp"
 #include "VOSS/localizer/AbstractLocalizer.hpp"
 #include "VOSS/utils/angle.hpp"
+#include <utility>
 
 namespace voss::controller {
 

src/VOSS/controller/SwingController.cpp

@@ -1,8 +1,8 @@
 #include "VOSS/controller/SwingController.hpp"
 
-#include <utility>
 #include "SwingControllerBuilder.hpp"
 #include "VOSS/utils/angle.hpp"
+#include <utility>
 
 namespace voss::controller {
 SwingController::SwingController(
@@ -17,6 +17,14 @@ chassis::DiffChassisCommand SwingController::get_command(bool reverse,
 chassis::DiffChassisCommand
 SwingController::get_angular_command(bool reverse, bool thru,
                                      voss::AngularDirection direction) {
+    // Runs in background of Swing Turn commands
+    // ArcTan is used to find the angle between the robot and the target
+    // position One size of the drive is locked in place while the other side
+    // moves. This is determined by which side has less required movement
+    // Reverse flag flips the direction the moving side
+    // Power appled to motors based on proportion of the error and the weight of
+    // the constant Exit conditions are when the robot has settled for a
+    // designated time duration or accurate to a specified tolerance
     counter += 10;
     double current_angle = this->l->get_orientation_rad();
     double target_angle = 0;
@@ -100,6 +108,8 @@ SwingController::get_angular_command(bool reverse, bool thru,
     return command;
 }
 
+// What is calculating the required motor power for the turn
+// Returns value for motor power with type double
 double SwingController::angular_pid(double error) {
     total_ang_err += error;
 
@@ -111,6 +121,7 @@ double SwingController::angular_pid(double error) {
     return speed;
 }
 
+// Resets all the variables used in the swing controller
 void SwingController::reset() {
     this->prev_ang_err = 0;
     this->prev_ang_speed = 0;

src/VOSS/controller/SwingControllerBuilder.cpp

@@ -1,9 +1,9 @@
 #include "VOSS/controller/SwingControllerBuilder.hpp"
 
-#include <utility>
 #include "VOSS/controller/SwingController.hpp"
 #include "VOSS/localizer/AbstractLocalizer.hpp"
 #include "VOSS/utils/angle.hpp"
+#include <utility>
 
 namespace voss::controller {
 

src/VOSS/localizer/ADILocalizer.cpp

@@ -7,6 +7,7 @@
 
 namespace voss::localizer {
 
+// Creating a localizer object with varibale option based on adi imput sensors
 ADILocalizer::ADILocalizer(int left, int right, int mid, double lr_tpi,
                            double mid_tpi, double track_width,
                            double middle_dist, int imu_port)
@@ -88,6 +89,11 @@ void ADILocalizer::calibrate() {
     this->pose = {0.0, 0.0, 0.0};
 }
 
+// Calculates the current position of the robot
+// Uses the change in value of the encoders to calculate the change in position
+// If no imu is present, the robot's heading is calculated using the difference
+// in the left and right encoder values Angle is the differnce between the robot
+// heading and the global angle
 void ADILocalizer::update() {
     double left_pos = get_left_encoder_value();
     double right_pos = get_right_encoder_value();

src/VOSS/localizer/ADILocalizerBuilder.cpp

@@ -53,6 +53,7 @@ ADILocalizerBuilder& ADILocalizerBuilder::with_imu(int imu_port) {
     return *this;
 }
 
+// Check to see if the attempted object to be build will be a valid build
 std::shared_ptr<ADILocalizer> ADILocalizerBuilder::build() {
     std::unordered_set<unsigned char> valid_representations = {
         0b11111111, 0b11101111, 0b11110111, 0b11110101, 0b11100111, 0b11100101,

src/VOSS/localizer/AbstractLocalizer.cpp

@@ -4,10 +4,15 @@
 
 namespace voss::localizer {
 
+// Creating the localiozer object with a starting pose of x = 0, y = 0, and
+// heading = 0
 AbstractLocalizer::AbstractLocalizer() {
     this->pose = {0.0, 0.0, 0.0};
 }
 
+// Starting the localization task
+// Once started it don't stop until program is stopped or data abort
+// Uses mutex to keep values protected
 void AbstractLocalizer::begin_localization() {
     pros::Task localization_task([this]() {
         this->calibrate();
@@ -20,7 +25,8 @@ void AbstractLocalizer::begin_localization() {
         }
     });
 }
-
+// These last few functions allows the user to set and get values of the robot's
+// pose while keeing the values safe with mutex
 void AbstractLocalizer::set_pose(Pose pose) {
     std::unique_lock<pros::Mutex> lock(this->mtx);
     this->pose = {pose.x, pose.y, to_radians(pose.theta)};

src/VOSS/localizer/IMELocalizer.cpp

@@ -10,6 +10,8 @@
 
 namespace voss::localizer {
 
+// Creating a localizer object with varibale option based on internal motor
+// encoders
 IMELocalizer::IMELocalizer(std::vector<int8_t> left_motors_ports,
                            std::vector<int8_t> right_motors_ports,
                            std::vector<int8_t> horizontal_motors_ports,
@@ -95,7 +97,11 @@ void IMELocalizer::calibrate() {
     }
     this->pose = {0.0, 0.0, 0.0};
 }
-
+// Calculates the current position of the robot
+// Uses the change in value of the encoders to calculate the change in position
+// If no imu is present, the robot's heading is calculated using the difference
+// in the left and right encoder values Angle is the differnce between the robot
+// heading and the global angle
 void IMELocalizer::update() {
     double left_pos = get_left_encoder_value();
     double right_pos = get_right_encoder_value();

src/VOSS/localizer/IMELocalizerBuilder.cpp

@@ -59,6 +59,7 @@ IMELocalizerBuilder& IMELocalizerBuilder::with_imu(int imu_port) {
     return *this;
 }
 
+// Check to see if the attempted object to be build will be a valid build
 std::shared_ptr<IMELocalizer> IMELocalizerBuilder::build() {
 
     std::unordered_set<unsigned char> valid_representations = {

src/VOSS/selector/Selector.cpp

@@ -10,10 +10,13 @@ lv_obj_t* redBtnm;
 lv_obj_t* blueBtnm;
 lv_obj_t* skillsBtnm;
 
+// Add the list of autonomous routines buttons here
 int auton;
 const char* btnmMap[11] = {"", "", "", "", "", "", "", "", "", "", ""};
 const char* skillsMap[] = {"Skills", ""};
 
+// Rendering the buttons for the autonomous routines
+// Add logic that if the button is pressed, that autonomous routine is selected
 void render() {
     lv_btnmatrix_clear_btn_ctrl_all(redBtnm, LV_BTNMATRIX_CTRL_CHECKED);
     lv_btnmatrix_clear_btn_ctrl_all(blueBtnm, LV_BTNMATRIX_CTRL_CHECKED);
@@ -29,6 +32,7 @@ void render() {
     }
 }
 
+// Initializing the autonomous selector screen
 void init(int default_auton, const char** autons) {
 
     int ptr = 0;
@@ -122,7 +126,8 @@ void init(int default_auton, const char** autons) {
     // Release mutex
     auton_mtx.give();
 }
-
+// What is envoked to get the value of the selected autonomous routine so it can
+// be used in the main.cpp file
 int get_auton() {
     auton_mtx.take();
     int ret = auton;