Colorduino Library for Arduino

I wrote a Colorduino library for Arduino.  It handles initialization and double-buffered drawing on ITead Studio’s Colorduino.  It is also compatible with Itead’s Arduino RGB Matrix driver shield. Included with the library is a sample sketch to show how to use it, ColorduinoPlasma, which draws a pretty plasma on an 8×8 RGB matrix.

To install the library, download the zip file (see below), and copy libraries/Colorduino to your arduino sketchbook/libraries/Colorduino. If you are already running the Arduino IDE, you must restart it before you can use the library. You can then run load ColorduinoPlasma.pde demo.

To include the Colorduino library in your own sketch, just

#include <Colorduino.h>

Then your setup() function needs to just call two functions for initialization:

void setup()
{
Colorduino.Init();
// compensate for relative intensity differences in R/G/B brightness
// array of 6-bit base values for RGB (0~63)
// whiteBalVal[0]=red
// whiteBalVal[1]=green
// whiteBalVal[2]=blue
unsigned char whiteBalVal[3] = {36,63,63}; // for LEDSEE 6x6cm round matrix
Colorduino.SetWhiteBal(whiteBalVal);
}

Colorduino.SetWhiteBal() is used to adjust the white balance. You can put

ColorFill(255,255,255);

in your sketch to test the white balance by drawing a white screen.  Then adjust whiteBalVal until your screen approximates white.

The origin of the screen, (0,0) is at the bottom left corner. The off screen buffer can be accessed either pixel by pixel:

Colorduino.SetPixel(x,y,r,g,b);

or by direct manipulation.  The screen buffer is arranged by row. For instance to set all of the pixels in the second row to the same color:

PixelRGB *p = GetPixel(0,1);
for (int x=0;x < ColorduinoScreenWidth;x++) {
p->r = red;
p->g = green;
p->b = blue;
p++;
}

After you finish updating your screen, make it live by swapping it with the currently display buffer:

Colorduino.FlipPage();

2012-06-07 I have moved the code to github.
Please download the latest version from: https://github.com/lincomatic/Colorduino/downloads

*****************************************************

Download below is *obsolete* but included here for historical purposes

Download Colorduino Library V1.2: ColorduinoV1_2.zip

Change Log

2011/05/25 v1.2
removed buggy unused function RGBtoINT from ColorduinoPlasma.pde

2011/03/06 v1.1
fixed bugs in coordinate system. origin (0,0) is bottom left corner
rearranged frame buffer for better performance

2011/03/04 v1.0
Initial Release

There are 102 Comments to "Colorduino Library for Arduino"

  • [...] released an Arduino library that works with both the Colorduino and Iteadʼs Arduino RGB Matrix driver [...]

  • Nick says:

    Hey,

    Great blog – I also have a Colorduino to test with and have been adding (probably badly) to your code for it to receive data over I2C from a master Arduino.

    One thing I have found is if I write to a pixel at:

    PixelRGB *p = &(*Colorduino.curWriteFrame)[0][0];

    It actually appears at 1,0 – i.e. x is one above. When x=7 it appears at 0.

    Do you see the same issue?

    Cheers
    Nick

    • lincomatic says:

      Nick, Funny how you mention that … I notice it this morning, and am in the middle of fixing it. I probably shouldn’t have tested it w/ the Plasma, because it’s hard to notice subtle bugs like this! I will be uploading the fix shortly… I just want to test a bit more first.

      • lincomatic says:

        Hmm.. it looks like I messed up the coordinate system, too. I want it to work like normal cartesian coordinate system… (0,0) in the bottom left corner. I’ll have to defer the update until this evening.
        Sorry for the premature release of V1.0 .. I will make sure it works properly this time before I upload the new one.

  • Nick says:

    Hey no problem, I can send you my I2C stuff if you are interested in adding that as an option.
    It’s based on the blinkM version.

    I like the plasma stuff BTW, it’s one of the cooler looking demos for the 8×8 matrix.

    • lincomatic says:

      OK, the update is live now. I changed the organization of the screen buffer while I was at it to make the memory access faster, since the board updates a row at a time, rather than a column at a time.
      Sure, send me your updates, if you like. I2C would be a nice addition.

  • Gandarez says:

    Hey Guys… I need the ColorduinoLibrary in C#… but is very complicated to translet it. :(

    • lincomatic says:

      I don’t code C#, but my understanding is that you can call C++ libraries from C#.
      Here’s a link to get you started: http://stackoverflow.com/questions/574801/call-c-library-in-c

      • Gandarez says:

        Hey Guys, I searched the web how it works the function”sei()”, but I didn’t find anything.. Has someone a tutorial about “sei()” function and “cli()” ??

        • lincomatic says:

          cli() clears (disables) interrupts,and sei() enables them.

          • Gandarez says:

            lincomatic, sei() enable all interrupts, all defined pins as digital, like to set true in interrupt?

          • lincomatic says:

            no it has nothing to do with digital pins. when you clear interrupts it keeps your code atomic. normally, your code flow can be interrupted, say, when a timer overflows. for time or context sensitive code, enclosing the code in cli()/sei() keeps it atomic. sorry, i can’t give you a tutorial on interrupts. it’s a basic function of CPU’s. you can just google “arduino sei cli” if you want to learn more.

          • Gandarez says:

            lincomatic I have the basic know to understand… so now I gonna learn more about this topic..

  • DarkAngel says:

    I don’t get it. Maybe I’m just too stupid for the English language…

    Colorduino.SetPixel(1,1,255,0,0); –> nothing changes

    ColorFill(255,255,255); –> start:40: error: ‘ColorFill’ was not declared in this scope

    I did exactly what was mentioned above:
    ———–
    #include
    void setup()
    {
    Colorduino.Init();
    // compensate for relative intensity differences in R/G/B brightness
    // array of 6-bit base values for RGB (0~63)
    // whiteBalVal[0]=red
    // whiteBalVal[1]=green
    // whiteBalVal[2]=blue
    unsigned char whiteBalVal[3] = {36,63,63}; // for LEDSEE 6x6cm round matrix
    Colorduino.SetWhiteBal(whiteBalVal);
    }

    void loop()
    {
    Colorduino.SetPixel(1,1,255,0,0);
    }

    ————

    I started about October 2010 with the Arduino Uno, I found it quite interesting and now I was tired of getting some single LED on my breadboard and connecting it to the Arduino… But how is this supposed to work?

    Regards

    • lincomatic says:

      ColorFill() isn’t included in the library, sorry, I should have made that clear. You need to copy it from ColorduinoPlasma.pde to your new sketch. Does the ColorduinoPlasma sketch work correctly? And what do you see when you run your own sketch… you say nothing changes… you mean all the LED’s are off?

  • [...] feeds and communicate via serial port. The Arduino code is pretty simple and uses the Colorduino library to change the colors of the LED [...]

  • bhunting says:

    Hello, thanks for creating the library and the plasma demo, both are very cool. I might have found an issue in the plasma demo. Although it does not appear to be used the function RGBtoINT might have a bug. It looks like you are trying to convert the 3 8 bit RGB colors to a single 24 bit unsigned int by shifting. I believe ints are 16 bits in avr-gcc so the red bits get shifted off the end.


    unsigned int RGBtoINT(void *vRGB)
    {
    ColorRGB *colorRGB=(ColorRGB *)vRGB;

    return (((unsigned int)colorRGB->r)<g)<b;
    }

    • bhunting says:

      hmm, looks like the html renderer processed out significant parts of the code in the snippet above, you’ll have to look at the code directly to see the problem. There is a shift of r by 16 bits, g by 8 bits, and b by 0 bits and then stored into an unsigned int which is 16 bits. The 16 bit shift of r should shift it off the end.

      • lincomatic says:

        Thanks. I’ll just delete that function, since it isn’t being used. I adapted the code from someone else’s sketch. It had a lot of extraneous unused functions in it. I guess I missed one.
        But yes, you’re right, for that function to work properly, it should return an unsigned long.

  • IllegalPete says:

    Did the Nick’s i2c-based control code ever get integrated into this library or released? Thanks.

  • Rik says:

    Hi, first thanks for the wonderful job you did!

    I am having problems with getting different frames made through the set pixel function and put them after each other in a switch case to generate animations. It seems that the screenbuffer doesnt get refreshed or something like that.
    After the first loop the two pixels both stay lit. Any ideas?

    Thanks in advance.

    void loop() {
    unsigned long currentMillis = millis();
    if(currentMillis – previousMillis > interval) {
    previousMillis = currentMillis;

    switch (LatestFrame) {
    case 0:

    Colorduino.SetPixel(0,0,255,255,0);
    LatestFrame++;
    break;
    case 1:
    Colorduino.SetPixel(0,1,255,255,0);
    LatestFrame++;
    break;

    default:
    LatestFrame = 0;

    }
    Serial.println(LatestFrame);
    Colorduino.FlipPage();
    }

    }

    • lincomatic says:

      They stay lit because that’s what your code does You’re just setting (0,0) and (0,1) to (255,255,0). There’s no code to change them to any other value.

      • Rik says:

        Oh okay well im just starting with coding but I think it would be useful for me to make a function which clears all the leds, u have any suggestions? Otherwise I would need to set all the 64 pixels per frame manually which is madness.

        Oh and btw when I add a third pixel the animation goes through one loop smoothly and after that combines the first and last pixel and swaps with the second pixel so actually it is does happen that leds turn of….

        • lincomatic says:

          Have a look at my Plasma demo.. there’s a function in there called ColorFill() which you can use to clear the screen by filling it in with black.

  • Weststar42 says:

    Does the latest library work correctly with the latest Arduino IDE (1.0?)? I’m getting some odd behavior.

  • Weststar42 says:

    Colorplasma demo runs and lights up the matrix but it looks different from the youtube videos. There is more quadranting going on than in the videos. Also, I cannot get Colorfil to fill the entire matrix. Colorfil(255,255,255) turns one quadrant of the LEDs (4×4) red. Colorfil (0,255,255) turns the same 4×4 LEDs red. Colorfill(0,0,255) turns a differnt 4×4 quadrant green. See video at http://www.youtube.com/watch?v=t13bgXZT_rQ and http://www.youtube.com/watch?v=5tGBpfx17g8

  • ken says:

    over the months or so i was using your colorduino library, but i made some small updates & modifications: if you or others are interested i’ve posted the code to github https://github.com/frederickk/Colorduino

    • lincomatic says:

      Thanks, I just got back from an overseas trip. I’ll check it out when I get the time.
      Can you tell me what you changed?

  • impure says:

    Thanks for the library and the lampduino instructable, I was able to use it for a project for university and it helped a great deal. We have however run into a small problem, the LED’s aren’t as bright as we would want them to. If we manually set the Arduino ports to high the LED’s are a lot brighter compared to setting them at full brightness using your library. I’m wondering if there’s a setting somewhere in the library to get the LED’s to burn brighter. Again thanks and hopefully you’ll be able to help out with this problem!

    • lincomatic says:

      Yes, it’s not as bright with the library, because it’s actually sequencing the LED’s so the duty cycle isn’t 100%.
      The only way to get the LED’s to burn brighter is to use transistors to drive them.

      • impure says:

        Thanks for the fast reply, saves me a lot of headaches trying to figure it out. Fortunately the LED’s are only used for our prototype and will do a fine job at demonstrating the principle! Thanks again!

  • Norbert says:

    Hi Lincomatic,

    if i want to compile the Colorduino Demo code i get the following error

    In file included from /Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/cores/arduino/Arduino.h:212,
    from ColorshieldDemo.cpp:69:
    /Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/variants/standard/pins_arduino.h:45: error: expected unqualified-id before 'volatile'
    /Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/variants/standard/pins_arduino.h:45: error: expected `)' before 'volatile'
    /Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/variants/standard/pins_arduino.h:45: error: expected `)' before 'volatile'
    /Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/variants/standard/pins_arduino.h:46: error: expected unqualified-id before 'volatile'
    /Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/variants/standard/pins_arduino.h:46: error: expected `)' before 'volatile'
    /Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/variants/standard/pins_arduino.h:46: error: expected `)' before 'volatile'

    i replaced the Wprogram.h with Arduino.h

    do you have an idea to solve the prob?

    thanks in advance

    Norbert

    • lincomatic says:

      I assume you’re using Arduino 1.0+? For older versions, you don’t need to keep Wprogram.h.
      I am not sure why you are getting the errors It works fine for me.
      Which board do you have selected?

  • Norbert says:

    Duemilanove, but i tried all with the same Processor

  • Norbert says:

    in addition, i made a reboot and everything is fine now.

    thx

  • Norbert says:

    In the schematic pin 9, 26 and 32 were unused, is it possible to use them for my own application?

    greets

  • da2001 says:

    i´cant use the “colors shield 1.1″ with an arduino mega 2560. Has anyone an idea why? I had a look at the sketch and also at the libraray, but i didn´t found anything that maybe helps me.

    • lincomatic says:

      What do you mean you can’t use it? What happens?

      • da2001 says:

        Strange.. my last message is went away. So again: When i upload the sketch to my mega 2560 r3, only the 2nd or 3rd vertical line of my 8×8 Matrix shield will blink 3times in violet. After that i see a black matrix shield. Only on my arduino uno is the plasma demo running very well. I have no idea what can be different to the uno board.

        • lincomatic says:

          Hmm. Sorry, I have no idea. I don’t have a Mega so I can’t test. Maybe you can ask ITead if it’s compatible with the Mega.

          • Matt says:

            I’ve made the same observations:
            mega 2560 r3: only 2 rows are flashing two times in violet
            uni r3: perfect running.
            environment is arduino v1.0.1 and colorshield v1.2
            somebody assumed that there might be different registers and interrupts in these chips….

          • lincomatic says:

            Hmm. OK, it’s possible my code isn’t compatible with a MEGA .. I based it on some sample code I got from ITead.
            If you look in Colorduino.h, it programs via direct port access instead of using Arduino calls (this is for speed … it would be too
            slow to use digitalWrite). I don’t have a Mega, but might be able to try some changes if you’re willing to test

        • lincomatic says:

          I uploaded test code for you to try on the Mega https://github.com/lincomatic/Colorduino/blob/master/libraries/Colorduino/Colorduino.h
          Please test and let me know if it works.

  • Matt says:

    Testing – That’s what the Community is made for
    If you publish New Code i’ll try it!
    Thanks anyway for the excellent library !!!
    Matt

  • Matt says:

    I’m pretty busy this weekend, but I’ll try it on Monday.
    Have a nice weekend
    Matt (corrected my e-mail)

  • Moe says:

    Hey first of all great library! Cool stuff you did there. But I tried the command ColorFill(255,255,255); and it just gives me an error (not defined). I searched for it in the library files, but yeah I couldn’t find it… So I just wanted to ask you if you removed it… (and if yes, why?). But anyways this isn’t a big problem at all because I wrote my own ColorFill (feel free to use this):

    void ColorFill(int r, int g, int b){
    for (int height=0; height < ColorduinoScreenHeight; height++){
    PixelRGB *p = Colorduino.GetPixel(0,height);
    for (int x=0;x r = r;
    p->g = g;
    p->b = b;
    p++;
    }
    }
    Colorduino.FlipPage();
    }

    It works perfectly with my Arduino UNO + Colorshield + 8×8 RGB Matrix.

  • Matt says:

    I tested your new library yesterday evening, but I could not see any difference. Uno is working, Mega not.

  • Markus says:

    Nice work your library, works great with the Arduino Uno in the IDE1.0.1 but not on the Arduino Leonardo ASSR and AS2 are not declared. Did you have some idea’s about it?

    • lincomatic says:

      THe U2 doesn’t have a Timer 2. I don’t have a Leonardo, so I can’t test, but the code in Colorduino.h that uses Timer2 needs to be modified to use Timer 4.
      This link might help: http://arduino.cc/forum/index.php?topic=107622.0;wap2
      If you get it working, please send me your changes.

      • Markus says:

        Yes, right I have take a look inside the files, but I think thats not all you set the ports of the Atmel328 really “global” and the Atmel32U4 has differents. maybe this must be more specific so it can work for all Arduinos. Something like D6 to PIN and PORT I know it’s written down in the pins_arduino.h. Btw. did I see it right you use the Timer to drive the clock pulse for the Serial in?

  • lincomatic says:

    the ISR in Colorduino.cpp uses Timer 2 :

    ISR(TIMER2_OVF_vect) //Timer2 Service

    All that needs to be done is for an alternate timer to be set up to call it. Hopefully, the other pins being used don’t need to also be remapped.

  • Atko says:

    I added support for the Arduino Mega (1280) and submitted a pull request on github.

  • Markus says:

    YES!!! works,

    how can I send you the files?

  • Giuseppe says:

    Hi there,
    I would like to use a Colorduino to drive 192 white 5mm LEDs in a 12×16 matrix. In other words, I guess I need some serious rearranging of pins and connections, compared to the typical 8x8x3 layout, and to adapt the library accordingly.
    Is anyone aware of comparable efforts in this direction? My googling has not been successful so far.
    Thanks in advance!

    Giuseppe

  • [...] помощью ПО PixelConroller А здесь представлена работа платы colorduino из которой тоже получится замечательный [...]

  • Jean Paul says:

    I get this error when trying to upload the code to the colorduino from an arduino.

    avrdude: stk500_paged_write(): (a) protocol error, expect=0×14, resp=0x9c
    avrdude: failed to write flash memory, rc=-4

    The compilation is OK, just the upload is the problem.

    When i unplug the RX and TX connectors, is now able to upload the code to the arduino board. I suppose that’s it’s a problem with de commucation between the boards. There’s something i’m missing? like a driver? the other thing is that the code that it came preloaded from fabric (R G B colors, rotating), now is not working, not even on the stand alone colorduino mode.

    I’ve done the 5 connections between boards, (Reset-DTR. GND-GND, 5V-VDD, TX-TXD, RX-RXD).

    Both boards are ON

    Hope someone can help, thanks

    • lincomatic says:

      you need to unplug the MCU from the Arduino

      • Jean Paul says:

        wow, thanks for the fast answer… and the good thing is that now is working, and the plasma animation is running beautiful…
        is not very smooth, i can clearly see the “steps” of the changing color.. anyway is very nice, but can it be better?
        i tried to use the RGBmtx animator, standalone and from processing, it runs fine, but when the animator main screen opens, my matrix, after a fast reset, continue doing the plasma animation, unlinked from what i do in realtime, and in the top it says ” No output device found, runing in standalone mode ”
        hope someone can help and share more ideas about what to do and play with the matrix

        thanks

  • Jean Paul says:

    when i run the processing skecth “RGBmtx” , it says that a colorduino is found on the COM 3 port, and the message no device found on the top of the display, is gone.
    But… the plasma animation is still there, and the matrix is not affected by the RGBmtx realtime modifications.
    What else is missing?

    THANKS

  • Jean Paul says:

    I finally did it… I just unpluged the reset cable as it says in another forum, and voilá!
    hope it helps

    • lincomatic says:

      Hmm. That’s interesting. I wonder why it works OK for me. Can you tell me in which forum you saw this? Thanks. Glad you got it working

  • Jean Paul says:

    Hello! here,

    http://www.instructables.com/id/Lampduino-an-8×8-RGB-Floor-Lamp/step18/RGBmtx-Host-Software/

    if you look the comments from user kd7eir almost at the end of the page, he doesn’t say how he discover it.

    By the way, do you have more ideas or codes made by yourself to use to use??, i’m not a programmer so it’s difficult to me import codes that are not made for the colorduino.

  • lincomatic says:

    OK, I will update the Instructable. Sorry, I haven’t done anymore work with Colorduino.

  • Daniel says:

    Hello! I have a couple of questions:

    1) I’m trying to multiplex with an 8×8 RBG LED and code it so that I can turn any pixel on and off whenever I want. Is there such a command built into the Colorduino code? In other words, is there a simple blink program on top of Colorduino.Setpixel?

    2) I notice everytime I plug in my colorduino with my USB, I see a sudden flash. Is there a way to get rid of this? Like attaching a mini surge protector or something?

    Thank you!

  • vahakn says:

    Hi there

    ive wired up my colorduino and Leonardo board. But the plasma demo code wont run.
    My matrix just switches from R to G to B every second. What do I do ?
    any help would be greatly apprecieated
    Vahakn

    • lincomatic says:

      It just go all R, all G, all B? That’s very strange. I have no idea what’s going on. Check your wiring. That is the only thing that could go wrong if you successfully loaded the sketch. Are you using a common anode matrix? Common cathode wiring will not work properly.

  • Jean Paul says:

    I think that you didn’t upload the code into the colorduino… the R G B every one second is the factory code that comes by default. When you uploaded the code in the arduino software, did you saw the message “Upload Complete” ?
    Remember to take out the ATmega microchip from the Arduino before you upload a new code into the colorduino.
    Hope it helps

    • lincomatic says:

      Jean Paul, thanks very much for jumping in with a reply! I think you’re right, that he didn’t upload the sketch properly.. I forgot that the factory code is R/G/B flash.

  • vahakn says:

    Thanks so much for the library and support… Im getting somewhere slowly.
    Do you know how I can run arduino program alongside colorduino. I need to use analog inputs and RX and TX for sending midi signals. Is this possible?

    thanks vahakn

    • lincomatic says:

      Yes, just add more code to the loop() function to do your other processing. Just remember that while the Colorduino code is running, your other code is waiting, and vice versa.

  • David says:

    Hey just want to let you know that I ported your excellent code to run on the ws2801 strips from adafruit. http://curltable.the-yard.net/blog/ws2801-strip-plasma

  • Max says:

    Hi,
    Don’t work for me…
    I have a Colorduino 2.0 and a Arduino MEGA 2560.
    But if I try to load the code, I have this:

    avrdude: stk500v2_getsync(): timeout communicating with programmer
    avrdude: stk500v2_ReceiveMessage(): timeout
    avrdude: stk500v2_ReceiveMessage(): timeout

    apparently, he can’t make the connection with the colorduino

    Please, help me!!!

    Thanks

    • lincomatic says:

      What’s a Colorduino 2.0? I’ve never seen one. Itead still shows v1.3.
      Give me a link. Is it a shield or standalone? My code doesn’t work with a Mega.
      The error you’re getting is because the bootloader isn’t loaded on the Mega.

      • Max says:

        Thank you for answering so quickly!
        I colorduino this:
        http://www.hobbyking.com/hobbyking/store/__26845__Colorduino_V2_0_RGB_LED_Matrix_Driver.html
        It’s probably a Chinese copy…

        But is it possible to program a colorduino with a mega 2560 via the serial link?
        I tried other codes but I still have the same problem …

        • lincomatic says:

          Oh, OK, so you’re trying to use the Mega just as a programmer.
          I’ve found that the MCU usually interferes, so you have to remove it, but that’s not possible on a Mega.
          You should try either a USBTinyISP or an FTDI cable.

          • lincomatic says:

            I forgot to mention.. you can do serial programming only if the bootloader is already installed. Otherwise, you need to use a USBTinyISP to install it. You can also follow the directions for Arduino as ISP in the Arduino Playground to load a bootloader.

  • [...] it: There’s lots of info in Lincomatic’s post, particularly in the comments. Though I found versions elsewhere, I ended up grabbing the plasma [...]

  • Jakob says:

    Hi.. Your code looks very promising for a small project i’m about to start – so thanks for making your work public first of all. I have two questions though.

    1) Do you use i2c to control the boards?

    2) Is there a possibility to control mulitple boards? cascaded or by choosing a adress for each board?

    Thanks in advance
    \ Jakob

  • Dan says:

    It would be nice if this library supported these functions:

    shiftup
    shiftdown
    shiftleft
    shiftright

    read buffer PixelRGB *p = Colorduino.GetPixel

    This would really help with scrolling and animation.

    • lincomatic says:

      thanks for the suggestions. they really aren’t that hard to write. if you want to do it, i’ll merge them into the github repository.
      unfortunately, i’m quite busy w/ other projects @ this point.

  • Dan says:

    Please join the discussion at:

    http://forum.arduino.cc/index.php?topic=182743

    Thank you for your time.

  • BRUNO says:

    Hi evrybody,
    Is anyone know if on the colorduino (mine is v1.3) there is some I/O remaining and where ?
    thanks !

Write a Comment

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>