RGBCommander - Wiring and Custom Animations

Well... I thought I was done with the arcade series of blog posts.  But as I started to actually play the completed arcade, there were little tweaks that I wanted to make.  One was the default "attract" or demo light pattern that ran on the control panel before a game was launched.  As I researched this, I thought I would share what I've learned (and been taught!) about the software that makes this happen.

RGBCommander is the excellent package developed by Gijsbrecht De Waegeneer for control of Ultimarc's RGB buttons and rotational joysticks (ServoStik, UltraStik 360).  Ultimarc makes utilities available, but they are all Windows-based.  Gijs put a lot of effort into making a version that works as well (in some cases I'd say better) for those of us using RetroPie.  A shout out to Gijs as well for assisting me in figuring some of this out!

First, RGBCommander is extremely easy to install and setup... if you just take time to read the excellent documentation!  After installation, you simply have to edit one configuration file, specifying your type of LED board, buttons/wiring scheme and joystick type (if you have 4/8-way sticks).  From there, it just works!  He's also included hundreds of predefined color schemes for arcade/mame games, lighting the proper controls for each game... even to match the color of the original arcade!  So, if a game had 2 player buttons, colored blue and red, when you launch the game, two player buttons will light up in blue and red!  All this with no work on your part once you configure the basic controls.  Not only that, but if you have ServoStiks, it will also automatically set your joystick(s) to 4-way or 8-way as called for by the ROM!  And it is easy to add additional games or or other emulators/games simply by following his examples.  But enough on that... visit his site and you can find out a lot more.

RGB Wiring
Before I get into creating custom light patterns, I want to take a minute to talk about wiring the RGB controls to the control board.  This is because I didn't think ahead to creating various light patterns and this would cause me some headaches down the road.

Above is the Ultimarc I-Pac Ultimate I/O that I used, and will be discussing here.  However, if you have another Ultimarc I-Pac, most of what I cover should be transferable.  There are a total of 96 LED pins on this board... 48 down the left side and 48 down the right side (technically, there is an extra pin in each row, but that's for power/common and is included in the wiring harness, so we are going to ignore that).  Once very important item to note:  the pins on the left (1-48) are RGB but the pins on the right (49-96) are BGR.

If you refer back to when I wired my control panel to the I/O, I wasn't really thinking about lighting patterns, but limiting the amount of extension cables that I needed.  The way it worked out, the player 2 controls are primarily wired to the left pins (1-48) and the player 1 controls to the right pins (49-96).  They are somewhat logically laid out, but I wasn't considering custom patterns at the time.  This will soon come back to bite me (just a bit, though).

RGBCommander comes with a number of defined animation files (called .rgba files).  In the configuration, you can specify which animation file/pattern you want to run when the arcade is in "attract" mode (e.g. not running a particular game).  By default, this is set to "RANDOM" and is what I started out with:

Since my lowest pin was 4 and the highest was 93 and all controls were lighting up in the random pattern, I figured all was good.  So I decided to update the configuration file to try some other patterns.  I found out two things:

• Since my controls weren't wired to the RGB pins in order, the "pattern" wasn't necessarily what was expected.
• Every pattern I tried simply lit my controls in white.  No other colors were observed.

So, I decided to take a peek at the .rgba files to see if I could figure them out and maybe try to build my own.  The .rgba files are actually .xml files laid out as follows:

<anim>
       <frm dec="0,0,0,0,....    0,0"/>
        <tms dec="50,50,50,.... 50"/>
</anim>

Each <frm> represents a "frame" of animation and had 32 numeric entries.  The <tms> indicates how long each frame "plays" and the number corresponds to the number of frames.  Now, I won't go into a lot of detail about RGB values (you can Google it yourself), but basically a color is represented by three values from 0-255... "red", "green" and "blue".  So, a value of (255,0,0) is pure red.  A value of (255,0,255) will result in magenta (red + blue).  

Since I had 96 pins and there were only 32 values in each frame, I (wrongly) assumed each value represented a combination of the 3 RGB values.  But I saw a range of values beside 255, so I couldn't figure this out.

I opted to drop an email to the author, unsure if I'd get an answer.  But many thanks to him, he responded back with a day (and that's saying something with the 6 hour time difference between Indiana and Belgium!).  He explained two things to me:

One, the frame display/delay speed (values in the <tms> tag) may be so short and due to some lag on the controls themselves, they may simply appear to the eye as white.  I increased the value of the delay by a factor of 10 and, viola, I had colors!

Next, he explained that his application was based on prior work that utilized a 32 x 32 grid, but each value represented a single pin in the <frm> tags.  So, the first three values represents pins 1-3 on the I/O board, the next three values corresponded to pins 4-6, etc.  But since the XML "frames" only had 32 values, that meant control of only 10 buttons, with 2 values left over for button 11.  Gijs then explaned to me that his code wrapped, starting with frame value 1 to complete fill in the maximum pins found.  In effect, this meant that if one button or control was set to a particular color, at least one (and maybe two) other controls would also light up, but in different colors due to the single pin "shift".  Here's an example to try to explain:

So, I tried a few simple tests and found this was, indeed, what was occurring.  So, I started trying to create some new patterns by hand.  But between the odd wiring in my cabinet and the 1 pin shift in each frame, it quickly became confusing and, while I could control which button lit, and its color, within the first ten, I could not control individual buttons past that due to the wrapping.  I opted to see what would happen if I tried to put the full 96 values in a single frame to see if it would work.  Thanks to well-written code, it performed exactly as I had hoped.  I could control each individual button and its color:

So, how did I actually create the .rgba (xml) file?  It was a tedious process.  I created a 96 column Excel spreadsheet (one for each pin) and did a lot of copying and pasting, adjusting each row.

Once this was complete, I exported the sheet as .csv, removed the header rows and added the appropriate xml tags around each remaining row.  Yes, it was a pain but it worked! 

So, while it is possible to create your own unique animations, it is a time-consuming, tedious and error-prone process.  I'm considering taking a stab at developing some sort of Linux-friendly app to simplify this process.  Yes, I could tackle this pretty quickly in a Windows environment, but there are already Windows apps out there to do this kind of thing.  But if you've been following my progress, you know one of the reasons I went into this was to learn a little more about Linux.  So, if I'm going to develop some sort of app to create RGB animation files for RGBCommander, it is going to natively run under Linux or not at all!

UPDATE! Helmutcode reached out and let me know he has developed a web-based app that takes the above information and allows you to create an animation file with a nice user interface and without all the kludgy copying and pasting.  You can find his app at: https://www.perfectdigitalboy.com/acp/.  If you have questions about this app, please contact Helmutcode directly from the info on his site, as the app and site are solely his... I have no clue how it works, but I'm just glad I can take development of an app off my list.  Thanks, Helmutcode!

I hope maybe this post fills a gap for those of you running a Raspberry Pi and using RGBCommander and would like to tackle your own custom animation files.

Happy "copying and pasting"!