doc: detail functions

controller/controller.ino

-/*
+/*******************************************************************************
   Controller
 
-  Controller for the MechaRaptor tandem flapping wing system.
+    Purpose: Controller for the MechaRaptor tandem flapping wing system.
 
-  Currently, both ESC are fed the same signal, which means that the two sets
-  of wings flap at the same frequency. The phase between the two sets will be
-  adjusted manually by setting their initial positions as desired.
+    Note: Currently, both ESC are fed the same signal, which means that the two
+    sets of wings flap at the same frequency. The phase between the two sets
+    will be adjusted manually by setting their initial positions as desired.
 
   ------------------------------------------------------------------------------
   https://howtomechatronics.com/tutorials/arduino/arduino-brushless-motor-control-tutorial-esc-bldc/
@@ -15,13 +15,16 @@
   ULiege - Aeroelasticity and Experimental Aerodynamics
   MIT License
   Repo: https://gitlab.uliege.be/thlamb/mecharaptor-controller
-  ------------------------------------------------------------------------------
-*/
+*******************************************************************************/
 
-// Include Servo library to generate the PWM signal to control the motors
-#include <Servo.h>
+/******************************************************************************
+  Includes
+*******************************************************************************/
+#include <Servo.h> // Control ESC by sending appropriate PWM signal
 
-// Constants
+/******************************************************************************
+  Defines
+*******************************************************************************/
 #define SERVO_PIN_1 10 // ESC 1
 #define SERVO_PIN_2 9  // ESC 2
 #define SWITCH_PIN 7   // ON/OFF switch (mode control)
@@ -33,14 +36,24 @@
 #define MAX_RPM 6000   // Motor maximum RPM (set in ESC)
 #define MIN_RPM 1000   // Motor minimum RPM (set in ESC)
 
-// Create servo objects to control the ESC
+/******************************************************************************
+  Globals
+*******************************************************************************/
 Servo ESC1;
 Servo ESC2;
 
-// Declare global variables
 float freq = 0;
 String mode;
 
+
+/******************************************************************************
+Setup function
+
+  Initializes everything and wait for serial input if switch in serial mode
+
+  inputs: N/A
+  outputs: N/A
+ ******************************************************************************/
 void setup() {
   Serial.begin(9600); //115200 when we will use angle sensors
 
@@ -62,8 +75,15 @@ void setup() {
 }
 
 
-void loop() {
+/******************************************************************************
+loop function
+
+  purpose : implements the control and aquisition of the MicroRaptor
 
+  inputs: N/A
+  outputs: N/A
+ ******************************************************************************/
+void loop() {
 
   // Get proper value to send to ESC
   /*if(mode =="SERIAL"){
@@ -105,7 +125,14 @@ void loop() {
 }
 
 
-// Prompt user to input the frequency
+/******************************************************************************
+promptfreq function
+
+  purpose : prompts the user for the frequency to use
+
+  inputs: N/A
+  outputs: freqency (float between 1 and 10)
+ ******************************************************************************/
 float promptfreq() {
   float input;
 
@@ -140,14 +167,29 @@ float promptfreq() {
 }
 
 
-// Convert frequency to ESC input
+/******************************************************************************
+freqtoesc function
+
+  purpose : converts frequency to ESC angle input
+
+  inputs: frequency
+  outputs: escVal
+ ******************************************************************************/
 int freqtoesc(float freq) {
   int ret = 0;
 
   return ret;
 }
 
-// Stop the motor properly
+
+/******************************************************************************
+stopmotor function
+
+  purpose : gently stops the motors
+
+  inputs: escVal
+  outputs: N/A
+ ******************************************************************************/
 void stopmotor(int curEscVal){
 
   // Slow it down first