Controlling RGB Matrices with Arduino

Skill Level: Beginner

by zagGrad September 16, 2010 | 14 comments

Multiple RGB Matrices

The RGB Matrix with Serial Interface boards are pretty sweet, but there's really only so much you can do with a single RGB Matrix. Stringing a bunch of these boards together would be awesome; the trouble is it's a little tough to control the information for multiple boards. Because of this we've written an Arduino Library that allows for easier control of multiple RGB Matrices. This tutorial is an overview of the functions in the library and how to use them

Multi-Board RGB Matrix Frame

Software Required

• Arduino 0018 (or later)

Hardware Required

• Arduino Duemilanove (or similar)
• RGB Matrix boards (up to 8)
• 5 Male/Male Jumper Wires (or just 5 normal wires will work too)

Firmware Required

• RGB Matrix Library
• RGB Matrix Hex File
• Optional: RGB Matrix v5 Source

Getting Things Ready

While the RGB Matrix library was being created a couple of bugs were found in the firmware of the RGB Matrix itself. The bugs have been fixed, however in order to use the RGB Matrix Library the firmware will need to be updated on the RGB Matrix boards. Download the RGB Matrix Hex File and upload it to every RGB Matrix board. Don't know how to do this? This tutorial on using an Arduino as an ISP Programmer shows you how you can upload a hex file to the RGB Matrix board.

Once the hex file has been uploaded to all of the RGB Matrix boards, the RGB Matrix Library has to be installed. Download the RGB Matrix Library and unzip it into the Arduino libraries directory. Usually this is located in the Arduino folder. After unzipping the folder you should have a directory with a path that looks something like this: ...\arduino-0018\libraries\RGBMatrix. The library files are inside the RGBMatrix folder.

Hooking Things Up

Before any code can be uploaded the RGB frame and the Arduino need to be connected. By the way, the 'RGB Frame' is the entire set of connected RGB Matrices. I found it easier to connect the wires from the Arduino to the first RGB matrix before connecting the rest of the frame. Use the table below as a guide on how to connect wires from the Arduino to the RGB Matrix. Make sure the wires get connected to the Female Header on the RGB Matrix

Wired RGB Matrix

After the Arduino is wired to the first RGB Matrix the rest of the matrices can be attached to create the frame. The wires should be connected to the female header of the RGB matrix, leaving a male header bare. The next RGB matrix just slides right onto this connected. Keep sliding up to 8 matrices onto the frame.

Several RGB Matrix Boards Connected

Quickstart

The quickest way to get started with the RGB Matrix library is to check out the demo sketch that's included. Once the library is installed, close the Arduino IDE if it's open. Start Arduino up (or restart it) and navigate to File->Examples->RGBMatrix->RGBMatrixDemo. The sketch is commented pretty well so it'll be left to you to figure out what's going on. The only thing that needs to be changed before uploading the sketch to your board is the NUM_BOARDS variable. This should be changed to the number of boards you have connected to create your frame (i.e. if you've got 3 RGB Matrices connected to the Arduino, change the variable from 8 to 3. Now just upload the sketch to your board and watch the different effects. You can dive into the sketch to see how the colors are being manipulated to create the different animation sequences.

The RGB Matrix Library

This section of the tutorial is an overview of the actual library, it will cover the definitions and functions that are available in the RGB Matrix Library. As always, to use a library in a sketch start by going to 'Sketch' in the menu bar and select RGBMatrix from the Import Library menu.

Colors

There are 8 colors made available by the library: BLACK, RED, GREEN, BLUE, ORANGE, MAGENTA, TEAL and WHITE. You can use these variable names (case sensitive) in your sketch to send the corresponding colors to the matrix. You can also create your own colors. A color is a single character. The RGB Values are split within the character byte. The most significant 3 bits of the character define the brightness of the Red component; the second 3 bits define the Green brightness, and the last 2 bits define the Blue brightness.

For example, if I wanted to make the color red at full brightness I would use the character 0xE0 (in binary, this is 11100000). Play around with different values to see how the colors on the matrix change.

Matrix Parameters

There are 3 special variables that are defined that make it easier to navigate the board.

NUM_ROWS - This variable is constant and it is set to 8 (The number of rows on an RGB Matrix).

NUM_COLUMNS - This variable is constant and it is set to 8 (The number of columns on an RGB Matrix).

NUM_PIXELS - This variable is constant and it is set to 64 (The number of pixels on an RGB Matrix).

Functions
 

RGBMatrix.begin(int num_boards)

This function sets up a communication link between the Arduino and the RGB Matrix frames. The function takes an input that defines how many RGB Matrices are connected.
Example: RGBMatrix.begin(8);  //Set up communication to a frame with 8 RGB matrices.

char RGBMatrix.fillPixel(int screen, int row, int column, char color)

This function can be used to set the color of a single pixel on the frame. The function takes 4 parameters: the screen number, the row, the column and the color.
screen - An integer representing the screen of the pixel. Screen 0 is the screen furthest away from the Arduino. The highest numbered screen is NUM_BOARDS -1.
row - An integer representing the row of the pixel. Row 0 is at the top of the matrix
column - An integer representing the column of the pixel. Column 0 is at the right side of the screen.
color - A character representing the color to set the pixel with.
The function also returns a 1 for success or a 0 for failure. A failure can occur if an invalid screen, row, column or color is entered.
Note: The frame won't be updated with the new contents until the display() function is called.
Example: RGBMatrix.fillPixel(1,5,7,RED); //Set the pixel on screen 1, row 5, column 7 to red.

char RGBMatrix.fillColumn(int screen, int column, char color)

Used to set the color of a column on a specied screen. This function takes 3 parameters: the screen number, the column number and the color.
screen - An integer representing the screen of the column. Screen 0 is the screen furthest away from the Arduino. The highest numbered screen is NUM_BOARDS -1.
column - An integer representing the column of the pixel. Column 0 is at the right side of the screen.
color - A character representing the color to be used on the column
This function returns a 1 for success or a 0 for failure. A failure can occur from an invalid screen number, column number or color.
Note: The frame won't be updated with the new contents until the display() function is called.
Example: RGBMatrix.fillColumn(0,7,BLUE); //Set the left-most column of the 'last' screen on the frame to blue.

char RGBMatrix.fillRow(int screen, int row, char color)

Used to set the color of a row on a specified screen. This function takes 3 parameters: the screen number, the row number and the color.
screen - An integer representing the screen of the pixel. Screen 0 is the screen furthest away from the Arduino. The highest numbered screen is NUM_BOARDS -1.
row - An integer representing the row of the pixel. Row 0 is at the top of the matrix
color - A character representing the color to set the row with.
This function returns a 1 for success or a 0 for failure. A failure can occur from an invalid screen number, row number or color.
Note: The frame won't be updated with the new contents until the display() function is called.
Example: RGBMatrix.fillRow(2, 0, WHITE); //Sets the top row of screen 2 to white.

char RGBMatrix.fillScreen(int screen, char color)

Used to fill an entire screen with a color. This function takes 2 parameters: the screen number and the color.
screen - An integer representing the screen of the pixel. Screen 0 is the screen furthest away from the Arduino. The highest numbered screen is NUM_BOARDS -1.
color - A character representing the color to set the row with.
This function returns a 1 for success or a 0 for failure. A failure can occur from an invalid screen number or color.
Note: The frame won't be updated with the new contents until the display() function is called.


Example: RGBMatrix.fillScreen(7, GREEN); //Fill the 7th board in the frame (closest to Arduino) with green pixels.

char RGBMatrix.fillChar(int screen, char letter, char color)

Used to put a character onto a screen in the frame. This function takes 3 parameters: the screen number, the letter and the color.
screen - An integer representing the screen of the pixel. Screen 0 is the screen furthest away from the Arduino. The highest numbered screen is NUM_BOARDS -1.
letter - A character representing the letter to be displayed on the screen. (Only letters a-z, A-Z are supported. No numbers or special characters).
color - A character representing the color to set the letter with.
This function returns a 1 for success or a 0 for failure. A failure can occur from an invalid screen number, letter or color.
Note: The frame won't be updated with the new contents until the display() function is called.

Example: RGBMatrix.fillChar(0, 'R', ORANGE); //Put the letter 'R' onto the first board in the frame in the color Orange.

char RGBMatrix.scroll(char * message, char color, int speed)

Used to scroll a message across the frame. This function takes 3 parameters: the message, the color and the speed.
message - A string containing the message to be scrolled. Message is limited to 50 characters.
color - A character representing the color to be used for the letters in the string.
speed -An integer representing the delay time between each scroll position. The smaller the number, the faster the scroll speed. (A good starting point is 50).
This function returns a 1 for success or a 0 for failure. A failure can occur from an invalid color.
Example: RGBMatrix.scroll("SPARKFUN RULES", MAGENTA, 25); //Scroll the message "SparkFun Rules" across the frame in a MAGENTA color.

RGBMatrix.display()

Used to post the new data to the RGB Frame. This function doesn't take any parameters.
Example: RGBMatrix.display(); //Display the contents of memory to the RGB frame.

RGBMatrix.clear()

Clears the entire frame by setting all of the pixels black. This function doesn't take any parameters.
Example: RGBMatrix.clear(); //Clear the frame.

That's it! I hope you enjoy using this library. Please leave any questions or critiques in the comments section.