arduinolibs/doc/blink-startrek.dox

/*
 * 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.ino
\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.ino
\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.ino
\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.ino
\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.ino
\skip advance(byte
\until }

The full source code for the example, including the "opposite pairs"
effect, follows:

\include BlinkLED/examples/StarTrek2/StarTrek2.ino
*/