Wednesday, May 4, 2011

SeeedStudio 4x4x4 LED cube and Rainboduino


The Seeed Studio Rainbow Cube Kit is a 4x4x4 RGB LED kit with 64 tri-color LEDs for a total 192 connections. The kit comes with professionally designed components. A connector on the bottom of the kit is designed to mate up with the Seeed Studio Rainboduino which contains all of the drivers and connections needed to control an 8x8 tri-color LED array.  The LED cube comes nicely packaged with no installation instructions, schematics or hints.   The LED Cube does have it's own wiki page, which is probably the worst wiki page on the planet with no schematics, theory of operation or description of what kind of line driving is required by controller board. The LED cube wiki does contain a link to a slick Rainbowduino driver program. Assembly instructions are available on the Seeed Studio site. Robotshop has done an instructable and has the assembly instructions on their site.

The Rainboduino is an Arduino clone specifically designed for LED control.  It was  designed for an 8x8, 64 tri-color LED with 192 connections the same as a used for the 4x4x4 cube.  It comes with no schematics, instructions or internet references.

The Red, Green and Blue squares identify the RGB drivers.  The two 4 pin connectors on either side of Green are the 8 selector lines. The black connector on the left hand side contains inbound I2C and serial pins. You will use the serial pins to program the board.  The connector on the right hand side  comes with the I2C header installed by default.

You can see a SeeedStudio BluetoothBee installed in the upper portion of the board.  This cannot be used without soldering an additional connector on the Rainbowduino.


The on line assembly guide is pretty good about telling you how to assemble the cube to be controlled over I2C or daisy chained together.  Assembly took me about 4 hours.  You need to solder everything to the base plate before attaching the LED cube risers to the bottom plate.   It is pretty hard to solder connections on the top side of the plate once all the cross pieces are in place.  You will need an external USB/serial adapter or an arduino to program the device. I used the UartsB since it came in RobotShop  kit.

Ignore this if you are not interested in the on-board XBee socket  The kit comes with parts to solder an XBee socket with 3.3V/5V level converters on the underside of the main board. The on-line guide describes component placement for the socket. There is no description of how to use the socket and how to connect the GND, RX and TX lines from the soldered in socket. It turns out the Rainbowduino pins of the downstream (right hand side in the picture above) are directly above a row of header mounting points on the base of the cube.  You can connect the serial lines from the XBee to the Rainbowduino by soldering a 4 pin connector in the position shown on the right.  You should not make the connector any longer, going up, because it will conflict with the I2C pins already mounted on the Rainbowduino.

The earlier picture of the bottom of the cube has been annotated as to which pins should have connector installed to mate with the one installed on the motherboard. This picture shows a serial connector mounted to the Rainbowduino board that will mate up with the 4 pin connector previously installed on the cube base.


The simplest way to program the device is to get the UartsB USB/serial converter. It plugs into one edge of the Rainbowduino board. (Remove this if communicating over I2C or Bluetooth)  Remember to remove any bluetooth adapters when programming. They share the same lines as the USB/serial adapter and they will conflict.

The firmware only knows about the 8x8 mapping so PC software must map from 8x8x3 Rainbowduino programming model to the 4x4x4x3 LED cub physical model.  It is possible to write different Rainboduino firmware that intrinsically understands the cube. You can find links to firmware that does this in this blog. The Rainbowduino firmware supports 12 bit (4,4,4) color using a 96 byte command payload. The default Rainboduino software accepts i2c commands to set the colors on the lights and supports the daisy chaining of controllers to build up strings of 8x8 panels.  There is no information as to what version of the firmware comes preloaded on the Rainbowduino. This blog contains one of the better first steps overview. There is a Rainboduino wiki page that should scare away all but the most motivated.  It contains links to at least three different sets of firmware.  All require an I2C master to talk to the Rainbowduino once it is flashed.

  1. The stock firmware. There appears to be a version that may talk over a serial port possibly negating the need for an additional arduino.
  2. Alternative firmware
  3. Neorainbow firmware  This appears to have the most active development and the biggest feature set.
  4. There is a custom version of the plasma demo that you can load into the Rainboduino that automatically cycles through colors. 
  5. Firmware and library for the processing lauage.
Directly Supporting 3D

I have updated the stock firmware to create serial port firmware to add 3D drawing methods.  They handle the mapping from the 2D 8x8 internal representation to the 3D 4x4x4 cube drawing space. The code uses this array to map from x,y,z to row,col that the actual frame buffer uses. The firmware is available on GitHub

unsigned int cubeToRowCol[4][4][4] PROGMEM = {
  // x 0
    {0x0007,0x0006,0x0005,0x0004}, // y=0
    {0x0107,0x0106,0x0105,0x0104}, // y=1
    {0x0207,0x0206,0x0205,0x0204}, // y=2
    {0x0307,0x0306,0x0305,0x0304}, // y=3
  // x 1
    {0x0000,0x0001,0x0002,0x0003,}, // y=0
    {0x0100,0x0101,0x0102,0x0103,}, // y=1
    {0x0200,0x0201,0x0202,0x0203,}, // y=2
    {0x0300,0x0301,0x0302,0x0303,}, // y=3
  // x 2
    {0x0407,0x0406,0x0405,0x0404,}, // y=0
    {0x0507,0x0506,0x0505,0x0504,}, // y=1
    {0x0607,0x0606,0x0605,0x0604,}, // y=2
    {0x0707,0x0706,0x0705,0x0704,}, // y=3
  // x 3
    {0x0400,0x0401,0x0402,0x0403,}, // y=0
    {0x0500,0x0501,0x0502,0x0503,}, // y=1
    {0x0600,0x0601,0x0602,0x0603,}, // y=2
    {0x0700,0x0701,0x0702,0x0703,}, // y=3
The standard 7 byte command structure is too short for 3D drawing with RGB values so I don't see any way to add 3D drawing commands to the stock firmware without breaking backwards compatibility.  The stock firmware is limited to 7 bytes 'R',cmd_byte,5 data bytes which doesn't work that well for x,y,z,r,g,b so the 3D drawing command packs x,y,z in the first data byte with two bits per pixel. A sample perl script is included in the zip package that shows how to use this new command.

sub sendPoint
    my $x = $_[0];
    my $y = $_[1];
    my $z = $_[2];
    my $coord = ($x << 4) | ($y <<2) | $z;
    my $r = $_[3];
    my $g = $_[4];
    my $b = $_[5];
    my $stringToSend = sprintf("R%c%c%c%c%c%c",$DRAW_DOT_CMD,$coord,$r,$g,$b,0);
    if ($DEBUG){
        my $commandHex = sprintf("R%d-%x-%x-%x-%x-%x",$DRAW_DOT_CMD,$coord,$r,$g,$b,0);
        my $debugString = sprintf "Command is %s - %i characters\n",$commandHex,length($stringToSend);
} sells a full kit as a single SKU.  They also have a self-produced video that shows how to assemble the cube and attach the Rainbowduino.  They have a complete diy package that includes the the LED cube, Rainboduino and a UartsB that lets you directly re-program the Rainboduino without going through an Arduino.  The UartsB is actually a USB to serial bridge making the Rainboduino appear as a virtual serial port.  The stock version of the firmware is designed to control a series of cubes via I2C.  The examples show how to do that using an Arduino .  I thought about using a Chumby as my I2C master but it runs at 3.3v and the Rainboduino/Arduino run at 5V so I instead loaded an alternate firmware that accepts commands via the UartsB allowing me to reprogram and control using the same port.

UartsBee (optional) Bluetooth Control

I normally used the Sparkfun BlueSmirf Bluetooth adapters but purchased the SeeedStudio Bluetooth Bee because it fits on the UartsB and because it could be installed in the on-board socket so that the UartsB USB/serial adapter can be removed.  See the section above on what hardware needs to be installed. The UartsBee runs at a default speed of 38400bps.  You should add something like the following code to the Rainbowduino initialization sequence after setting the data rate to 38400.

    Serial.print("\r\n+STWMOD=0\r\n");     // slave
    Serial.print("\r\n+STNA=LEDCube\r\n"); // device name
    Serial.print("\r\n+STAUTO=0\r\n");     // auto connect to last device 0=no,1=yes
    Serial.print("\r\n+STOAUT=1\r\n");     // permit paired device to connect 0=no,1=yes
    Serial.print("\r\n +STPIN=1234\r\n");  // set pin to 1234
    delay(2000); // This delay is required.
    Serial.print("\r\n+INQ=1\r\n");        // Slave/Enable being inquired
    delay(2000); // This delay is required.


Troubleshooting Tips

The Rainbowduino looks like an Arduino Duemilanove.  You need to set the board type in the IDE in order to upload firmware.

The cube is divided in halves  A and B. Rainbowduino is designed to drive an 8x8 display with 8 select lines.  Each A/B post contains RGB lines and a single select line.  Each select line drives 8 LEDs on a single level, two rows of 4 closest to that side's posts. The instructions tell you to short 4 jumpers on each the Side A and Side B supports, one on each level. (Do not connect all 16 jumpers on each side.) These jumpers connect the + select line from the base of that support to the bank of 8 (2x4) LEDs  on the level next to the jumper.  The jumpers actually connect to the post/level solder pad closest to the jumper.  A dark set  lights either means the jumper isn't connected or that the join at that corner isn't soldered together.  I had to solder a jumper form the pads to the corner solder joint for a couple of mine, probably because I had played with the jumpers a couple times while troubleshooting.  All of the lights on one side always changing together may mean you soldered too many jumpers.  You only need 4 per side.

This LED cube used as a CI build light.  Each level represents a different build. The top build is blinking (in progress). The second level down shows a broken build.  The bottom two builds were both successful in their last iteration. The cube is driven over bluetooth by a java program using rxtx to talk to the virtual serial port. The foam plate  is used as a reflector to increase contrast in an office environment.


  1. Hi,just wondered, you mention that to get the bluetooth module working you had to create another connection on the Rainboduino, is this a logical initiation, or a physical cable? Thanks, Simon.

  2. I'm not sure I understand the question. The Rainboduino has an XBee style socket on the bottom. They make a bluetooth device in the XBee form factor that fits in that socket. I had to modify my software to configure the XBee on startup because I couldn't get it to hold configuration changes. On the software side, you will bluetooth pair with the device and a new virtual com port will be create. That is the COM port the PC will use to communicate.

  3. Hi i am doing the rainbow cube from rainbowduino on C++ programming. the link for the rainbow cube that i am doing is the programming codes that i have error on is on cube 2. the error is avrdude: stk500_getsync(): not in sync: resp=0x00
    avrdude: stk500_disable(): protocol error, expect=0x14, resp=0x51.