Support class for Charlieplexing large numbers of LED's

doc/Doxyfile

@@ -688,7 +688,7 @@ EXAMPLE_RECURSIVE      = NO
 # directories that contain image that are included in the documentation (see
 # the \image command).
 
-IMAGE_PATH             = ../libraries/BlinkLED/examples/Cylon ../libraries/BlinkLED/examples/Cylon4 ../libraries/BlinkLED/examples/StarTrek ../libraries/LCD/examples/HelloWorld ../libraries/LCD/examples/Form ../libraries/RTC/examples/AlarmClock ../libraries/DMD
+IMAGE_PATH             = ../libraries/BlinkLED/examples/Cylon ../libraries/BlinkLED/examples/Cylon4 ../libraries/BlinkLED/examples/StarTrek ../libraries/BlinkLED/examples/Charlieplex ../libraries/LCD/examples/HelloWorld ../libraries/LCD/examples/Form ../libraries/RTC/examples/AlarmClock ../libraries/DMD
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

doc/blink-charlieplex.dox

@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2012 Southern Storm Software, Pty Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+\file blink-charlieplex.dox
+\page blink_charlieplex Charlieplexing Example
+
+<a href="http://en.wikipedia.org/wiki/Charlieplexing">Charlieplexing</a>
+is a technique for multiplexing large numbers of LED's on a small
+number of microcontroller output pins.  LED's are arranged in
+complementary pairs and managed by the Charlieplex class.  For this
+example we are going to use 3 output pins to drive 6 LED's:
+
+\image html charlieplexeg.png
+
+The technique can be expanded to even larger numbers of LED's.
+See the documentation for the Charlieplex class for a description of
+how to connect up larger numbers of pins in a Charlieplexed arrangement.
+
+The first step is to initialize a Charlieplex object with the output
+pins it needs to drive:
+
+\dontinclude BlinkLED/examples/Charlieplex/Charlieplex.pde
+\skip #include
+\until charlie
+
+Then in <tt>setup()</tt> we use Charlieplex::setLed() and
+Charlieplex::setPwmLed() to set three of the six LED's to
+the desired output values:
+
+\dontinclude BlinkLED/examples/Charlieplex/Charlieplex.pde
+\skip setup
+\until }
+
+Charlieplexing can only light a single LED at a time.  It is therefore
+necessary to constantly scan the entire LED array, alternatively turning
+LED's on and off.  The user's peristence of vision fills in the gaps.
+To do this, we call Charlieplex::loop():
+
+\dontinclude BlinkLED/examples/Charlieplex/Charlieplex.pde
+\skip loop
+\until }
+
+The downside of Charlieplexing is that when multiple LED's are lit, each LED
+will appear to be dimmer than if only a single LED was lit.  This can be
+counteracted by using brighter LED's or smaller resistors.  The danger with
+smaller resistors is that if the program crashes or locks up for some reason,
+a large amount of continuous current could be fed through a single LED and
+cause it to exceed its maximum rating and burn out.
+
+The full source code for the example follows:
+
+\include BlinkLED/examples/Charlieplex/Charlieplex.pde
+
+A more complex example that performs a LED chase over the 6 LED's follows:
+
+\include BlinkLED/examples/CharlieplexChase/CharlieplexChase.pde
+*/

doc/mainpage.dox

@@ -56,11 +56,15 @@ to draw and animate bitmaps.
 to a output pin.
 \li ChaseLEDs class that simplifies the process of performing a LED chase
 over several output pins.
+\li Charlieplex class that manages a matrix of LED's arranged in a
+<a href="http://en.wikipedia.org/wiki/Charlieplexing">Charlieplexing</a>
+arrangement.
 \li \ref blink_blink "Blink" example of using BlinkLED.
 \li \ref blink_cylon "Cylon" example of using ChaseLEDs to simulate
 the Cylon eye effect from Battlestar Galactica.
 \li \ref blink_startrek "StarTrek" example for lighting a starship
 Enterprise model kit.
+\li \ref blink_charlieplex "Charlieplex" example.
 
 \section main_I2C I2C Utility Library