Step 18: RGBmtx Host Software

Picture of 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.

evolutiondub8 months ago

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?

lincomatic (author)  evolutiondub8 months ago
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.
m1s73r3 years ago
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.

Thanks a lot!
lincomatic (author)  m1s73r3 years ago
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.


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...


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

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)

Mal3D1 year ago

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!!!

lincomatic (author)  Mal3D1 year ago
cool! send me a pm and i'll tell you where to send it.
sansari27112 years ago
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?
misael1233 years ago
Hi your project is awesome!!!...i try use my colorduino too...but i have a problem i need your help...i connect my arduino board to colorduino with SERIAL connection RX-RX-TX-TX...but the Rgbmatrix not work...Please help me !!!
you will see this in this images
12 - 1.jpg12 - 12.jpg
kd7eir3 years ago
I can load the colorduino slave sketch to the colorduino, but rgbmtx says that there is no device found.

Any suggestions?