Index: analog.c
===================================================================
--- analog.c	(revision 323)
+++ analog.c	(revision 324)
@@ -28,9 +28,22 @@
  * @brief Analog input and output
  *
  * Contains functions for manipulating the ADC on the Dragonfly board.
+ * It operates by running throug all available analog ports (set by AN_MAX,
+ * see analog.h for details on that constant). It performs a conversion for
+ * each port and stores the 8bit and 10bit value. It then increments the 
+ * port that it is looking at and then procedes to do another read.
+ *
+ * analog8 and analog10 are changed to use the lookup table. To use the
+ * historic functions, use analog_get8 and analog_get10. If you do use those,
+ * it is advised to turn off the loop by calling analog_stop_loop and restarting
+ * the loop when done with analog_start_loop. This is especially important if you
+ * are planning on doing a series of analog_getX reads.
+ *
+ * This function pretty intensive on the interrupts as it will be called quite
+ * often. Plan ahead for this.
  * 
- * @author Colony Project, CMU Robotics Club
- * code mostly taken from fwr analog file (author: Tom Lauwers)
+ * @author Colony Project, CMU Robotics Club, Kevin Woo
+ * Originally based on fwr code by Tom Lauwers
  **/
 
 #include <util/delay.h>
@@ -62,17 +75,19 @@
  * Initializes the ADC.
  * Call analog_init before reading from the analog ports.
  *
- * @see analog8, analog10
+ * @see analog8, analog10, analog_get8, analog_get10, analog_start_loop
+ *      analog_stop_loop
  **/
 void analog_init(int start_conversion)
 {
-	for (int i = 0; i < 11; i++) {
+    //Initialize the array to 0
+	for (int i = 0; i < (AN_MAX + 1); i++) {
 		an_val[i].adc10 = 0;
 		an_val[i].adc8 = 0;
 	}
 
-	//cli();
 	// ADMUX register
+	// The following bits are set
 	// Bit 7,6 - Set voltage reference to AVcc (0b01)
 	// Bit 5 - ADLAR set to simplify moving from register
 	// Bit 4 - X
@@ -83,10 +98,8 @@
 
 
 	// ADC Status Register A
+	// The following bits are set
 	// Bit 7 - ADEN is set (enables analog)
-	// Bit 6 - Start conversion bit is set (must be done once for free-running mode)
-	// Bit 5 - Enable Auto Trigger (for free running mode) NOT DOING THIS RIGHT NOW
-	// Bit 4 - ADC interrupt flag, 0
 	// Bit 3 - Enable ADC Interrupt (required to run free-running mode)
 	// Bits 2-0 - Set to create a clock divisor of 128, to make ADC clock = 8,000,000/64 = 125kHz
 	ADCSRA = 0;
@@ -99,15 +112,24 @@
 	set_adc_mux(0x00);
 	adc_current_port = AN1;
 
-	//Start the conversion if requested
+	// Start the conversion if requested
 	if (start_conversion)
 		analog_start_loop();
 	else
 		analog_stop_loop();
-	//sei();
 	
 }	
 
+/**
+ * Reads an analog value from the look-up table. Values are not
+ * good unless the analog loop is running.
+ *
+ * @param which is the analog port you wish to read.
+ *
+ * @return returns an 8 bit value which represents the analog value
+ *
+ * @see analog8, analog_start_loop, analog_stop_loop, analog_init
+ **/
 unsigned int analog_get8(int which) {
 	if (which == BOM_PORT) {
 		return 0;
@@ -116,6 +138,16 @@
 	}
 }
 
+/**
+ * Reads an analog value from the look-up table. Values are not
+ * good unless the analog loop is running.
+ *
+ * @param which is the analog port you wish to read.
+ *
+ * @return returns an 10 bit value which represents the analog value
+ *
+ * @see analog8, analog_start_loop, analog_stop_loop, analog_init
+ **/
 unsigned int analog_get10(int which) {
 	if (which == BOM_PORT) {
 		return 0;
@@ -124,6 +156,13 @@
 	}
 }
 
+/**
+ * Starts the analog loop to put values into the lookup table. Need
+ * to have the loop running before analog_get8 and analog_get10 are
+ * valid.
+ *
+ * @see analog_stop_loop, analog_init, analog_get8, analog_get10
+ **/
 void analog_start_loop(void) {
 	//Start the conversion
 	ADCSRA |= _BV(ADSC);
@@ -130,7 +169,12 @@
 	adc_loop_running = 0x1;
 }
 
-//will stop after current conversion finishes
+/**
+ * Starts the analog loop to put values into the lookup table. You
+ * should disable to loop to use analog8 and analog10 reliably.
+ *
+ * @see analog_stop_loop, analog_init, analog8, analog10
+ **/
 void analog_stop_loop(void) {
 	//Stop the conversion
 	adc_loop_running = 0x0;
@@ -140,7 +184,7 @@
  * analog_init must be called before using this function.
  * 
  * @param which the analog port to read from. One of
- * the constants AN0 - AN7.
+ * the constants AN0 - AN15.
  *
  * @return the eight bit input to the specified port
  *
@@ -173,7 +217,7 @@
  * 
  *
  * @param which the analog port to read from. Typically
- * a constant, one of AN0 - AN7.
+ * a constant, one of AN0 - AN15.
  *
  * @return the ten bit number input to the specified port
  * 
@@ -218,7 +262,7 @@
  **/
 int wheel(void)
 {
-	return analog_get8(WHEEL_PORT);
+	return analog8(WHEEL_PORT);
 }
 
 
@@ -248,26 +292,19 @@
 ISR(ADC_vect) {
 	static volatile int adc_prev_loop_running = 0;
 
+    // Need these local variables to read ADCH and ADCL in the correct order
 	int adc_h = 0;
 	int adc_l = 0;
 
-	//usb_putc('p');
-	//usb_putc('r');
-	//usb_puti(adc_loop_running);
-	//usb_puts("\n\r");
-
 	//Store the value only if this read isn't for the BOM
 	if (ADMUX != BOM_PORT) {
+	    // Read ADCL before ADCH otherwise the registers change in the middle
 		adc_l = ADCL;
 		adc_h = ADCH;
 	
 		an_val[adc_current_port - 1].adc10 = (adc_h << 2) | (adc_l >> 6);
 		an_val[adc_current_port - 1].adc8 = adc_h;
-		//usb_puti(an_val[adc_current_port - 1].adc10);
-		//usb_puts("\n\r");
-		//usb_puti(an_val[adc_current_port - 1].adc8);
-		//usb_puti(ADCH);
-		//usb_puts("\n\r");
+
 	}
 	
 	//Save the result only if we just turned off the loop
@@ -302,10 +339,6 @@
 		return;
 
 	ADCSRA |= _BV(ADSC);
-	
-	//if (ADCSRA & _BV(ADSC))
-	//	usb_putc('s');
-		
 	return;
 }
 
