Overview of Programming the Colorduino

The sketches used with the Colorduino arrays (or another other matrix of LEDs)
make heavy use of arrays. Be sure you know how to program with arrays
(see, e.g., the packet on arrays before proceeding.

To use the Colorduino, check that your libraries folder contains the required
libraries. Use Sketch->Include Libraries, and look for both Colorduino
and Colorduino_FW.

The Colorduino Library

This library defines a new class (Colorduino) with 2 utility methods needed in setup():

Colorduino.Init()
Colorduino.SetWhiteBal()

It also includes a third method which is needed in your loop() function when you want
to move an image you’d been building in memory to the RGB array itself.

Colorduino.FlipPage()

The Colorduino_FW Library

This library defines 31 functions that make it easy to achieve special effects with your
Colorduino:

// Basic Functions
void clearScreen(); 
void fillScreen();
void plot(int8_t, int8_t);
void bg_plot(int8_t, int8_t);

// Text Functions
void drawChar(int8_t, int8_t,unsigned char);
void drawCharTransparent(int8_t, int8_t, unsigned char);
void getChar(String*, unsigned char, unsigned char, int8_t, int8_t);

// Geometric Shapes
void drawCircle(int8_t, int8_t, int8_t);
void fillCircle(int8_t, int8_t, int8_t);
void fillRect(int8_t, int8_t, int8_t, int8_t);
void drawLine(int8_t, int8_t, int8_t, int8_t);

// Image Functions
void drawImage(String* , int8_t, int8_t);
void drawImageTransparent(String*, int8_t, int8_t);
void dropImage(String*, String*, String*);

// Special Effects
void scroll(String, int, int);
void scrollDown(String*, String*, String*, uint8_t);
void scrollLeft(String*, String*, String*, uint8_t);
void scrollOverImg(String, String*, int, int);
void letItSnow(String*, String*, String*);
void rotateLeft(String*, String*, String*);
void spinImageLeft(String*, String*, String*);
void wipeImageLeft(String*, String*, String*);

// Utility Functions
void saveColor();
void restoreColor();
void setBgColor(uint8_t);
void setColor(uint8_t);
boolean isBgColor(uint8_t);
void drawFastHLine(int8_t x, int8_t y, int8_t);
void drawFastVLine(int8_t x, int8_t y, int8_t);
void fillCircleHelper(int8_t, int8_t, int8_t r, uint8_t, int8_t);
void drawCircleHelper(int8_t, int8_t, int8_t, uint8_t);

Preparing Your Colorduino board

Before you can upload the sketch to your Colorduino, make sure that the
settings are right for the Board, the processor, and the USB port.
In the tools menu, check these settings:

Board -> Arduino Duemilanove or Diecimila
Processor -> ATmega328
Port -> (whatever serial port your FTDI cable is connected to)

Installing the Demo

A demo program comes with the Colorduino_FW library. To install it on your
Colorduino, invoke it in your Arduino IDE by clicking on:

File -> Examples -> Colorduino_FW -> demo

(You may need to scroll all the way to the bottom of your Examples
menu to find the Colorduino_FW entry.) The demo sketch should
show up in your Arduino window.

Then use the upload button as usual (or CTRL-U) to upload the demo
program to the board.

Modifying the demo

It’s easiest to begin programming the Colorduino just by modifying the demo program.
For example, change the string that scrolls near the beginning of the program from:

String message = "Robotics and beyond";

to

String message = "Hi I'm George!";

Recompile and download.

Another simple mod is to change the color used for the heart image. Near the top of
the demo.ino sketch, notice a statement which defines an array variable named heart,
to consist of 8 strings, each having 8 characters. To review the syntax and use of
array-type variables, see the packet on arrays.

String heart[] = {
                  "--------",    // '-' means no color, which is the same as background color
                  "--11-11-",    // '1' means "Color #1" in the colors[][] array.
                  "-1111111",
                  "-1111111",
                  "--11111-",
                  "---111--",
                  "----1---",
                  "--------"
                 };

The colors array is defined in Colorduino_FW.cpp in the libraries folder.
It is pre-filled with 10 colors, as shown below:

const uint8_t colors[][3] = { 
    { 255, 255, 255},    // white  0
    { 255, 000, 000},    // red    1
    { 255, 140, 000},    // orange 2
    { 255, 255, 000},    // yellow 3
    { 000, 60, 000},     // green 4
    { 000, 000, 255},    // blue 5
    { 255, 000, 255},    // purple 6
    { 139, 67, 19},      // brown 7 
    { 000, 000, 000},    // black 8
    { 255, 255, 255}     // snow white 9
};

Each color is an array of 3 values, corresponding to the desired intensity
of Red, Green, and Blue light. Each value ranges from 0 to 255.

The “zeroth” element in the array is:

colors[0] = { 255, 255, 255 };

This color is white because each of Red, Green, and Blue has its maximum value.

The “first” element in the array is:

colors[1] = { 255, 0, 0};

This color is red because only the Red light has any value at all.

The heart array is made up of empty (background) pixels and red pixels.

You can replace the heart array in the demo sketch with another one.

A Simple Sketch

The following sketch sets up two “images”, one is a smiley, where the
foreground color is yellow, and the other is a frownie, where the
foreground color is green.

#include <Colorduino_FW.h>
#include <Colorduino.h>

/* A smiley in color #3, i.e., yellow. */
String smiley[] = {
                     "--------",
                      "--------",
                      "-3----3-",
                      "--------",
                      "--------",
                      "3------3",
                      "-3----3-",
                      "--3333--"
                    };

/* A frownie in color #4, i.e., green. */
String frownie[] = {
                     "--------",
                      "--------",
                      "-4----4-",
                      "--------",
                      "--------",
                      "--4444--",
                      "-4----4-",
                      "4------4"
                    };

void setup() {
  Colorduino.Init();
  // The next 2 statements adjust the color balance.
  // each value can range from 0 to 63.  Adjust to taste.
  unsigned char whiteBalVal[3] = {36,63,63}; 
  Colorduino.SetWhiteBal(whiteBalVal);
}

void loop() {

  String returnImage[] = {  /* Placeholder for an image used by wipeImageLeft() */ 
    "--------",
    "--------",
    "--------",
    "--------",
    "--------",
    "--------",
    "--------",
    "--------"
  };

  String tempImage[] = {   /* Another placeholder */
    "--------",
    "--------",
    "--------",
    "--------",
    "--------",
    "--------",
    "--------",
    "--------"
  };

  setBgColor(8);           // background is now black
  clearScreen();

  drawImage(smiley,  0, 0);    // draw the "smiley" starting at x=0, y=0
  Colorduino.FlipPage();       // copy the buffer to the RGB matrix
  delay(3500);                 // show the image for 3.5 seconds
  wipeImageLeft(smiley, tempImage, returnImage);  // scroll the image off the screen

  drawImage(frownie,  0, 0);
  Colorduino.FlipPage();
  delay(3500);
  wipeImageLeft(smiley, tempImage, returnImage);

}