Merge branch 'sean.wallace.working' documentation updates

Author: swallace23

include/AT25M02.hpp

@@ -5,13 +5,14 @@
 #include "SPI.h"
 
 /**
- * Provides a library to interact with Microchip's AT25M02 chip.
+ * @file AT25M02.hpp
+ * @brief Provides a library to interact with Microchip's AT25M02 chip.
  * This treats the chip as a circular queue that will not overwrite it's data.
  *
  */
 
-/*
- * Commands for the AT25M02 chip. Pulled from the data sheet for this chip.
+/**
+ * @brief Commands for the AT25M02 chip. Pulled from the data sheet for this chip.
  * All commands are MSB first.
  */
 enum Command

include/Max1148.hpp

@@ -77,7 +77,7 @@ class Max1148{
          */
         void csh();
         /**
-         * @brief Reads an average ADC value from the Max1148 ADC. Uses Arduino's SPI library. 
+         * @brief Reads an average ADC value from the Max1148 ADC. Uses Arduino's SPI library. We don't use this anymore because we wanted to interleave ADC sampling between channels.
          * 
          * @param avg_num The number of samples to average.
          */
@@ -89,7 +89,7 @@ class Max1148{
     public:
         /**
          * @brief ADC constructor. Sets cs_pin as per ADC_CS_PIN macro. Chooses channel from Channel enum.
-         * @param channel The channel to read from. Format: CHAN0, CHAN1, etc.
+         * @param channel The channel to read from. Format: CHAN0, CHAN1, etc. I don't remember why it has to be static_cast but it works.
          */
         Max1148(Channel channel): cs_pin(ADC_CS_PIN) {
             this->channel = static_cast<uint8_t>(channel);

include/Pip.hpp

@@ -71,19 +71,15 @@ class Pip{
         uint16_t read_adc();
     public:
         /**
-         * @brief Constructor for the Pip class. All parameters modifiable.
+         * @brief Constructor for the Pip class. 
+         * 
          */
         Pip(int delay_us, uint16_t avg_num, uint16_t num_samples, uint16_t min, uint16_t max, uint8_t dac_pin, Max1148& adc);
         /**
          * @brief The data array for the sweep.
          */
         uint16_t data[SWEEP_MAX_SAMPLES];
 
-        /**
-         * @brief Sweeps the DAC output from min to max.
-         * Step length, delay, and number of samples are all set by the constructor.
-         */
-        void sweep();
 
 };
 #endif

include/PipController.hpp

@@ -5,7 +5,7 @@
 #include <Pip.hpp>
 /**
  * @brief Manages simultaneous sweep for two Pip sensors.
- * A bit hacky, but allows easily storing separate sweep data in each Pip object without compromising data privacy.
+ * A bit hacky, but allows easily managing simultaneous sweeping while keeping data separate and clean.
  */
 class PipController{
 	private:
@@ -14,8 +14,7 @@ class PipController{
 	public:
 		PipController(Pip& pip1, Pip& pip2) : pip1(pip1), pip2(pip2) {}
 		/**
-		 * @brief Sweeps both DACs simultaneously, reads both ADC channels. 
-		 * Functionally identical to the version committed by Max Roberts in 2015.
+		 * @brief Sweeps both DACs simultaneously, reads both ADC channels. Note that ADC sampling alternates between each pip channel.
 		 */
 		void sweep(){
 			double value1 = pip1.sweep_min;
@@ -32,9 +31,11 @@ class PipController{
 				analogWrite(pip2.dac_pin, (int)value2);
 				value1 += step1;
 				value2 += step2;
+				//preamp settling time - experimentally derived
 				delayMicroseconds(delay);
 				int total_data1 = 0;
 				int total_data2 = 0;
+				//avg_num should be same across both pips.
 				for (int i=0; i < pip1.avg_num; i++){
 					total_data1 += pip1.read_adc();
 					total_data2 += pip2.read_adc();

src/AT25M02.cpp

@@ -34,7 +34,7 @@ AT25M02::AT25M02()
 // Public Methods
 
 /**
- * @brief Initialize the AT25M02 EEPROM device.
+ * @brief Initialize the AT25M02 EEPROM device. Define spi settings, chip select pin, and set initial variables to zero.
  */
 void AT25M02::init(){
 	// Set up SPI device settings
@@ -49,16 +49,16 @@ void AT25M02::init(){
 	setWRSR(0x00);
 }
 
-/*
- * Returns how many bytes are free and available to be written to.
+/** 
+ * @brief Returns how many bytes are free and available to be written to.
  */
 uint32_t AT25M02::freeBytes()
 {
 	return RAM_SIZE - usedBytes();
 }
 
-/*
- * Returns the number of bytes currently being used.
+/**
+ * @brief Returns the number of bytes currently being used.
  */
 uint32_t AT25M02::usedBytes()
 {
@@ -90,8 +90,8 @@ uint32_t AT25M02::freeBufferBytes()
 }
 
 
-/*
- * Write from the given array to the memory. This data is appended to the end of
+/**
+ * @brief Write from the given array to the memory. This data is appended to the end of
  * the queue. Returns true if it successfully wrote all bytes. Returns false if
  * it could not write every byte without overwriting existing data.
  */
@@ -164,8 +164,8 @@ uint32_t AT25M02::readMemory(byte *dest, uint32_t length)
 	return len;
 }
 
-/*
- * Write the given number of bytes from the ram into the destination array.
+/**
+ * @brief Write the given number of bytes from the ram into the destination array.
  * These bytes are taken from the start of the queue.
  * Returns how many bytes were read and written to the array.
  */
@@ -181,8 +181,8 @@ int AT25M02::readData(byte* dest, uint32_t length)
 	return memlen + buflen;
 }
 
-/*
- * Checks if the RAM is ready for a new command.
+/**
+ * @brief Checks if the RAM is ready for a new command.
  */
 bool AT25M02::isReady()
 {
@@ -199,8 +199,8 @@ bool AT25M02::isReady()
 
 // Private Methods
 
-/*
- * Write the given data to the RAM in a page write.
+/**
+ * @brief Write the given data to the RAM in a page write.
  * Increments mem_end when done.
  */
 void AT25M02::writePage(uint32_t addr, byte* bytes, uint32_t length)
@@ -266,8 +266,8 @@ void AT25M02::sendCommand(Command cmd)
 	SPI.endTransaction();
 }
 
-/*
- * Sets the WRSR (Write status reg)
+/**
+ * @brief Sets the WRSR (Write status reg)
  */
 void AT25M02::setWRSR(byte val)
 {
@@ -283,8 +283,8 @@ void AT25M02::setWRSR(byte val)
 	SPI.endTransaction();
 }
 
-/*
- * Waits until the RAM is ready to write.
+/**
+ * @brief Waits until the RAM is ready to write.
  */
 void AT25M02::waitUntilReady()
 {

src/Pip.cpp

@@ -2,16 +2,6 @@
  * @file Pip.cpp
  * @brief Source file for the Pip library for Dartmouth's 317 Lab.
  */
-/*Check how linear DAC output is
-
-memory chips meant to be handed a page at a time, not bit by bit. that was the on board memory we had access to. 
-That's what explains the weird page framing things. there may now be better ways to address now.
-should be able to use the 422 to program the arduino. we can't understand why not. Worried that we'll have to bring some of the
-usb aspect up, because need to program it.
-
-Note - step time is 565 us.
-
-*/
 #include <Pip.hpp>
 /** @copydoc Pip:Pip(int delay, uint16_t avg_num, uint16_t num_samples, uint16_t min, uint16_t max, uint8_t dac_pin, Max1148& adc) */
 Pip::Pip(int delay, uint16_t avg_num, uint16_t num_samples, uint16_t min, uint16_t max, uint8_t dac_pin, Max1148& adc)
@@ -20,23 +10,6 @@ Pip::Pip(int delay, uint16_t avg_num, uint16_t num_samples, uint16_t min, uint16
     analogWriteResolution(12);
 }
 
-
-/** @copydoc Pip::sweep() */
-void Pip::sweep(){
-    //clear data from last sweep. Shouldn't cause issues with sending since sweep won't begin until data is cleaned and loaded into PDC buffer.
-    //Leaving commented because it shouldn't actually be necessary and impacts performance.
-    //clear_data(data, sizeof(data) / sizeof(data[0]));
-
-    double value = sweep_min;
-	double step = (double)(sweep_max - sweep_min) / (double)(num_samples - 1);
-    for (int i = 0; i < num_samples; i++){
-        analogWrite(DAC_PIN, (int)value);
-        value += step;
-        delayMicroseconds(delay_us);
-        data[i] = adc.adc_read_avg(avg_num);
-    }
-    analogWrite(DAC_PIN, sweep_max);
-}
 /** @copydoc Pip::clear_data(uint16_t data[], uint16_t size) */
 void Pip::clear_data(uint16_t data[], uint16_t size){
     for (int i = 0; i < size; i++){

src/main.cpp

@@ -17,7 +17,7 @@ GSE-D is configured to program the board. Simply connect to the board with USB,
 
    pio run
 
-Make sure you fetch and pull changes from git before programming the board.
+Make sure you fetch and pull changes from git before programming the board. This will build the project again before uploading, but it should be very fast.
 
 ## Notes and Quirks
 The board uses an external crystal oscillator, rather than the included ceramic oscillator on the Due. This required some changes that are not included in this documentation. First, a modded_system_sam3xa.c file is included in src/ to change the startup clock settings. Then, replace_libsam.py replaces the gcc_rel.a file that contains the precompiled startup code with our modded version. This required manually including the CMSIS libraries in /src/.

src/modded_system_sam3xa.c

@@ -1,6 +1,11 @@
 #include "cmsis_include/sam3xa.h"
 
-// copied from C:\Users\<user>\.platformio\packages\framework-cmsis-atmel\CMSIS\Device\ATMEL\sam3xa\source\system_sam3xa.c
+/**
+ * @file modded_system_sam3xa.c
+ * @brief Rewrite of system_sam3xa.c to support the external crystal oscillator on the shield. 317 Lab changes are flagged in comments.
+ * This is compiled into modded_libsam_3x8e_gcc_rel.a, which is linked into the final binary with replace_libsam.py. We have to do this because the Arduino framework uses a precompiled library for initial chip setup.
+ * This allows us to modify clock settings without changing the Platformio build process.
+ */
 
 /* @cond 0 */
 /**INDENT-OFF**/
@@ -18,7 +23,7 @@ extern "C" {
 uint32_t SystemCoreClock = CHIP_FREQ_MAINCK_RC_4MHZ;
 
 /**
- * \brief Setup the microcontroller system.
+ * @brief Setup the microcontroller system.
  * Initialize the System and update the SystemFrequency variable.
  */
 void SystemInit( void )
@@ -30,12 +35,13 @@ void SystemInit( void )
   /* Initialize main oscillator */
   if ( !(PMC->CKGR_MOR & CKGR_MOR_MOSCSEL) )
   {
+    //317 LAB - the last flag here bypasses the internal RC oscillator
     PMC->CKGR_MOR = CKGR_MOR_KEY_PASSWD | SYS_BOARD_OSCOUNT | CKGR_MOR_MOSCRCEN | CKGR_MOR_MOSCXTBY;
     while ( !(PMC->PMC_SR & PMC_SR_MOSCXTS) )
     {
     }
   }
-
+  //317 LAB - I don't fully understand why this flag is necessary, but selecting the crystal oscillator with the bypass flag still routes through the external oscillator.
   /* Switch to 3-20MHz Xtal oscillator */
   PMC->CKGR_MOR = CKGR_MOR_KEY_PASSWD | SYS_BOARD_OSCOUNT | CKGR_MOR_MOSCRCEN | CKGR_MOR_MOSCXTBY | CKGR_MOR_MOSCSEL;
 
@@ -68,6 +74,7 @@ void SystemInit( void )
   SystemCoreClock = CHIP_FREQ_CPU_MAX;
 }
 
+//317 LAB - we did not modify this function.
 void SystemCoreClockUpdate( void )
 {
   /* Determine clock frequency according to clock register values */