Step 18: RGBmtx Host Software

The host software, RGBmtx, is a Processing sketch. It is a heavily hacked up version of mtxControl (thanks, Tobi!), and excellent visual animation editor for RGB matrices. Processing is a simplified version of Java, much as Arduino is a simplfied version of C++.
I have included pre-compiled executables for Windows, OSX, and Linux, which you can directly run without installing Processing on your computer. You can find them in RGBmtxAppsV1.1.zip. They still require Java, so if you don't have Java installed on your computer, download it from java.com. If you don't want to play with the source code within the Processing IDE, skip to Using RGBmtx below.


The serial buffer has been decreased to 64 bytes, which is too small for RGBmtx to properly communicate with my ColorduinoSlave sketch. RGBmtx will just freeze up your Colorduino, and not work correctly.
To fix it, you must exit the Arduino 1.x IDE and edit modify hardware\arduino\cores\arduino\HardwareSerial.cpp.
Look for the line


and change it to


Then restart Arduino 1.x and re-upload the ColorduinoSlave.pde sketch to your Colorduino.

If you have trouble with communication between RGBmtx and the Colorduino, try disconnecting the connection between DTR and Reset.

Working with the Source Code in the Processing IDE

The full source code to RGBmtx is contained in RGBmtxsrcV1.1.zip.

RGBmtx relies on a Java Colorpicker. Before you can run the sketch, you must copy colorpicker.jar /libraries/colorpicker/library/colorpicker.jar. Restart the Processing IDE if it's already running, so it can find the newly installed library.

Copy the contents of the RGBmtx folder to /RGBmtx, and load RGBmtx.pde into Processing.
You should be able to launch it by clicking the Run button in the Processing IDE.

Using RGBmtx

If your Colorduino is connected to your host PC via a serial port, RGBmtx will automatically find it. The scanning for the device occurs only on startup, so make sure to connect it to your computer before launching RGBmtx. If the Colorduino is not connected, then Device:Slave will be grayed out, and you will only be able to run it in Record mode.

To create animations for your matrix, simply use the built in editor in Record mode. When editing frames while the Colorduino is connected, the matrix will instantly update in realtime. Click on the color patches to select the current drawing color. To select a color which is not in the default palette, hold down the CTRL key while clicking a color patch to pull up an RGB color picker (Note: for some reason that I can't figure out, pulling up a color picker sometimes freezes up RGBmtx. Therefore, make sure you save your work first). The little buttons on the right, bottom, and bottom right corner allow you to fill a whole row, column, or the entire matrix with the currently selected color. You can use the matrix as a mood light by filling it with a single color.

To save a set of frames to your PC, click Save to: File. RGBmtx can save in two different formats: BMP and MTX. If you specify a filename without an extension, it will save to Windows BMP format, and the filename will automatically be appended with .bmp. If you specify a filename ending in .mtx, the data will be saved in a text file format instead. You can also create or edit animations with any BMP-compatible graphics editor (.bmp), or, if you prefer a text editor (.mtx).

To load a previously created frame set, click Load from: File. If you specify a filename without an extension, it will automatically append .bmp. If you want to load a .mtx file, you must explicitly type the whole filename. I have included some sample framesets in framesets.zip, which you can download below.

You can cycle through RGBmtx's various modes by repeatedly clicking the Mode button. The modes are:

Record - create or load a frame set

Play - play the currently loaded frames. I have attached some sample frame sets below.

Plasma - run plasma mode

Snow - display a snowflake-like effect

Meteor - similar to Snow mode, but with trails

Music - music synchronization mode. Optional. You must add the music synchronization circuit described in the next step.

In the Play, Snow, and Meteor modes, you can control the playback speed with the up and down arrow keys on your keyboard.

framesets.zip contains the following sample framesets:

spaceinvaders.bmp - Space Invaders
tetris.bmp - Tetris simulation
music.bmp - suitable for synchronizing with music

mal_animations.zip contains some cool animations that were created by Mal3D

If you make any framesets that you think are really cool, please send them to me, and I'll make them available for everyone to download. For that matter, please send me any good upgrades you make to RGBmtx or my Colorduino library.

UPDATE 2016-10-10:White-Tea has written MagicMatrix, an alternative host controller software in Java. I have not tested it myself, as my Lampduino is currently inoperable. Github repo for MagicMatrix:


his announcement comment:


<p>Hi, thanks for your instructions! I created the matrix and after a year and half I have finished a first version of my own host software (compatible with your slave code):</p><p><a href="https://github.com/wietsebuseyne/MagicMatrix" rel="nofollow">https://github.com/wietsebuseyne/MagicMatrix</a></p><p>I started this because your host software wasn't always working properly on my computer and I always had to build it with Processing in order for it to work.</p>
<p>White-Tea, very cool!!! Thanks so much for sharing! I will link your new software in the Instructable, too.</p>
Is it possible to put a 330 ohm transistor on all wires of the R/G/B pins, like you did on the 5x5 coffee table. So i dont have to worry about leds being burnt or shorting my Arduino/Colorduino. Could you also explain me how to hook up the Colorduino with a Arduino Leonardo (clone).<br><br>Thanks in advance.
<p>Iv managed to get this running fine from my MacBook, but im struggling to get RGBmtx to run on raspberry pi, using the linux version. I have tried downloading processing and running the source code through there, but I cannot get it to work. Any tips on getting the software to run on a Raspberry Pi?</p>
I haven't tried running it on anything other than Windows. If it's having trouble finding the Colorduino, have a look at Colorduino.pde. The function openPort() scans for the serial port. Perhaps you can try hardcoding the actual port name into that function and see if that works.
I cant get the software to open at all on raspbian.
<p>Try this: <a href="http://cagewebdev.com/index.php/raspberry-pi-running-processing-on-your-raspi/" rel="nofollow">http://cagewebdev.com/index.php/raspberry-pi-runni...</a></p>
Ok this step is a little bit too complicated for me... I just want to control my 8x8 RGB Matrix with this software, so which code do I upload on my arduino? And were should I put RGBmtx.pde? I'm on a mac... Please give me a detailed step by step answer so that I can comprehend the single steps.<br><br>Thanks a lot!
RGBmtx.pde runs in Processing on your Mac. You need to download and install it. Follow Step 17 to load ColorduinoSlave.pde into your Arduino.
<p>Hello,</p><p>I am using a Mac and having a hard time getting RGBmtx to see the Colorduino. I am totally new to this. I am using a USBtiny which works to upload the slave sketch. I then have a Arduino Duemilanove board with the chip removed and connections from the Arduino Reset to DTR,TX to TX, RX to RX. The Arduino was getting power from the USB so i didn't use the 5V and ground connections. RGBmtx still says No output device found, running in standalone mode., Do I need to edit the Serial speed settings? If so where can I do this on the mac. Where is the place to edit the line of code. Sorry for the basic questions. Just having trouble with RGBmtx...</p><p>Thanks!</p>
<p>dunno if you have solved this already, but I was having the same issue. The reset pin needs to be connected for programming the board, but remove it before starting up RGBmtx, then the software should see the </p><p>colorduino on startup. I Also programmed the board with Arduino IDE 022 which has the right serial buffer, to save me messing around with too much in the Arduino software. (I am still extremely new to this whole thing and really dont understand most of what I am doing) </p>
<p>It took a couple of days as am very new to programming and arduino, but finally I got it working with the RGBmtx software. Now i just gotta figure out how to make it standalone. Eventually i want to be able to DMX control it. Thanks for the tutorial, defiantly the most comprehensive I was able to find. </p><p>In order to make this work I took the ATmega chip out of the Arduino chassis, and used the chassis as a USB to serial adaptor to program the colorduino directly. Is there any way of saving completed bitmaps onto the Arduino chip and utilising this to send the data to the colorduino rather than a computer? </p>
<p>Really nice work ! Thanks for sharing, keep on going, that's great</p><p>I rarely sign in to comment stuff, but i did it just to say how i was amazed and find this creation really nice.</p>
<p>I've read &quot;Instructables&quot; for quite a long time, but I gotta say Sir, you &quot;forced&quot; me to create an account just so I could comment on your work here. It's easily the best, most thorough &quot;how to&quot; tutorial I've ever seen here. You really know what you're doing and how to explain it. Impressive.</p><p>I don't plan to make one of these but you gave me some great ideas I'd been looking for for a while for another project. So thank you. Again, impressive. :)</p>
<p>will this work going 5x13 or can it only be 8x8? </p>
5x13 is 65 LED's. The Colorduino can only handle 64.
<blockquote>You needn't be super precise</blockquote><p>Unfortunately with this material it doesn't work like that ... 2mm cutting rabbets/slits with 3mm material thickness isn't a helpful combination ;) A dremel has to be used to widen all 96 slits.</p>
<p>Since you're using dibond, won't the aluminum short out the LEDs when you press them into the slits? I guess you have to cut wider slits, insulate the wires, and then hot glue the LEDs in.</p>
<p>I'm going a different way, cause of 140&deg; angle diffuse leds... On the backside a plate will be mounted, holding all leds which are facing toward the front. Right now the soldering part has to be finished, which will take &quot;some&quot; time ;)</p><p>I will keep you informed!</p><p>Btw.: Thanks alot for this great guide, lincomatic!</p>
<p>Dibond (3mm) is used instead of foam ... more than once i was thinking about stopping and using foam like lincomatic did ... ;)</p>
<p>You, my friend, have incredible patience! Looking forward to seeing the completed build!</p>
<p>Hopefully i don't have to take it apart again, cause the connections are very tight/strong (2mm slits / 3mm material) Much ironing left to do ...</p>
<p>Nearly 20m cuttings with circular saw (cause of the dibond material used) had to be made.</p>
<p>I finalllly finished wiring and building everything and testing my LEDs and power supply today. I was planning to power the array from the screw terminals, but when I went to attach the power supply I realized the colorduino I was sent did not have a switch to slide between &quot;header&quot; and 'terminal&quot; power sources. I was able to find a picture of both (so clearly they manufacture it both ways?) and have included it below. The one on the left is what every tutorial seems to depict and somehow I ended up with one like the righthand picture. I was curious what to do in this situation- will powering it through the terminals without the switch in place cause a problem to my the Colorduino or my LEDs?</p>
<p>I heard back from iTead and their reply is below: </p><p>&quot;We <br>have soldered 0R resistors on that position of the switch. You can add 9V <br>or other power supply on VIN pin.&quot; </p><p>I powered my array with 6V 1A through the screw terminals and it works perfectly.</p>
<p>The image quality on this is miserable (sorry!) but since this was a gift for someone, I don't have it around to take a better picture of. I'm happy with how it turned out. Used a Lexan enclosure for the array, with black foam board instead of white, and vellum sheets inside to diffuse the light I used black glossy spray paint on the bottom 2.5&quot; to hide the wires/colorduino/usbtinyisp programmer.</p>
<p>just FYI, the itead product links no longer work</p>
I can load the colorduino slave sketch to the colorduino, but rgbmtx says that there is no device found. <br> <br>Any suggestions?
I discovered the source of my communications error! When RGBmtx is launched it was resetting the serial port connection to the Colorduino, causing it to not see the Colorduino. <br> <br>Instead of plugging my programmer directly into the Colorduino, I used female to female cables and connected GND, VCC, RXD, and TXD. I did NOT connect DTR. By not connecting DTR, I prevented the serial port reset from affecting the Colorduino, and RGBmtx was able to see it!
<p>Thanks! That fixed my problem, too! :)</p>
<p>Glad to help!</p>
<p>Still new to the whole Arduino, Colorduino thingy, but thanks to you, I am able to use the RGBmtx to create some animations that work on the Colorduino! I used the animation code from Adafruit to do another Space Invader animation, but I don't know where to send it to you. Thanks!!!</p>
cool! send me a pm and i'll tell you where to send it.
Hey, Congrats for the great idea!<br>I&acute;m building mine and would like to know if there are any changes if I use a 24awg wire instead of the 30awg one...<br>Thanks!
Will this work with an arduino UNO rather than Duemilanove?
I have a problem with rgbmtx. I connected Colorduino, and the matrix of LEDs, to the PC via Arduino Duemilanove (without microcontroller). However, when using rgbmtx, there is a random delay in the display of frames. it is as if some frames were skipped, as during the animation LEDs rx-tx arduino blink correctly but the frame does not show all on the matrix. anyone have any ideas as to the reason for this? thanks
I just love this project and I really want to make one as a coffee table like in the picure I found on google. But there is one problem i would like to solve. In you instructions you said that if its not connected to the computer it can only display the plasma program because the memory is to small to hold other sketches. Now is my question if there is any way to increase the memory ? A external memory I can connect to it or something like that ? I've been searching on google without succes. It would be a shame if I had to connect my coffee table to my pc just to put something else on there then the plasma or to make it react to music. Thanks
I was wondering, did you take that picture or did you get from google?
Did you read my post ? Apparently not. It is in the first sentence.
I sort of skimmed through it I wasn't really awake yet
Would the microSD breakout board be an option ? How would I connect this and program it to make it work ?
Yes, you need to store the animations in files on the SD card, instead of feeding them via the serial link
oke thansk I'll give that a try
really cool lincomatic
I'm having some trouble getting RGBMtx to recognize the device. I have the Colorduino connected via USBTinyISP and the ColorduinoSlave sketch is uploaded (the plasma works, but only if the USB is plugged in as well). Any tips to get RGBMtx to recognize?
What resistor did you use? It looks like you have a large one hooked up to your Colorduino.
I didn't use any large resistors. The current limiting is all done on the board.
me podr&iacute;as ayudar como hacer un texto en colorduino hasta ahora solo he logrado poner letra por letra pero es mucho el espacio entre ellas, es asi. <br> for(j = -7;j &lt; 7;j++) <br> { <br> DispShowChar('u',255,255,255,j); <br> delay(i); <br> } <br> for(j = -7;j &lt; 7;j++) <br> { <br> DispShowChar('d',255,255,255,j); <br> delay(i); <br> } <br> for(j = -7;j &lt; 7;j++) <br> { <br> DispShowChar('i',255,255,255,j); <br> delay(i); <br> } <br> asi se pone letra por letra pero quisiera meter una palabra completa como hacerle te lo agradecer&iacute;a mucho.
Also, what USB adapter/parts do I need in order to connect to my computer?

About This Instructable




Bio: For more information on my projects as they develop, visit my blog: http://blog.lincomatic.com
More by lincomatic:Turn Your Bike Into a Party Machine Lampduino - an 8x8 RGB Floor Lamp Yet Another Daft Punk Coffee Table (5x5 LED Matrix) 
Add instructable to: