blink-cylon.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-cylon.dox
\page blink_cylon Cylon Eyes Example

This example shows how to use the ChaseLEDs class to simulate the Cylon
eye effect from Battlestar Galactica.  Digital outputs are used to drive
six LED's in a back and forth motion, using the following schematic:

\image html Cylon.png

We start by including the ChaseLEDs class:

\dontinclude BlinkLED/examples/Cylon/Cylon.ino
\skip ChaseLEDs.h
\until ChaseLEDs.h

The next step is to define the pins that the chase will run over:

\dontinclude BlinkLED/examples/Cylon/Cylon.ino
\skip byte pins
\until cylonEyes

The chase runs from the first pin to the sixth pin and back again,
with each LED lit for 100 milliseconds before moving onto the next one.
To complete the example, we need to call ChaseLEDs::loop() each time
around our main loop to cause the chase to run:

\dontinclude BlinkLED/examples/Cylon/Cylon.ino
\skip loop()
\until }

While this example uses only six pins, it can be easily extended to any
number of pins by modifying the \c pins array and altering the schematic
accordingly.

So far we are chasing only a single LED.  We could change this to chase
two adjacent LED's instead by defining a new \c CylonChase class that
inherits from ChaseLEDs:

\dontinclude BlinkLED/examples/Cylon2/Cylon2.ino
\skip class CylonChase
\until };

The important part is the implementation of the <tt>advance()</tt> method,
which overrides ChaseLEDs::advance() to provide our own scheme for lighting
the LED's each time the chase advances.  We use ChaseLEDs::previousPin() to
get the pin that is 2 steps back in the sequence, set it to LOW, and then
set the previous pin (1 step back) and the next pin to HIGH.  All that
remains is to change our chase initialization to use the new class:

\dontinclude BlinkLED/examples/Cylon2/Cylon2.ino
\skip byte pins
\until cylonEyes

We can do even better than this.  Instead of fully lighting both LED's,
we could instead use the PWM outputs to dim the previous pin, creating a
kind of "trailing flame" effect:

\dontinclude BlinkLED/examples/Cylon3/Cylon3.ino
\skip advance(
\until }

The current chase is fixed at 100 milliseconds per LED, which takes a full
second to run the sequence.  An alternative to hard-wiring the chase
rate is to hook up a 10K potentiometer to the A0 analog input:

\image html Cylon4.png

We then modify the <tt>advance()</tt> method to read the new chase rate
from the potentiometer each time the LED advances:

\dontinclude BlinkLED/examples/Cylon4/Cylon4.ino
\skip advance(
\until }

The full source code for the final version of the example follows:

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