Added doxygen source documentation

.gitignore

@@ -0,0 +1,3 @@
+.cproject
+.project
+

README.md

@@ -1,2 +1,12 @@
-# libBAT
-Blackaddr Audio Teensy Library
+Blackaddr Audio
+Teensy Guitar Audio Library
+
+This library contains convience C++ classes to allow full and easy access to the features of the Teensy Guitar Audio Series of boards.
+
+"Teensy" is an Arduino compatible series of boards from www.pjcr.com
+
+This libray can be downloaded and installed into the Arduino IDE by following the instruction here for installing from a zip:
+
+https://www.arduino.cc/en/Guide/Libraries
+
+

src/BAAudioControlWM8731.cpp

@@ -23,6 +23,65 @@
 
 namespace BAGuitar {
 
+// use const instead of define for proper scoping
+constexpr int WM8731_I2C_ADDR = 0x1A;
+
+// The WM8731 register map
+constexpr int WM8731_REG_LLINEIN   = 0;
+constexpr int WM8731_REG_RLINEIN   = 1;
+constexpr int WM8731_REG_LHEADOUT  = 2;
+constexpr int WM8731_REG_RHEADOUT  = 3;
+constexpr int WM8731_REG_ANALOG     =4;
+constexpr int WM8731_REG_DIGITAL   = 5;
+constexpr int WM8731_REG_POWERDOWN = 6;
+constexpr int WM8731_REG_INTERFACE = 7;
+constexpr int WM8731_REG_SAMPLING  = 8;
+constexpr int WM8731_REG_ACTIVE    = 9;
+constexpr int WM8731_REG_RESET    = 15;
+
+// Register Masks and Shifts
+// Register 0
+constexpr int WM8731_LEFT_INPUT_GAIN_ADDR = 0;
+constexpr int WM8731_LEFT_INPUT_GAIN_MASK = 0x1F;
+constexpr int WM8731_LEFT_INPUT_GAIN_SHIFT = 0;
+constexpr int WM8731_LEFT_INPUT_MUTE_ADDR = 0;
+constexpr int WM8731_LEFT_INPUT_MUTE_MASK = 0x80;
+constexpr int WM8731_LEFT_INPUT_MUTE_SHIFT = 7;
+constexpr int WM8731_LINK_LEFT_RIGHT_IN_ADDR = 0;
+constexpr int WM8731_LINK_LEFT_RIGHT_IN_MASK = 0x100;
+constexpr int WM8731_LINK_LEFT_RIGHT_IN_SHIFT = 8;
+// Register 1
+constexpr int WM8731_RIGHT_INPUT_GAIN_ADDR = 1;
+constexpr int WM8731_RIGHT_INPUT_GAIN_MASK = 0x1F;
+constexpr int WM8731_RIGHT_INPUT_GAIN_SHIFT = 0;
+constexpr int WM8731_RIGHT_INPUT_MUTE_ADDR = 1;
+constexpr int WM8731_RIGHT_INPUT_MUTE_MASK = 0x80;
+constexpr int WM8731_RIGHT_INPUT_MUTE_SHIFT = 7;
+constexpr int WM8731_LINK_RIGHT_LEFT_IN_ADDR = 1;
+constexpr int WM8731_LINK_RIGHT_LEFT_IN_MASK = 0x100;
+constexpr int WM8731_LINK_RIGHT_LEFT_IN_SHIFT = 8;
+// Register 4
+constexpr int WM8731_ADC_BYPASS_ADDR = 4;
+constexpr int WM8731_ADC_BYPASS_MASK = 0x8;
+constexpr int WM8731_ADC_BYPASS_SHIFT = 3;
+constexpr int WM8731_DAC_SELECT_ADDR = 4;
+constexpr int WM8731_DAC_SELECT_MASK = 0x10;
+constexpr int WM8731_DAC_SELECT_SHIFT = 4;
+// Register 5
+constexpr int WM8731_DAC_MUTE_ADDR = 5;
+constexpr int WM8731_DAC_MUTE_MASK = 0x8;
+constexpr int WM8731_DAC_MUTE_SHIFT = 3;
+constexpr int WM8731_HPF_DISABLE_ADDR = 5;
+constexpr int WM8731_HPF_DISABLE_MASK = 0x1;
+constexpr int WM8731_HPF_DISABLE_SHIFT = 0;
+
+// Register 9
+constexpr int WM8731_ACTIVATE_ADDR = 9;
+constexpr int WM8731_ACTIVATE_MASK = 0x1;
+
+
+// Reset the internal shadow register array to match
+// the reset state of the codec.
 void BAAudioControlWM8731::resetInternalReg(void) {
 	// Set to reset state
 	regArray[0] = 0x97;
@@ -47,6 +106,7 @@ BAAudioControlWM8731::~BAAudioControlWM8731()
 {
 }
 
+// Powerdown and disable the codec
 void BAAudioControlWM8731::disable(void)
 {
 
@@ -62,8 +122,8 @@ void BAAudioControlWM8731::disable(void)
 	resetCodec();
 }
 
-
-bool BAAudioControlWM8731::enable(void)
+// Powerup and unmute the codec
+void BAAudioControlWM8731::enable(void)
 {
 
 	// Sequence from WAN0111.pdf
@@ -109,18 +169,12 @@ bool BAAudioControlWM8731::enable(void)
 	regArray[WM8731_REG_POWERDOWN] = 0x02;
 	delay(500); // wait for output to power up
 
-//	// Activate the audio interface
-//	setActivate(true);
-//	delay(10);
 
-	//setDacMute(false);
 	delay(100); // wait for mute ramp
 
-	return true;
-
 }
 
-
+// Set the PGA gain on the Left channel
 void BAAudioControlWM8731::setLeftInputGain(int val)
 {
 	regArray[WM8731_LEFT_INPUT_GAIN_ADDR] &= ~WM8731_LEFT_INPUT_GAIN_MASK;
@@ -129,6 +183,7 @@ void BAAudioControlWM8731::setLeftInputGain(int val)
 	write(WM8731_LEFT_INPUT_GAIN_ADDR, regArray[WM8731_LEFT_INPUT_GAIN_ADDR]);
 }
 
+// Mute control on the ADC Left channel
 void BAAudioControlWM8731::setLeftInMute(bool val)
 {
 	if (val) {
@@ -139,6 +194,7 @@ void BAAudioControlWM8731::setLeftInMute(bool val)
 	write(WM8731_LEFT_INPUT_MUTE_ADDR, regArray[WM8731_LEFT_INPUT_MUTE_ADDR]);
 }
 
+// Link the gain/mute controls for Left and Right channels
 void BAAudioControlWM8731::setLinkLeftRightIn(bool val)
 {
 	if (val) {
@@ -152,6 +208,7 @@ void BAAudioControlWM8731::setLinkLeftRightIn(bool val)
 	write(WM8731_LINK_RIGHT_LEFT_IN_ADDR, regArray[WM8731_LINK_RIGHT_LEFT_IN_ADDR]);
 }
 
+// Set the PGA input gain on the Right channel
 void BAAudioControlWM8731::setRightInputGain(int val)
 {
 	regArray[WM8731_RIGHT_INPUT_GAIN_ADDR] &= ~WM8731_RIGHT_INPUT_GAIN_MASK;
@@ -160,6 +217,7 @@ void BAAudioControlWM8731::setRightInputGain(int val)
 	write(WM8731_RIGHT_INPUT_GAIN_ADDR, regArray[WM8731_RIGHT_INPUT_GAIN_ADDR]);
 }
 
+// Mute control on the input ADC right channel
 void BAAudioControlWM8731::setRightInMute(bool val)
 {
 	if (val) {
@@ -170,6 +228,7 @@ void BAAudioControlWM8731::setRightInMute(bool val)
 	write(WM8731_RIGHT_INPUT_MUTE_ADDR, regArray[WM8731_RIGHT_INPUT_MUTE_ADDR]);
 }
 
+// Dac output mute control
 void BAAudioControlWM8731::setDacMute(bool val)
 {
 	if (val) {
@@ -180,6 +239,7 @@ void BAAudioControlWM8731::setDacMute(bool val)
 	write(WM8731_DAC_MUTE_ADDR, regArray[WM8731_DAC_MUTE_ADDR]);
 }
 
+// Switches the DAC audio in/out of the output path
 void BAAudioControlWM8731::setDacSelect(bool val)
 {
 	if (val) {
@@ -190,6 +250,8 @@ void BAAudioControlWM8731::setDacSelect(bool val)
 	write(WM8731_DAC_SELECT_ADDR, regArray[WM8731_DAC_SELECT_ADDR]);
 }
 
+// Bypass sends the ADC input audio (analog) directly to analog output stage
+// bypassing all digital processing
 void BAAudioControlWM8731::setAdcBypass(bool val)
 {
 	if (val) {
@@ -200,6 +262,7 @@ void BAAudioControlWM8731::setAdcBypass(bool val)
 	write(WM8731_ADC_BYPASS_ADDR, regArray[WM8731_ADC_BYPASS_ADDR]);
 }
 
+// Enable/disable the dynamic HPF (recommended, it creates noise)
 void BAAudioControlWM8731::setHPFDisable(bool val)
 {
 	if (val) {
@@ -210,6 +273,7 @@ void BAAudioControlWM8731::setHPFDisable(bool val)
 	write(WM8731_HPF_DISABLE_ADDR, regArray[WM8731_HPF_DISABLE_ADDR]);
 }
 
+// Activate/deactive the I2S audio interface
 void BAAudioControlWM8731::setActivate(bool val)
 {
 	if (val) {
@@ -220,29 +284,26 @@ void BAAudioControlWM8731::setActivate(bool val)
 
 }
 
-
+// Trigger the on-chip codec reset
 void BAAudioControlWM8731::resetCodec(void)
 {
 	write(WM8731_REG_RESET, 0x0);
 	resetInternalReg();
 }
 
+// Direct write control to the codec
 void BAAudioControlWM8731::writeI2C(unsigned int addr, unsigned int val)
 {
 	write(addr, val);
 }
 
+// Low level write control for the codec via the Teensy I2C interface
 bool BAAudioControlWM8731::write(unsigned int reg, unsigned int val)
 {
 	Wire.beginTransmission(WM8731_I2C_ADDR);
 	Wire.write((reg << 1) | ((val >> 8) & 1));
 	Wire.write(val & 0xFF);
 	Wire.endTransmission();
-//        Serial.print(String("Wrote "));
-//        Serial.print((reg << 1) | ((val >> 8) & 1), HEX);
-//        Serial.print(" ");
-//        Serial.print(val & 0xFF, HEX);
-//        Serial.print("\n");
 
 	return true;
 }

src/BAAudioControlWM8731.h

@@ -1,10 +1,13 @@
-/*
- * BAAudioControlWM8731.h
+/**************************************************************************//**
+ *  BAAudioContromWM8731 is a class for controlling a WM8731 Codec via I2C.
+ *  @details The Codec power ups in a silent state, with non-optimal
+ *  configuration. This class will enable codec and set some initial gain levels.
+ *  The user can than use the API to changing settings for their specific needs.
  *
- *  Created on: May 22, 2017
- *      Author: slascos
- *
- *  This program is free software: you can redistribute it and/or modify
+ *  @file
+ *  @author Steve Lascos
+ *  @company Blackaddr Audio
+ *  @copyright This program is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
  *  the Free Software Foundation, either version 3 of the License, or
  *  (at your option) any later version.*
@@ -16,7 +19,7 @@
  *
  *  You should have received a copy of the GNU General Public License
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-*/
+ *****************************************************************************/
 
 #ifndef INC_BAAUDIOCONTROLWM8731_H_
 #define INC_BAAUDIOCONTROLWM8731_H_
@@ -25,90 +28,96 @@
 
 namespace BAGuitar {
 
-// use const instead of define for proper scoping
-constexpr int WM8731_I2C_ADDR = 0x1A;
-constexpr int WM8731_NUM_REGS = 10;
-
-constexpr int WM8731_REG_LLINEIN   = 0;
-constexpr int WM8731_REG_RLINEIN   = 1;
-constexpr int WM8731_REG_LHEADOUT  = 2;
-constexpr int WM8731_REG_RHEADOUT  = 3;
-constexpr int WM8731_REG_ANALOG     =4;
-constexpr int WM8731_REG_DIGITAL   = 5;
-constexpr int WM8731_REG_POWERDOWN = 6;
-constexpr int WM8731_REG_INTERFACE = 7;
-constexpr int WM8731_REG_SAMPLING  = 8;
-constexpr int WM8731_REG_ACTIVE    = 9;
-constexpr int WM8731_REG_RESET    = 15;
-
-// Register Masks and Shifts
-// Register 0
-constexpr int WM8731_LEFT_INPUT_GAIN_ADDR = 0;
-constexpr int WM8731_LEFT_INPUT_GAIN_MASK = 0x1F;
-constexpr int WM8731_LEFT_INPUT_GAIN_SHIFT = 0;
-constexpr int WM8731_LEFT_INPUT_MUTE_ADDR = 0;
-constexpr int WM8731_LEFT_INPUT_MUTE_MASK = 0x80;
-constexpr int WM8731_LEFT_INPUT_MUTE_SHIFT = 7;
-constexpr int WM8731_LINK_LEFT_RIGHT_IN_ADDR = 0;
-constexpr int WM8731_LINK_LEFT_RIGHT_IN_MASK = 0x100;
-constexpr int WM8731_LINK_LEFT_RIGHT_IN_SHIFT = 8;
-// Register 1
-constexpr int WM8731_RIGHT_INPUT_GAIN_ADDR = 1;
-constexpr int WM8731_RIGHT_INPUT_GAIN_MASK = 0x1F;
-constexpr int WM8731_RIGHT_INPUT_GAIN_SHIFT = 0;
-constexpr int WM8731_RIGHT_INPUT_MUTE_ADDR = 1;
-constexpr int WM8731_RIGHT_INPUT_MUTE_MASK = 0x80;
-constexpr int WM8731_RIGHT_INPUT_MUTE_SHIFT = 7;
-constexpr int WM8731_LINK_RIGHT_LEFT_IN_ADDR = 1;
-constexpr int WM8731_LINK_RIGHT_LEFT_IN_MASK = 0x100;
-constexpr int WM8731_LINK_RIGHT_LEFT_IN_SHIFT = 8;
-// Register 4
-constexpr int WM8731_ADC_BYPASS_ADDR = 4;
-constexpr int WM8731_ADC_BYPASS_MASK = 0x8;
-constexpr int WM8731_ADC_BYPASS_SHIFT = 3;
-constexpr int WM8731_DAC_SELECT_ADDR = 4;
-constexpr int WM8731_DAC_SELECT_MASK = 0x10;
-constexpr int WM8731_DAC_SELECT_SHIFT = 4;
-// Register 5
-constexpr int WM8731_DAC_MUTE_ADDR = 5;
-constexpr int WM8731_DAC_MUTE_MASK = 0x8;
-constexpr int WM8731_DAC_MUTE_SHIFT = 3;
-constexpr int WM8731_HPF_DISABLE_ADDR = 5;
-constexpr int WM8731_HPF_DISABLE_MASK = 0x1;
-constexpr int WM8731_HPF_DISABLE_SHIFT = 0;
-
-// Register 9
-constexpr int WM8731_ACTIVATE_ADDR = 9;
-constexpr int WM8731_ACTIVATE_MASK = 0x1;
-
+constexpr int WM8731_NUM_REGS = 10; // Number of registers in the internal shadow array
 
+/**************************************************************************//**
+ * BAAudioControlWM8731 provides an API for configuring the internal registers
+ * of the WM8731 codec.
+ * @details Not every single command is provided, please ask if you need something
+ * added that is not already present. You can also directly write any register
+ * you wish with the writeI2C() method.
+ *****************************************************************************/
 class BAAudioControlWM8731 {
 public:
 	BAAudioControlWM8731();
 	virtual ~BAAudioControlWM8731();
 
+	/// Mute and power down the codec.
 	void disable(void);
-	bool enable(void);
+
+	/// First disable, then cleanly power up and unmute the codec.
+	void enable(void);
+
+	/// Set the input gain of the codec's PGA for the left (TRS Tip) channel.
+	/// @param val an interger value from 31 = +12dB . . 1.5dB steps down to 0 = -34.5dB
 	void setLeftInputGain(int val);
+
+	/// Set the input gain of the codec's PGA for the right (TRS Ring) channel.
+	/// @param val an interger value from 31 = +12dB . . 1.5dB steps down to 0 = -34.5dB
 	void setRightInputGain(int val);
+
+	/// Mute/unmute the Left (TRS Tip) channel at the ADC input.
+	/// @param val when true, channel is muted, when false, channel is unmuted
 	void setLeftInMute(bool val);
+
+	/// Mute/unmute the Right (TRS Ring) channel at the ADC input.
+	/// @param val when true, channel is muted, when false, channel is unmuted
 	void setRightInMute(bool val);
+
+	/// Links the Left/Right channel contols for mute and input gain.
+	/// @details when true, changing either the left or right gain/mute controls will
+	/// affect both channels.
+	/// @param val when true, channels are linked, when false, they are controlled separately
 	void setLinkLeftRightIn(bool val);
+
+	/// Mute/unmute the output DAC, affects both Left and Right output channels.
+	/// @param when true, output DAC is muted, when false, unmuted.
 	void setDacMute(bool val);
+
+	/// Control when the DAC is feeding the output analog circuitry.
+	/// @param val when true, the DAC output is connected to the analog output. When
+	/// false, the DAC is disconnected.
 	void setDacSelect(bool val);
+
+	/// ADC Bypass control.
+	/// @details This permits the analog audio from the Codec's PGA to bypass the ADC
+	/// and go directly to the analog output of the codec, bypassing the digital domain
+	/// entirely.
+	/// @param val when true, analog ADC input is fed directly to codec analog otuput.
 	void setAdcBypass(bool val);
-	void setHPFDisable(bool val);
 
+	/// Digital High Pass Filter disable. RECOMMENDED ALWAYS TRUE!
+	/// @details this controls a HPF in the codec that attempts to remove the lowest
+	/// frequency (i.e. < 10 Hz) to improve headroom by dynamically measuring DC level.
+	/// In most cases, it introduces noise components by modulating the filter. This
+	/// is not suitable for applications where the audio is used for output, but might
+	/// be useful for applications like tuning, pitch detection, whre the noise components
+	/// can be tolerated.
+	/// @param val when true (recommended) the dynamic HPF is disabled, otherwise enabled.
+	void setHPFDisable(bool val);
 
+    /// Activates the I2S interface on the codec.
+	/// @param val when true, I2S interface is active, when false it is disabled.
 	void setActivate(bool val);
+
+	/// Soft-reset the codec.
+	/// @details This will cause the codec to reset its internal registers to default values.
 	void resetCodec(void);
 
+	/// Write a custom command to the codec via I2C control interface.
+	/// @details See WM8731 datasheet for register map details.
+	/// @param addr The register address you wish to write to, range 0 to 15.
+	/// @param val the 9-bit data value you wish to write at the address specifed.
 	void writeI2C(unsigned int addr, unsigned int val);
+
 protected:
+	// A shadow array for the registers on the codec since the interface is write-only.
 	int regArray[WM8731_NUM_REGS];
 
 private:
+	// low-level write command
 	bool write(unsigned int reg, unsigned int val);
+	// resets the internal shadow register array
 	void resetInternalReg(void);
 
 };

src/BAGpio.cpp

@@ -13,10 +13,6 @@ namespace BAGuitar {
 BAGpio::BAGpio()
 {
 	// Set all GPIOs to input
-//	for (auto i=0; i<NUM_GPIO; i++) {
-//		m_gpioState = 1;
-//	}
-
 	pinMode(static_cast<uint8_t>(GPIO::GPIO0), INPUT);
 	pinMode(static_cast<uint8_t>(GPIO::GPIO1), INPUT);
 	pinMode(static_cast<uint8_t>(GPIO::GPIO2), INPUT);
@@ -28,9 +24,9 @@ BAGpio::BAGpio()
 	pinMode(static_cast<uint8_t>(GPIO::TP1),   INPUT);
 	pinMode(static_cast<uint8_t>(GPIO::TP2),   INPUT);
 
+	// Set the LED ot ouput
 	pinMode(USR_LED_ID, OUTPUT);
-	m_ledState = 0;
-
+	clearLed(); // turn off the LED
 
 }
 
@@ -51,10 +47,11 @@ void BAGpio::clearGPIO(GPIO gpioId)
 	digitalWrite(static_cast<uint8_t>(gpioId), 0);
 
 }
-void BAGpio::toggleGPIO(GPIO gpioId)
+int BAGpio::toggleGPIO(GPIO gpioId)
 {
 	int data = digitalRead(static_cast<uint8_t>(gpioId));
 	digitalWrite(static_cast<uint8_t>(gpioId), ~data);
+	return ~data;
 }
 
 void BAGpio::setLed()
@@ -67,10 +64,11 @@ void BAGpio::clearLed()
 	digitalWrite(USR_LED_ID, 0);
 	m_ledState = 0;
 }
-void BAGpio::toggleLed()
+int BAGpio::toggleLed()
 {
 	m_ledState = ~m_ledState;
 	digitalWrite(USR_LED_ID, m_ledState);
+	return m_ledState;
 }
 
 

src/BAGpio.h

@@ -1,10 +1,11 @@
-/*
- * BAGpio.h
+/**************************************************************************//**
+ *  BAGPio is convenience class for accessing the the various GPIOs available
+ *  on the Teensy Guitar Audio series boards.
  *
- *  Created on: May 22, 2017
- *      Author: slascos
- *
- *  This program is free software: you can redistribute it and/or modify
+ *  @file
+ *  @author Steve Lascos
+ *  @company Blackaddr Audio
+ *  @copyright This program is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
  *  the Free Software Foundation, either version 3 of the License, or
  *  (at your option) any later version.*
@@ -16,17 +17,18 @@
  *
  *  You should have received a copy of the GNU General Public License
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-*/
+ *****************************************************************************/
 
 #ifndef SRC_BAGPIO_H_
 #define SRC_BAGPIO_H_
 
 namespace BAGuitar {
 
-//constexpr int NUM_GPIO = 10;
-
-constexpr uint8_t USR_LED_ID = 16;
+constexpr uint8_t USR_LED_ID = 16; ///< Teensy IO number for the user LED.
 
+/**************************************************************************//**
+ * GPIOs and Testpoints are accessed via enumerated class constants.
+ *****************************************************************************/
 enum class GPIO : uint8_t {
 	GPIO0 = 2,
 	GPIO1 = 3,
@@ -41,39 +43,47 @@ enum class GPIO : uint8_t {
 	TP1 = 34,
 	TP2 = 33
 };
-//// J3 - GPIO Header
-//constexpr int GPIO0 = 2;
-//constexpr int GPIO1 = 3;
-//constexpr int GPIO2 = 4;
-//constexpr int GPIO3 = 6;
-//
-//// J6 - GPIO Header
-//constexpr int GPIO4 = 12;
-//constexpr int GPIO5 = 32;
-//constexpr int GPIO6 = 27;
-//constexpr int GPIO7 = 28;
-
-
-// Test points
-//constexpr int TP1 = 34;
-//constexpr int TP2 = 33;
 
+/**************************************************************************//**
+ * BAGpio provides a convince class to easily control the direction and state
+ * of the GPIO pins available on the TGA headers.
+ * @details you can always control this directly with Arduino commands like
+ * digitalWrite(), etc.
+ *****************************************************************************/
 class BAGpio {
 public:
 	BAGpio();
 	virtual ~BAGpio();
 
+	/// Set the direction of the specified GPIO pin.
+	/// @param gpioId Specify a GPIO pin such as GPIO::GPIO0
+	/// @param specify direction as INPUT or OUTPUT which are Arduino constants
 	void setGPIODirection(GPIO gpioId, int direction);
+
+	/// Set the state of the specified GPIO to high
+	/// @param gpioId gpioId Specify a GPIO pin such as GPIO::GPIO0
 	void setGPIO(GPIO gpioId);
+
+	/// Clear the state of the specified GPIO pin.
+	/// @param gpioId gpioId Specify a GPIO pin such as GPIO::GPIO0
 	void clearGPIO(GPIO gpioId);
-	void toggleGPIO(GPIO gpioId);
 
+	/// Toggle the state of the specified GPIO pin. Only works if configured as output.
+	/// @param gpioId gpioId Specify a GPIO pin such as GPIO::GPIO0
+	/// @returns the new state of the pin
+	int toggleGPIO(GPIO gpioId);
+
+	/// Turn on the user LED
 	void setLed();
+
+	/// Turn off the user LED
 	void clearLed();
-	void toggleLed();
+
+	/// Toggle the stage of the user LED
+	/// @returns the new stage of the user LED.
+	int toggleLed();
 
 private:
-	//bool m_gpioState[NUM_GPIO];
 	uint8_t m_ledState;
 };
 

src/BAGuitar.h

@@ -25,16 +25,11 @@
 #include "BASpiMemory.h"
 #include "BAGpio.h"
 
+/**************************************************************************//**
+ * BAGuitar is a namespace/Library for Guitar processing from Blackaddr Audio.
+ *****************************************************************************/
 namespace BAGuitar {
 
-#define AUDIO_BLOCK_SIZE 128
-
-// Spi Memory
-constexpr int SPI_MAX_ADDR = 131071;
-
-// LED
-constexpr int usrLED = 16;
-
 }
 
 #endif /* SRC_BATGUITAR_H_ */

src/BASpiMemory.cpp

@@ -61,6 +61,7 @@ BASpiMemory::BASpiMemory(SpiDeviceId memDeviceId, uint32_t speedHz)
 	m_Init();
 }
 
+// Intitialize the correct Arduino SPI interface
 void BASpiMemory::m_Init()
 {
 
@@ -93,9 +94,9 @@ void BASpiMemory::m_Init()
 }
 
 BASpiMemory::~BASpiMemory() {
-	// TODO Auto-generated destructor stub
 }
 
+// Single address write
 void BASpiMemory::write(int address, int data)
 {
 
@@ -131,6 +132,7 @@ void BASpiMemory::write(int address, int data)
 	digitalWrite(m_csPin, HIGH);
 }
 
+// single address read
 int BASpiMemory::read(int address)
 {
 

src/BASpiMemory.h

@@ -1,10 +1,11 @@
-/*
- * BASpiMemory.h
+/**************************************************************************//**
+ *  BASpiMemory is convenience class for accessing the optional SPI RAMs on
+ *  the GTA Series boards.
  *
- *  Created on: May 22, 2017
- *      Author: slascos
- *
- *  This program is free software: you can redistribute it and/or modify
+ *  @file
+ *  @author Steve Lascos
+ *  @company Blackaddr Audio
+ *  @copyright This program is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
  *  the Free Software Foundation, either version 3 of the License, or
  *  (at your option) any later version.*
@@ -16,7 +17,7 @@
  *
  *  You should have received a copy of the GNU General Public License
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-*/
+ *****************************************************************************/
 #ifndef SRC_BASPIMEMORY_H_
 #define SRC_BASPIMEMORY_H_
 
@@ -24,25 +25,50 @@
 
 namespace BAGuitar {
 
+constexpr int SPI_MAX_ADDR = 131071; ///< Max address size per chip
+
+/**************************************************************************//**
+ *  This class enumerates access to the two potential SPI RAMs.
+ *****************************************************************************/
+
 enum class SpiDeviceId {
 	SPI_DEVICE0,
 	SPI_DEVICE1
 };
 
+/**************************************************************************//**
+ *  This wrapper class uses the Arduino SPI (Wire) library to access the SPI ram.
+ *  @details The purpose of this class is primilary for functional testing since
+ *  it currently support single-word access. High performance access should be
+ *  done using DMA techniques in the Teensy library.
+ *****************************************************************************/
 class BASpiMemory {
 public:
 	BASpiMemory() = delete;
+	/// Create an object to control either MEM0 (via SPI1) or MEM1 (via SPI2).
+	/// @details default is 20 Mhz
+	/// @param memDeviceId specify which MEM to controlw with SpiDeviceId.
 	BASpiMemory(SpiDeviceId memDeviceId);
+	/// Create an object to control either MEM0 (via SPI1) or MEM1 (via SPI2)
+	/// @param memDeviceId specify which MEM to controlw with SpiDeviceId.
+	/// @param speedHz specify the desired speed in Hz.
 	BASpiMemory(SpiDeviceId memDeviceId, uint32_t speedHz);
 	virtual ~BASpiMemory();
 
+	/// write a single data word to the specified address
+	/// @param address the address in the SPI RAM to write to
+	/// @param data the value to write
 	void write(int address, int data);
+
+	/// read a single data word from the specified address
+	/// @param address the address in the SPI RAM to read from
+	/// @return the data that was read
 	int  read(int address);
 
 private:
-	SpiDeviceId m_memDeviceId;
-	uint8_t m_csPin;
-	SPISettings m_settings;
+	SpiDeviceId m_memDeviceId; // the MEM device being control with this instance
+	uint8_t m_csPin; // the IO pin number for the CS on the controlled SPI device
+	SPISettings m_settings; // the Wire settings for this SPI port
 	void m_Init();
 
 };