Merge pull request #125 from mcgill-robotics/power_commenting

Added comments to power_custom & power_ros1_main.cpp

Author: JPGC04

pio_workspace/.gitignore

@@ -3,3 +3,5 @@
 .vscode/c_cpp_properties.json
 .vscode/launch.json
 .vscode/ipch
+.DS_Store
+lib/.DS_Store

pio_workspace/lib/power_custom/TMP36.cpp

@@ -1,20 +1,39 @@
+/* 
+Revision 1.0
+Commenter: Dorothy Ma
+
+TEMPERATURE SENSOR CONTROLS:
+0) indicate pin number and ref (Vcc) voltage when creating TMP36 object
+1) call "begin()" to setup the pin with microcontroller
+2) call "readTemperature()" to retrieve updated measurements
+*/
+
 #include "TMP36.h"
 
+// Arguments: pin number, reference voltage (Vcc)
 TMP36::TMP36(int pin, float ref) {
   sensorPin = pin;
   refVoltage = ref;
+  // Initializes volts and temperature variables to 0
   volts = 0;
   temperature = 0;
 }
 
+// Initializes the temp sensor by setting it up with the right pin
 void TMP36::begin() {
   pinMode(sensorPin, INPUT);
 }
 
+
+// Returns reading of the temperature sensor
 float TMP36::readTemperature() {
+  // calculates the temperature based on formula and reference voltage from the setup
+  // code source: https://botland.store/content/147-Read-temperature-with-an-Arduino-and-sensor-TMP36GT9Z
+
   int reading = analogRead(sensorPin);
   volts = (reading * refVoltage) / 1024.0;
   temperature = (volts - 0.5) * 100;
 
   return temperature;
+  
 }

pio_workspace/lib/power_custom/TMP36.h

@@ -1,20 +1,31 @@
+/* 
+Revision 1.0
+Commenter: Dorothy Ma
+
+HEADER FILE FOR TEMPERATURE SENSOR (TMP36GT9Z)
+*/
+
 #ifndef TMP36_H
 #define TMP36_H
 
 #include "Arduino.h"
 
 class TMP36 {
   public:
+    // Constructor for TMP36 class
     TMP36(int pin, float ref);
 
+    // Initialize TMP36 class
     void begin();
+
+    // Performs one reading of the sensor
     float readTemperature();
 
   private:
-    int sensorPin;
-    float refVoltage;
-    float volts;
-    float temperature;
+    int sensorPin; // Pin number to which the sensor is connected
+    float refVoltage; // Reference voltage for voltage conversion (Vcc)
+    float volts; // Voltage from reading
+    float temperature; // Temperature from reading
 };
 
 #endif

pio_workspace/lib/power_custom/ThrusterControl.cpp

@@ -1,3 +1,11 @@
+/* 
+Revision 1.0
+
+FUNCTIONS TO CONTROL THRUSTERS:
+1) call "initThrusters()" to attach servos and initialize all thrusters to off state
+2) call "updateThrusters(const int16_t microseconds[8])" to update PWM signals based on the microseconds[8] array
+*/
+
 #ifdef POWER_H
 
 #include "ThrusterControl.h"

pio_workspace/lib/power_custom/ThrusterControl.h

@@ -1,3 +1,9 @@
+/* 
+Revision 1.0
+
+HEADER FILE FOR THRUSTER CONTROL
+*/
+
 #ifdef POWER_H
 
 #ifndef THRUSTER_CONTROL_H

pio_workspace/lib/power_custom/adc_sensors.cpp

@@ -1,5 +1,18 @@
-#include "adc_sensors.h"
+/* 
+Revision 1.0
+Commenter: Dorothy Ma
+
+FUNCTIONS TO USE VOLTAGE- AND CURRENT-SENSING WITH ADCS:
+1) call "begin()" to initialize the ADCs and indicate whether to enableVoltage- and or enableCurrent-sensing
+2) call "senseVoltage()" and "senseCurrent()" to retrieve updated measurements
+*/
 
+#include "adc_sensors.h"
+/* 
+  Constructor for empty ADCSensor object:
+  1) voltageEnabled and currentEnabled flags are set to false
+  2) the arrays for holding sensor values are initialized to 0
+*/
 ADCSensors::ADCSensors() {
   voltageEnabled = false;
   currentEnabled = false;
@@ -17,6 +30,11 @@ ADCSensors::ADCSensors() {
   }
 }
 
+/*
+Initializes the I2C buses for sensors using their respective addresses for current and voltage sensing
+Arguments: flags for voltage sensing, current sensing, and wire
+Returns: true if the sensors are successfully initialized
+*/
 bool ADCSensors::begin(bool enableVoltage, bool enableCurrent, TwoWire* wire) {
   voltageEnabled = enableVoltage;
   currentEnabled = enableCurrent;
@@ -35,6 +53,10 @@ bool ADCSensors::begin(bool enableVoltage, bool enableCurrent, TwoWire* wire) {
   return success;
 }
 
+/* 
+Returns meaningful voltage values into an array [2]
+Will be -ve if voltageEnabled = false
+*/
 float* ADCSensors::senseVoltage() {
   if (voltageEnabled) {
     refreshVoltage();
@@ -47,6 +69,10 @@ float* ADCSensors::senseVoltage() {
   return voltageValues;
 }
 
+/*
+Returns meaningful current values into an array [8]
+Will be -ve if currentEnabled = false
+*/
 float* ADCSensors::senseCurrent() {
   if (currentEnabled) {
     refreshCurrent();
@@ -61,6 +87,10 @@ float* ADCSensors::senseCurrent() {
   return currentValues;
 }
 
+/*
+Performs one reading of the ADC for voltage
+Read and stores raw ADC value from channels 0-1 and computed voltage values into arrays
+*/
 void ADCSensors::refreshVoltage() {
   rawADCVoltage[0] = adcVoltage.readADC_SingleEnded(0);
   rawADCVoltage[1] = adcVoltage.readADC_SingleEnded(1);
@@ -69,6 +99,11 @@ void ADCSensors::refreshVoltage() {
   computedADCVoltage[1] = adcVoltage.computeVolts(rawADCVoltage[1]);
 }
 
+/* 
+Performs one reading of the ADC for current
+Read and stores raw ADC value for channels 0-3 for both adcCurrent objects
+Stores adcCurrent1 values into 0-3 and adcCurrent2 values into 4-7
+*/
 void ADCSensors::refreshCurrent() {
   for (int i = 0; i < 4; i++) {
     rawADCCurrent[i] = adcCurrent1.readADC_SingleEnded(i);
@@ -81,10 +116,22 @@ void ADCSensors::refreshCurrent() {
   }
 }
 
+// Convert ADC values into meaningful real-life voltage values based on circuit components
 float ADCSensors::convertVoltage(float adcVoltage) {
+  /* 
+  1+R41/R42 = 3
+  VBAT LOW: 12.8  | ADC INPUT: 0.18
+  VBAT NOM: 14.8  | ADC INPUT: 1.384
+  VBAT HIGH: 16.8 | ADC INPUT: 2.586
+  */
   return (adcVoltage * 2) * (16.8 - 12.8) / (2.586 - 0.180) + 12.5;
 }
 
+// Convert ADC values into meaningful real-life current values based on circuit components
 float ADCSensors::convertCurrent(float adcCurrent) {
+  /* 
+  Rs * Imax * Gain = Vomax
+  Vomax = 0.005 * 10 * 50 = 2.5
+  */
   return (((adcCurrent * 2 ) / 50 ) / 0.005);
 }

pio_workspace/lib/power_custom/adc_sensors.h

@@ -1,3 +1,10 @@
+/* 
+Revision 1.0
+Commenter: Dorothy Ma
+
+HEADER FILE FOR ADC_SENSOR FOR CURRENT & VOLTAGE SENSING
+*/
+
 #ifndef ADC_SENSORS_H
 #define ADC_SENSORS_H
 
@@ -11,32 +18,43 @@
 
 class ADCSensors {
   public:
+    // Constructor for ADCSensor class
     ADCSensors();
 
+    // Initialization of ADCSensor
     bool begin(bool enableVoltage, bool enableCurrent, TwoWire* wire = &Wire1);
+    
+    // Returns an array pointer to current measurements
     float* senseVoltage();
     float* senseCurrent();
 
   private:
+    // Flags to indicate which component to measure
     bool voltageEnabled;
     bool currentEnabled;
 
+    // Create Adafruit_ADS1115 sensor drivers
     Adafruit_ADS1115 adcCurrent1;
     Adafruit_ADS1115 adcCurrent2;
     Adafruit_ADS1115 adcVoltage;
 
+    // Arrays for raw measurements from the ADC
     int16_t rawADCVoltage[2];
     float computedADCVoltage[2];
 
+    // Arrays for measurements from ADC converted by the ADS1X15 computeVolts method
     int16_t rawADCCurrent[8];
     float computedADCCurrent[8];
 
+    // Arrays for V and I values calculated using real-world components with meaningful values
     float voltageValues[2];
     float currentValues[8];
 
+    // Reads the ADC values and uses computeVolts and stores into arrays
     void refreshVoltage();
     void refreshCurrent();
 
+    // Converts computed values to real-world values and stores into arrays
     float convertVoltage(float adcVoltage);
     float convertCurrent(float adcCurrent);
 };

pio_workspace/src/power_ros1_main.cpp

@@ -1,3 +1,12 @@
+/* 
+Revision 1.0
+
+SETUP FOR ROS COMMUNICATION WITH THE POWER BOARD
+1) Initializes and connects thrusters, adc sensors, and temperature sensors
+2) Sets up ros nodes for advertising and subscribing
+3) Polls all sensors, publishes data, and updates thrusters every 10 ms
+*/
+
 #ifdef POWER_ROS1_H
 
 #include "power_ros1_main.h"
@@ -29,10 +38,11 @@
 #define ENABLE_VOLTAGE_SENSE true
 #define ENABLE_CURRENT_SENSE true
 
+// creates ADCSensors and TMP36 sensor objects
 ADCSensors adcSensors;
 TMP36 temperatureSensor(23, 3.3);
 
-// defines 8 thursters for ROS subscribing
+// defines 8 thrusters for ROS subscribing
 const uint8_t BACK_L = auv_msgs::ThrusterMicroseconds::BACK_LEFT;
 const uint8_t HEAVE_BACK_L = auv_msgs::ThrusterMicroseconds::HEAVE_BACK_LEFT;
 const uint8_t HEAVE_FRONT_L = auv_msgs::ThrusterMicroseconds::HEAVE_FRONT_LEFT;
@@ -46,6 +56,7 @@ const uint8_t BACK_R = auv_msgs::ThrusterMicroseconds::BACK_RIGHT;
 std_msgs::Float32 batt1_voltage_msg;
 std_msgs::Float32 batt2_voltage_msg;
 
+// defines 8 thruster current sensing for ROS advertising
 std_msgs::Float32 thruster1_current_msg;
 std_msgs::Float32 thruster2_current_msg;
 std_msgs::Float32 thruster3_current_msg;
@@ -55,6 +66,7 @@ std_msgs::Float32 thruster6_current_msg;
 std_msgs::Float32 thruster7_current_msg;
 std_msgs::Float32 thruster8_current_msg;
 
+// defines board and teensy temperature sensing for ROS advertising
 std_msgs::Float32 board_temperature_msg;
 std_msgs::Float32 teensy_temperature_msg;
 
@@ -65,9 +77,8 @@ Servo thrusters[8];
 uint16_t microseconds[] = {1500, 1500, 1500, 1500, 1500, 1500, 1500, 1500};
 const uint16_t offCommand[] = {1500, 1500, 1500, 1500, 1500, 1500, 1500, 1500};
 
-// creates array for 2 battery voltage sensing
-float Bvoltages[2];
-float Tcurrents[8];
+float Bvoltages[2]; // array for 2 battery voltage sensing
+float Tcurrents[8]; // array for 8 thrusters current sensing
 float boardTemperature;
 float teensyTemperature;
 
@@ -118,7 +129,7 @@ ros::Publisher thruster8_current("/power/thrusters/current/8", &thruster8_curren
 ros::Publisher board_temperature("/power/board/temperature", &board_temperature_msg);
 ros::Publisher teensy_temperature("/power/teensy/temperature", &teensy_temperature_msg);
 
-// senses the voltages of the 2 batteries
+// senses the battery voltages, thruster currents, and board and teensy temperatures
 void senseData() {
     float* voltagePtr = adcSensors.senseVoltage();
     float* currentPtr = adcSensors.senseCurrent();
@@ -171,9 +182,10 @@ void publishData() {
     teensy_temperature.publish(&teensy_temperature_msg);
 }
 
+// setup all thrusters and sensors and setup node handler for subscribing and advertising
 void power_ros1_setup() {
     pinMode(LED_PIN, OUTPUT);
-    digitalWrite(LED_PIN, HIGH);
+    digitalWrite(LED_PIN, HIGH); // turn on LED_PIN
 
     initThrusters();
 
@@ -197,7 +209,7 @@ void power_ros1_setup() {
 }
 
 void power_ros1_loop() {
-    updateThrusters(microseconds);
+    updateThrusters(microseconds); 
 
     publishData();