152 lines
6.8 KiB
Plaintext
152 lines
6.8 KiB
Plaintext
Avocamentum Galactica (http://douglasruuska.com/avocamentum-galactica/), the
|
|
galaxy, a kinetic sculpture by Douglas Ruuska with electronics by Joshua
|
|
Krueger, features at its core a PIC18F452 microcontroller running a pattern
|
|
generator written in C. The pattern generator creates a serial broadcast that
|
|
is received by the LED drivers to produce the color effects seen across the
|
|
fiber optic stars of the galaxy's spiral arms. This project is that pattern
|
|
generator.
|
|
|
|
The star fibers are driven by 42 individually addressable RGB LEDs at 24 bits
|
|
per pixel color resolution. There are 21 RGB LEDs per arm, aligned roughly
|
|
sequentially.
|
|
|
|
The software project consists of two build targets. The primary target is the
|
|
galaxy's PIC and uses the serial port and galaxy hardware as the display output.
|
|
This code was written using the C90 standard (with extensions) for the MicroChip
|
|
XC8 compiler (v1.33). The secondary target was written to allow the code to be
|
|
run on a general purpose computer with an emulated output shown in a graphical
|
|
window. The build instructions in this file apply to the emulator target.
|
|
|
|
|
|
To make this project in a build directory separate from the source:
|
|
|
|
1) Extract the archive somewhere convenient (like your home directory or
|
|
Desktop):
|
|
|
|
tar -zxvf galaxyEmulator-0.4.0.20141104.tgz
|
|
|
|
Or, using git (preferred method):
|
|
|
|
git clone https://github.com/argyle77/galaxyMaster.git EmulatorTarget
|
|
|
|
2) Enter the extracted directory and make a build directory.
|
|
|
|
cd EmulatorTarget
|
|
mkdir build
|
|
cd build
|
|
|
|
3) Run cmake to generate the build scripts.
|
|
|
|
cmake ..
|
|
|
|
4) Run make to compile and link the project.
|
|
|
|
make
|
|
|
|
5) Once build is successful, run galaxyEmulator in the build/bin directory:
|
|
|
|
bin/galaxyEmulator
|
|
|
|
Hints:
|
|
|
|
You may need to install the following packages:
|
|
build-essential, cmake, libsdl2-gfx-dev, git
|
|
|
|
To do this in an Ubuntu derivative environment, run the following command:
|
|
sudo aptitude install build-essential cmake libsdl2-gfx-dev git
|
|
|
|
|
|
When looking at this code, keep in mind that there are two build targets.
|
|
Emulator code is demarcated in the source files using the c pre-processor
|
|
define, "EMULATOR" (source enclosed in #ifdef EMULATOR / #endif), which the
|
|
cmake build process automatically activates. It is sort of like having two
|
|
overlapping programs that share a lot of common code. The emulator outputs the
|
|
patterns to a window so that you can see a preview without needing the galaxy
|
|
hardware on hand. I've broken the code into several files. Here is a manifest:
|
|
|
|
|
|
README.txt - This file. The project build instructions and the file manifest.
|
|
|
|
LICENSE.txt - Copyright notice and license for the project source and
|
|
documentation.
|
|
|
|
CMakeLists.txt - These files contain the cmake build instructions. Don't worry
|
|
about them unless you want to change the version numbers.
|
|
|
|
version.h.in - Totally unimportant. Used for versioning.
|
|
|
|
deviceConfig.h - Lots of defines for setting up the PIC hardware. Not important
|
|
for writing pattern code.
|
|
|
|
galaxyConfig.h - Definitions specific to the galaxy. Some convenient constants
|
|
and typdefs in here.
|
|
|
|
init.h, init.c - PIC hardware initialization functions. Unimportant.
|
|
|
|
display.h, display.c - Functions to write the pattern out to the LEDs. You won't
|
|
need to change any of this.
|
|
|
|
master.c - Contains main(). Calls the pattern generators. You probably won't
|
|
need to change any of this.
|
|
|
|
patternSupport.h, patternSupport.c - Contains helper functions that are useful
|
|
in generating patterns. Currently available are:
|
|
FadeChannel - Increases or decreases the intensity of all the LEDs of a
|
|
given color channel.
|
|
Shift - Rotates the color of all the LEDs up or down the arms by one step
|
|
ColorAll - Set the color of all the pixels on the galaxy to a chosen
|
|
color.
|
|
GetRandomColor - Returns a random color in accordance with a selected
|
|
mode.
|
|
Examples of how these functions are used can be found in pattern.c
|
|
|
|
pattern.h, pattern.c - A collection of pattern generation functions. This is
|
|
where you put your pattern code. There are 6 examples already in this
|
|
file. Add new patterns to patternList in pattern.h to get them to run.
|
|
|
|
|
|
Pattern functions manipulate the galaxy->pixels array one step at a time. The
|
|
loop in master.c calls your function over and over again and sends the results
|
|
to the serial port (or to the emulator window) each time. The iterations field
|
|
in the patternList tells the program how many times to call a particular pattern
|
|
function before moving on to the next one. Patterns have access to the "initial"
|
|
variable, which is set to TRUE the first time a new pattern function is called,
|
|
and FALSE every time thereafter. Pattern functions can use static variables to
|
|
keep track of state information between calls. Code pieces that you write that
|
|
might be useful for multiple patterns may be candidates for inclusion as
|
|
functions in patternSupport.c.
|
|
|
|
The emulator timing is not exact and may be thought of as suggestive of what a
|
|
pattern might look like on the galaxy itself. When run, the emulator will print
|
|
out a list of available key-presses to the terminal window so that you'll know
|
|
how to use it.
|
|
|
|
The code, as it stands, occupies 22% of the PIC data memory (RAM) and 30% of the
|
|
PIC program space (flash). The PIC can use floating point variables and
|
|
functions, but these are very memory and CPU intensive and may not result in the
|
|
timing you desire. The PIC only has 1536 bytes of RAM, so keep in mind that
|
|
though the emulator target can compile and run anything (I personally have giga-
|
|
bytes of RAM available to it), the galaxy itself is somewhat more limited.
|
|
|
|
I built this project using the Linux Mint operating system, which is an Ubuntu
|
|
derivative. It should be very easy to get it running on any Ubuntu derivative,
|
|
and relatively easy to get it running on other popular linux distributions.
|
|
With the right software and libraries installed, you may even be able to build
|
|
it in Windows or MAC (thanks to cmake), but I have little experience programming
|
|
for either of these platforms.
|
|
|
|
To build the code for the PIC target rather than the emulator target, I suggest
|
|
obtaining a copy of MPLAB X IDE:
|
|
http://www.microchip.com/pagehandler/en-us/family/mplabx/
|
|
as well as the XC8 compiler:
|
|
http://www.microchip.com/pagehandler/en-us/devtools/mplabxc/home.html
|
|
both of which are available for multiple operating systems at no charge from
|
|
MicroChip. Create a simple Microchip Embedded, standalone project with the
|
|
PIC18F452 and the XC8 compiler selected and add the source files to your
|
|
project. There should be no special settings or flags required for compilation
|
|
in this environment. If you use a different PIC for this project, you'll find
|
|
most of the stuff you need to change in deviceConfig.h
|
|
|
|
This project's use of git and presence on github are the author's efforts to
|
|
learn to use these tools.
|