added some documentation

Author: michaelkamprath

README.md

@@ -56,7 +56,7 @@ When constructing a matrix driver, you need to tell it a few details:
 * The matrix's size in rows and columns
 * Whether the shift registers used for controlling columns should be set to `HIGH` or `LOW` to turn on the column. 
 * Whether the shift registers used for controlling rows should be set to `HIGH` or `LOW` to turn on the row
-* The pin which will be used to send the latch signle.
+* The pin which will be used to send the latch signal.
 
 #### LEDMatrix
 The `LEDMatrix` driver is used for matrices of single color LEDs. This drive uses a `MutableGlyph` as its image buffer.

src/BaseLEDMatrix.cpp

@@ -21,9 +21,6 @@
 #define ICACHE_RAM_ATTR
 #endif
 
-#define SPICACHEPADBITS(rows,cols)	(rows*3 + cols)%8 ? 8 - (rows*3 + cols)%8 : 0
-#define SPICACHESIZE(rows,cols)	1+((rows*3 + cols)-1)/8
-
 const unsigned long UPDATE_INTERVAL = 2000;
 
 static BaseLEDMatrix* gSingleton = NULL;
@@ -110,7 +107,7 @@ void BaseLEDMatrix::action() {
 	} 
 }
 
-void BaseLEDMatrix::shiftOutCurrentRow( void ) {
+ICACHE_RAM_ATTR void BaseLEDMatrix::shiftOutCurrentRow( void ) {
 	this->shiftOutRow( _scanRow, _scanPass );
 }
 

src/BaseLEDMatrix.h

@@ -56,8 +56,23 @@ class BaseLEDMatrix : public TimerAction {
 
 	virtual unsigned int multiplier5microseconds( size_t frame ) const;
 public:
-  
 
+	/**
+	 *	Constructs the base LED matrix controller object.
+	 *
+	 *	@param rows the number of  rows in the LED matrix. Rows are expected to have
+	 *	            shared power to the LEDs.
+	 *	@param columns the number of columns in the LED matrix.
+	 *	@param columnBitWidth the number of bits needed to represent one physical LED in 
+	 *              a column. E.g., and RGB LED needs 3 bits.
+	 *	@param pwmCycleScanCount the number of row scans needed for the PWM cycle of the matrix.
+	 *	@param columnControlBitOn what value a column bit should be set to to the column on.
+	 *	@param rowControlBitOn what value a row bit should be set to to turn the row on. 
+	 *               E.g. of the row is common anode and a PNP transistor is being use 
+	 *               to switch power to the row, the row bit likely needs to be LOW to
+	 *               cause the transistor to power the row.
+	 *  @param slavePin which ard pin is used for the latch signal.
+	 */
 	BaseLEDMatrix(
 			unsigned int rows,
 			unsigned int columns,
@@ -73,18 +88,60 @@ class BaseLEDMatrix : public TimerAction {
 		);
 	virtual ~BaseLEDMatrix();
 
+	/**
+	 * Should be called before any operations against this object is performed. Child
+	 * classes implementing matrix-type specific implementation should call this parent 
+	 * class implementation of setup() before doing their own setup work.
+	 */
 	virtual void setup();  
 
+	/**
+	 * Increments the draw lock. While a matrix has a non-zero draw lock, any changes to 
+	 * the image() buffer will not be pass through to the matrix scan buffer.
+	 */
 	void startDrawing(void)   			{ _isDrawingCount++; }
+	
+	/**
+	 * Decrements the draw lock. All calls to startDrawing() should be balanced with a 
+	 * call to stopDrawing().
+	 */
 	void stopDrawing(void)    			{ _isDrawingCount--; if (_isDrawingCount < 0) { _isDrawingCount = 0; }}
+	
+	
+	/**
+	 * Returns true is a draw lock is active.
+	 */
 	bool isDrawing(void) const			{ return (_isDrawingCount > 0); }
 
+	/**
+	 * Returns the number of rows in this matrix.
+	 *
+	 * @return the number of rows in the matrix.
+	 */
 	unsigned int rows() const          			{ return _rows; }
+
+	/**
+	 * Returns the number of columns in this matrix.
+	 *
+	 * @return the number of columns in the matrix.
+	 */
 	unsigned int columns() const       			{ return _columns; }
 
+	/**
+	 * Begins the row scan timer interrupt, which in turn starts sending data through the 
+	 * SPI interface to the LED matrix.
+	 */
 	void startScanning(void);
+
+	/**
+	 * Stops the LED matrix row scan timmer interrupt.
+	 */
 	void stopScanning(void);
 
+	/**
+	 * This methods are "private" to this class but have to be declared public so 
+	 * the timer interrupt can access them.
+	 */
 	void shiftOutCurrentRow(void);
 	unsigned int nextTimerInterval(void) const;
 	void incrementScanRow( void );

src/LEDMatrix.h

@@ -42,6 +42,19 @@ class LEDMatrix : public BaseLEDMatrix {
 public:
 
 
+	/**
+	 *	Constructs a mono-color LED matrix controller object.
+	 *
+	 *	@param rows the number of  rows in the LED matrix. Rows are expected to have
+	 *	            shared power to the LEDs.
+	 *	@param columns the number of columns in the LED matrix.
+	 *	@param columnControlBitOn what value a column bit should be set to to the column on.
+	 *	@param rowControlBitOn what value a row bit should be set to to turn the row on. 
+	 *               E.g. of the row is common anode and a PNP transistor is being use 
+	 *               to switch power to the row, the row bit likely needs to be LOW to
+	 *               cause the transistor to power the row.
+	 *  @param slavePin which ard pin is used for the latch signal.
+	 */
 	LEDMatrix(
 			int rows,
 			int columns,
@@ -55,9 +68,26 @@ class LEDMatrix : public BaseLEDMatrix {
 		);
 	virtual ~LEDMatrix();
 
+	/**
+	 * Should be called before any operations against this object is performed.
+	 */
 	virtual void setup();
 
+	/**
+	 * Returns the image buffer for this matrix object. This is the 
+	 * image buffer that drawing should be done to.
+	 *
+	 * @return a MutableGlyph object reference that is the matrix's image buffer.
+	 */ 
 	MutableGlyph& image(void)				{ return *_screen_data; }
+
+	/**
+	 * Returns a const reference to the image buffer for this matrix object. This is the 
+	 * image buffer that drawing should be done to, but is const here and thus should
+	 * be only read from.
+	 *
+	 * @return a const MutableGlyph object reference that is the matrix's image buffer.
+	 */ 
 	const MutableGlyph& image(void) const	{ return *_screen_data; }
 };
 

src/RGBLEDMatrix.h

@@ -53,7 +53,21 @@ class RGBLEDMatrix : public BaseLEDMatrix {
 	virtual unsigned int multiplier5microseconds( size_t frame ) const;
 public:
 
-
+	/**
+	 *	Constructs an RGB LED matrix controller object.
+	 *
+	 *	@param rows the number of  rows in the LED matrix. Rows are expected to have
+	 *	            shared power to the LEDs.
+	 *	@param columns the number of columns in the LED matrix.
+	 *	@param bitLayout an RGBLEDBitLayout enum indicating how the RGB bits are arranged 
+	 *              in each row.
+	 *	@param columnControlBitOn what value a column bit should be set to to the column on.
+	 *	@param rowControlBitOn what value a row bit should be set to to turn the row on. 
+	 *               E.g. of the row is common anode and a PNP transistor is being use 
+	 *               to switch power to the row, the row bit likely needs to be LOW to
+	 *               cause the transistor to power the row.
+	 *  @param slavePin which ard pin is used for the latch signal.
+	 */
 	RGBLEDMatrix(
 			int rows,
 			int columns,
@@ -70,7 +84,21 @@ class RGBLEDMatrix : public BaseLEDMatrix {
 
 	virtual void setup();
 
+	/**
+	 * Returns the image buffer for this matrix object. This is the 
+	 * image buffer that drawing should be done to.
+	 *
+	 * @return a MutableRGBImage object reference that is the matrix's image buffer.
+	 */ 
 	MutableRGBImage& image(void)				{ return *_screen_data; }
+
+	/**
+	 * Returns a const reference to the image buffer for this matrix object. This is the 
+	 * image buffer that drawing should be done to, but is const here and thus should
+	 * be only read from.
+	 *
+	 * @return a const MutableRGBImage object reference that is the matrix's image buffer.
+	 */ 
 	const MutableRGBImage& image(void) const	{ return *_screen_data; }
 
 };

src/TimerAction.h

@@ -19,11 +19,18 @@
 #ifndef __TIMERACTION_H__
 #define __TIMERACTION_H__
 
+/**
+ * TimerAction is a class that manages the timed firing of an action. Timing is 
+ * approximate and "no sooner than" the period delay.  To use, subclass this class
+ * and override the protected action() method to implement the periodic action, then call 
+ * the loop() method to an instance of the the subclass that has been constructed with the
+ * desired timing interval. The TimerAction class will call the action() method repeatedly
+ * after the first call to loop once the timing interval has passed.
+ */
 class TimerAction {
 private:
 	unsigned long _interval;
 	unsigned long  _lastLoopMicros;
-	unsigned long  _actionAverageMicros;
 
 	bool _isActive;
 
@@ -47,7 +54,6 @@ class TimerAction {
 public:
   TimerAction(unsigned long intervalMicros)
   		: 	_interval(intervalMicros),
-  			_actionAverageMicros(0),
   			_isActive(true)
   	{
 		_interval = intervalMicros;
@@ -60,9 +66,6 @@ class TimerAction {
 			if ( _interval <= delta ) {
 				_lastLoopMicros = micros();
 				this->action();
-				// at this point this->timeSinceLast() is the time it took to 
-				// do the action;
-				_actionAverageMicros = (_actionAverageMicros+this->timeSinceLast())/2;
 			}
 		}
 	}