Controlling RGB Matrices with Arduino


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

http://www.sparkfun.com/tutorial/ArduinoRGBMatrix/Multiboard%20Setup%20Edit%20Scaled.jpeg
Multi-Board RGB Matrix Frame

Software Required

Hardware Required

Firmware Required

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

Arduino Pin RGB Matrix Pin
5V VCC
GND GND
D10 CS
D11 MOSI
D13 SCLK

http://www.sparkfun.com/tutorial/ArduinoRGBMatrix/Wired_Scaled.JPG

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.

http://www.sparkfun.com/tutorial/ArduinoRGBMatrix/Connected.JPG
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.

Comments 13 comments

  • will this work with the arduino yun?

  • Does the RGBBackpackv5.hex work with the RG(red/green) backpack? Will I brick my LED if I try it?

  • I am running the RGBMatrixdemo.pde, and I am having issues the (0,0) and (0,1) pixel do not seem to be running with the code. They are showing a random Purple colour flashing intermittently, and off setting the demo animation.
    I have ran reprogramming avr tutorial many times (http://www.sparkfun.com/tutorials/200)
    This is my response:
    localhost:build5771000639837063125.tmp lowell bert$ avrdude -P /dev/cu.usbserial-A800eK8t -b 19200 -c avrisp -p m328p -v -e -U flash:w:/Users/lowell bert/Desktop/RGB_Backpack_v5-1/RGB_Backpack_v5.hex
    avrdude: Version 5.8cvs, compiled on Jan 15 2010 at 17:27:01
    Copyright © 2000-2005 Brian Dean, http://www.bdmicro.com/
    Copyright © 2007-2009 Joerg Wunsch
    System wide configuration file is “/usr/local/CrossPack-AVR-20100115/etc/avrdude.conf"
    User configuration file is ”/Users/lowell bert/.avrduderc"
    User configuration file does not exist or is not a regular file, skipping
    Using Port : /dev/cu.usbserial-A800eK8t
    Using Programmer : avrisp
    Overriding Baud Rate : 19200
    avrdude: stk500_getsync(): not in sync: resp=0x15

    avrdude done. Thank you.

    Anyone know a fix?

  • Hi, please update the firmware link to point to v5 on the RGB Matrix product page. Also, the datasheet/docs should also be updated to reflect the changes in the firmware - in particular, the special 0x26 Start of frame character.

  • would this work with modules like this?
    http://www.sureelectronics.net/goods.php?id=142
    or is this project/code designed specifically for the boards in question?
    reason I ask, is because it seems to be somewhat of a similar interface between the boards, and I’ve already got 2 of them on order.

  • I’ve got an Uno, so I thought I wasn’t able to upload the firmware. I stumbled on a patch for ArduinoISP here:
    http://www.arduino.cc/cgi-bin/yabb2/YaBB.pl?num=1286589145
    I applied the patch manually, saved it as a new sketch. Then, I did this:
    1. Uploaded the patched ArduinoISP.
    2. Unplugged from USB.
    3. Disabled the autoreset.
    4. Connected the Matrix ISP pins in the prescribed manner.
    5. Connected the USB cable and let the Arduino boot.
    6. Ran the following from a terminal:
    avrdude -P /dev/tty.usbmodem621 -b 19200 -c avrisp -p m328p -F -v -e -U flash:w:RGB_Backpack_v5.hex
    And it worked. The firmware uploaded. Once it was done, I
    7. Unplugged the USB cable to power off the Arduino.
    8. Removed the disable of the autoreset.
    No more “tearing” letters, no off-by-one problems.

  • I’m confused. My understanding from the datasheet is that you have to do this:
    1. Take SS low.
    2. Wait 500 microseconds.
    3. Write to the SPI.
    4. Take the SS high.
    5. Wait 500 microseconds.
    I just had a look into the library and the code that initialises the board seems to skip the timing on the datasheet. For example:
    //Make sure the RGB matrix is deactivated
    digitalWrite(SLAVESELECT,HIGH);
    //Send the command mode character
    digitalWrite(SLAVESELECT, LOW);
    spiTransfer(‘%’);
    digitalWrite(SLAVESELECT, HIGH);
    delay(100);
    //Configure the correct number of boards
    digitalWrite(SLAVESELECT, LOW);
    spiTransfer(num_boards);
    digitalWrite(SLAVESELECT, HIGH);
    delay(100);
    Shouldn’t it be more like:
    //Make sure the RGB matrix is deactivated
    digitalWrite(SLAVESELECT,HIGH);
    //Send the command mode character
    digitalWrite(SLAVESELECT, LOW);
    delayMicroseconds(500);
    spiTransfer(‘%’);
    digitalWrite(SLAVESELECT, HIGH);
    delayMicroseconds(500);
    //Configure the correct number of boards
    digitalWrite(SLAVESELECT, LOW);
    delayMicroseconds(500);
    spiTransfer(
    num_boards);
    digitalWrite(SLAVESELECT, HIGH);
    delayMicroseconds(500);
    There seem to be other examples in ::display() and ::scrollBuffer.
    Or maybe that’s being handled elsewhere? Please de-confusify me.

  • Apologies for a comment that is not directly linked with this project but I am struggling to find a solution to making an art project which is an led message scroller that scrolls a message around a circle that is around 40cm in diameter. This scroller would have 230 x 7 leds, a total of 1610. It would scroll a set message which would go around anticlockwise without beginning or end. Here is a sketch:
    http://img210.imageshack.us/img210/2099/diagram2.jpg
    I know a bit a microcontrollers and would have no problem making the led array but to control them I dont seem to be finding the right controller….Any help or pointers in the right direction from anyone would be greatly appreciated!
    Thanks

  • Is the source code for the new firmware (V5) available anywhere?
    It seems to be acting incorectly. For example, if I send B00100101 to the entire matrix (all colours dimest), it just looks black, no different from B00000000. Maybe it works differently than v4? Advice or source code would be much appreciated. I’ve added colour/brightness fading to the RGB Matrix Library and I’m trying to get all the resolution I can!

    • Ah, OK, the value you’re sending for the lowest brightness level for each color is 0x25. Unfortunately this is a special command value that tells the matrix boards to go into ‘command mode’ so that the number of boards can be set. 0x26 is also an invalid color option.
      I’m pretty sure that every funtion in the library that’s used to set a color will return 0 (rather than 1) if one of these characters is used; you can use that to help debug.
      (i.e. if(!RGBMatrix.fillPixel(0,1,2,0x25))Serial.print(“Invalid Character”);

    • The source is posted. I’ll try and look into the lowest brightness level you mentioned soon.

  • “This tutorial on using an Arduino as an ISP Programmer” tutorial (or whatever) should be linked.