Document StarTrek example

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
+IMAGE_PATH             = ../libraries/BlinkLED/examples/Cylon ../libraries/BlinkLED/examples/Cylon4 ../libraries/BlinkLED/examples/StarTrek
 
 # 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-startrek.dox

@@ -0,0 +1,165 @@
+/*
+ * 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-startrek.dox
+\page blink_startrek Star Trek Example
+
+This example shows how to use the BlinkLED and ChaseLEDs classes to
+simulate the running lights on the starship Enterprise from Star Trek.
+This can be used as the basis for lighting a model kit.  It is
+recommended that you read the \ref blink_blink "Blink" and
+\ref blink_cylon "Cylon" tutorials first.
+
+There are four categories of lights on the Enterprise:
+
+\li Static lights in windows, engines, and the deflector dish.
+We don't handle those in this example as we assume that they are
+connected directly to the power supply with no computer control.
+\li Red and green navigation lights on the left and right of the saucer,
+and on the left and right warp nacelles, typically with a 1 second period.
+The red light is on the left as viewed from the back of the model.
+\li White strobe light behind the bridge and on the warp nacelles
+that comes on briefly every second.
+\li Nacelle lights that perform a circular LED chase in the front of the
+nacelles to create the warp engine twirl effect.
+
+Different models of the Enterprise have the lights in different places,
+and the period of flashing can vary from TV show to show, and sometimes
+from episode to episode.  There isn't a definitive set of blink timings
+or number of LED's in the nacelle chase.  The sketch has a number of
+configurable parameters that gives the user the freedom to choose which
+show and/or episode they wish to treat as "canonical" for their model.
+
+We start by building a test circuit with a small number of LED's for
+each of the three categories (navigation, strobe, and nacelles):
+
+\image html StarTrek.png
+
+This won't be the final circuit for the model, but building it on a
+breadboard will help with the initial prototyping stages and choosing
+the appropriate blink timings:
+
+\image html StarTrekBreadboard.png
+
+Alternatively, the test circuit can be built on a prototyping shield
+with the chase LED's in a circular arrangement to simulate how they will
+look when placed in the front of the model's warp nacelles:
+
+\image html StarTrekShield.png
+
+Now that we have a circuit, let's configure the red navigation LED on AOUT2
+using the BlinkLED class, to blink with a period of 1000 milliseconds on,
+1000 milliseconds off:
+
+\dontinclude BlinkLED/examples/StarTrek/StarTrek.pde
+\skip <BlinkLED.h>
+\until <BlinkLED.h>
+\skip NAV_LIGHTS
+\until NAV_LIGHTS
+\skip NAV_LIGHTS_ON
+\until NAV_LIGHTS_OFF
+\skip navLights
+\until navLights
+
+We repeat the process for the strobe LED on AOUT3, with a period of
+70 milliseconds on, and 830 milliseconds off:
+
+\dontinclude BlinkLED/examples/StarTrek/StarTrek.pde
+\skip STROBE_LIGHT
+\until STROBE_LIGHT
+\skip STROBE_LIGHT_ON
+\until STROBE_LIGHT_OFF
+\skip strobeLight
+\until strobeLight
+
+We also need to arrange for BlinkLED::loop() to be called from the
+application's main <tt>loop()</tt> function:
+
+\code
+void loop() {
+  navLights.loop();
+  strobeLight.loop();
+}
+\endcode
+
+If you run the sketch at this point, you should see the navigation and
+strobe LED's blink with the selected rates.
+
+Next is the twirl effect in the warp nacelles, using the ChaseLEDs
+class.  We are actually going to inherit from ChaseLEDs to create a
+custom LED chaser that reads the chase rate from AIN0 and uses PWM
+outputs to create a trailing flame effect.  See the
+\ref blink_cylon "Cylon" example for more information on creating
+custom effects with ChaseLEDs.
+
+\dontinclude BlinkLED/examples/StarTrek/StarTrek.pde
+\skip NACELLE_CHASE_LEN
+\until NacelleChaseLEDs nacelleChase
+
+We also need to add a call to ChaseLEDs::loop() to the application's
+main loop:
+
+\dontinclude BlinkLED/examples/StarTrek/StarTrek.pde
+\skip loop()
+\until }
+
+Running the sketch now should cause the six LED's in the nacelle
+sequence to chase, in addition to the navigation and strobe LED's.
+The 10K potentiometer can be used to select the desired chase rate.
+This completes the test circuit, and will allow you to fiddle with
+the blink timings and chase rate until you are happy with the result.
+
+We've made provision in this sketch for six outputs in the chase,
+but some models may only use three or five.  The <tt>NACELLE_CHASE_LEN</tt>
+parameter controls the length of the chase.
+
+With three outputs, the LED's can be arranged in opposite pairs,
+lighting two LED's at a time.  The following circuit demonstrates
+how three outputs can be used to drive six LED's:
+
+\image html ThreeChase.png
+
+You will need two of these circuits, for the left and right warp nacelles.
+The transistor drivers reduce the current load on the Arduino CPU and
+provide the option to drive the LED's from 12V instead of 5V.
+
+It is recommended that you use transistor drivers for the navigation and
+strobe lights as well as there will be multiple LED's on each output in a
+real model.  For example, there will be at least three each of the red
+and green navigation lights: the top of the saucer section, the bottom of
+the saucer section, and the top of the warp nacelle.  Using a 12V supply
+will make it easier to string lots of LED's together in series.
+
+Other nacelle effects are possible by modifying the <tt>advance()</tt> method
+in the sketch.  For example, the "opposite pairs" effect with 3 outputs
+can also be done with 6 outputs and the following modification to the sketch:
+
+\dontinclude BlinkLED/examples/StarTrek2/StarTrek2.pde
+\skip advance(byte
+\until }
+
+The full source code for the example, including the "opposite pairs"
+effect, follows:
+
+\include BlinkLED/examples/StarTrek2/StarTrek2.pde
+*/

doc/mainpage.dox

@@ -44,5 +44,7 @@ over several output pins.
 \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.
 
 */