Overview - Current project state

RGBcommander is a daemon on Linux. It has no gui. It has one logically structured and well commented configuration file that you need to adapt to your configuration. It comes with a convenient shell installer that supports removal. It also has a command line tool that allows you to connect to a running instance. It is not needed during runtime or ever at all actually. It mainly serves as a development tool but it also has some functionality that'll aid during configuration or to diagnose things. Some useful ones in that regard are shown in the 'Parameters' section. It is fast. It starts in under two seconds on a normal pc, seven seconds on a pi and it is completely unobtrusive. It evolved significantly, all received suggestions and feedback were taken into account and this version delivers on all that has been asked. Overall it should provide a smooth experience.

Donate

Due to its nature RGBcommander took a lot of dedication to get it where it is today. In the absence of developer libraries everything has been written from the ground up. It is the only free linux/rpi arcade led and joystick solution. If you have successfully configured it and it serves you well please consider donating a sensible amount. After all, without RGBcommander all those flashy led buttons you purchased for your arcade cabinet would look very very dim... Your donation might spur up feature development and keep it alive. Thank you.

License and Warning

RGBcommander is free for non-commercial, personal use.

If this program causes your computer or other hardware it accesses to blow up or forces it into a catastrophic meltdown than I am :

a) very sorry that this happened to you but also,

b) very much not responsible for that event.

This software has the ability to flash Ultimarc led boards. If you do that you can NEVER EVER get the original animation back for the simple reason that I do not have the original data as there is, to my knowledge, no way to read it.

RGBcommander

Linux v0.4.0.2 beta1
Download

Main features

  • Supports Ultimarc PacLed64, UltimateIO, ServoStik, UltraStik 360
  • Supports GroovyGameGear LED-Wiz
  • Supports rom specific colours, animations and joystick switching
  • Startup animation flashing on Ultimarc led boards
  • Highly compatible due to being frontend agnostic
  • Customisable and fully RetroPie integrated ( rPI2/3 )
  • Supports MAME blinking leds ( emulator and rom specific )

Beta...

It has been tested by some gentle people on linux arm and amd64.

Solrac21, Howard Abraham, Mahuti - Thank you for your time, suggestions and persistence! You helped this program reach 0.4beta status and contributed to its overall quality and stability.

Does 0.4 still exhibit undesired behavior? The nasty things are gone for sure... Time and broader adaptation will tell... If if you do find an issue mail a clear, nicely structured bug report please. A limitation is not a bug. Suggestions are welcome.

Feedback

If you've successfully configured it I kindly ask you to send me an email stating your platform, hardware and features used. That'll help me to get an overview, that is important for me. It'll help me to enhance the program. You can also tell me what you perceived difficult or unclear. You won't be bothered or replied to unless you ask a question. Thank you.

High level

Knowing the way it works combined with the comments in the rgbcmdd.xml configuration file will allow you to understand why things behave the way they do and you will understand its structure. Basically it monitors processes you specify in the cfg file. The daemon waits for the frontend to appear before it kicks in. If no frontend is specified it'll start right away with an animation sequence. So if the frontend runs you have an animation, if an emulator runs you have leds. Each emulator has its own section. Each emulator section contains at the very least a 'default' section and can contain other rom specific sections. When the daemon sees a process it'll light the leds and switch joysticks as needed.

Now there are two special cases. MAME and Retroarch. The Windows and sdl versions of mame both have a different communication system. If RGBcommander sees what's defined in the cfg as real mame, it gets its input from mame itself. That is what allows for the rom specific blinking leds among other things. The daemon also uses a file called minimame.bin. One use of this is if it doesn't find a rom in the preconfigured section it'll use what is in there to deduct how many buttons to light so it matches how it was in the real arcade for example.

In RetroArch most emulators run as a core. RGBcommander uses the input hooks in RetroPie to know what core RetroArch is running. So, as such there is no RetroArch integration but RetroPie integration. A RetroArch core has to be declared as one in the cfg. The way it works is logically the same as with normal emulators with the difference being that you specify the folder name where your roms reside instead of a process name. It looks exactly the same but that is indeed a difference that's clearly commented in the configuration file.

Requirements

It runs on Linux 64 bit and ARM 32 bit. A Linux 32 bit version will probably never exist. It has been tested on Debian Jessie, RetroPie 4.0.2. The ARM build requires minimum RetroPie v4.0.2 - lower versions WILL NOT work - though it is possible to update the RetroPie scripts. Check the RetroPie wiki on how to accomplish that.

It behaves the same on all platforms and all version have the same features.

MAME

not an ideal situation...

At the time of writing the current mame version is 0.181 . During beta testing it became clear that that MAME team has replaced their output system with another one that doesn't have all the features the old one had. This impacts RGBcommander more than other programs that depend on this feature because it completely relies on mame to tell it what it is doing but now mame doesn't do that anymore.

I intend to pursue a fix in the mame source but in the mean time the following applies :

Linux : it can never work with 0.170 and higher because the mame linux interface system has been completely erased so 0.170 - .fixed will be a gaping hole forever unfortunately. Everything below 0.170 works.

Retropie : there are some different mame variants in use. Normally if the mame version you are using has its output system intact then everything below 0.170 will work. 0.170 and up will work except for blinking buttons.

With regards to linux, there is a work around by using the set,rom feature through rgbcmdcon but your frontend has to have the option to execute a command before launching the emulator. This is actually intended for another situation that is explained in the xml file but its result will be that 0.170 and up will work except for blinking buttons. You really shouldn't resort to this unless you absolutely need to as it is a compatibility feature that can't give all the features the integration has. The advice would be to stick with a mame version below .170 on linux atm.

Installation

On the pi: Extract the archive and copy it through ssh to the flash card. Connect to your pi using ssh and navigate to that folder. Issue the following command to make your setup script executable : sudo chmod +x ./setup.sh and then install it by doing sudo ./setup.sh install . It can be removed the same way by doing sudo ./setup.sh remove. After the installation you need to adapt the configuration file. On the pi the easiest way is to issue a sudo pico /usr/sbin/rgcommander/rgbcmdd.xml and adapt it to your system. ctrl x exits and it'll ask you to save the changes. Once saved restart the daemon by doing sudo /etc/init.d/rgbcmdd restart

On Linux: the same as for the pi except that I tend to use gedit and su myself... it is tiresome to always sudo... root is root - period.

Ports used: default the daemon uses port 2724 on all platforms. On Linux an additional port 2701 is used (that one is fixed, it can't be changed)

The log file is your friend...

It really really is. Don't forget it...

On Linux the most convenient way is to open a shell and issue tail -f /usr/sbin/rgbcommander/rgbcmdd.log

Parameters

There is a console program called rgbcmdcon that allows you to try things out. Note that you don't need to do anyhing special with it to have a functional RGBcommander installation. It just needs to be there. It is mainly a dev tool for the gui calls. What follows beneath are some interesting commands from a user point of view.

At any time just type '?' <enter> and it'll show the relevant options for the current situation. When started without parameters it'll try to connect localhost:2724. Nothing stops you from running it from another computer to connect to your cabinet. That is what it is designed to do like so : rgbcmdon 1.2.3.4 2724 . Once connected it'll look somewhat like this :

  ...
  connected to localhost:2724 RGBcommander Linux build 0.4.0
  ?
  get,procdiff    		 run once, start/stop processes, run again to get results
  set,stick,way   		 sets the joysticks to the supplied way (4 or 8)
  stop,animation    		 stops the running animation
  set,animation,anim,speed   	 starts playing the supplied animation ...
  get,animation,anim||* 	 returns xml animation cfg, wildcard * gets all
  get,flashanimations     	 gets all available flash animations
  flash,flashanim,flip(optional) flashes an animation to board - PERMANENTLY erases ...
  flash,preview,flashanim,flip	 approximates how a flash animation would look in flash
  ... and a lot of other commands ... 
  Note that the get,procdiff call can be very handy to determine a process real name during cfg
  
				

File description

Linux:
/usr/sbin/rgbcommander/rgbcmdd		the daemon binary
/usr/sbin/rgbcommander/rgbcmdd.xml	the configuration file
/usr/sbin/rgbcommander/rgbcmdd.log	the log file - gets cleared with every restart
/usr/sbin/rgbcommander/minimame.bin	a binary file that contains specific mame data	
/usr/sbin/rgbcmdd			symlink pointing to /usr/sbin/rgbcommander/rgbcmdd
/usr/sbin/rgbcmdcon			a console program to connect to the daemon	
/usr/bin/rgbcmdcon			symlink pointing to /usr/sbin/rgbcmdcon
/usr/sbin/rgba				a dir containing animation sequences
/usr/sbin/flash				a dir containing flash animation sequences
/usr/sbin/libstd.so.6			C++ lib the binaries have been linked to use
		

Tools used

It is written in C++ and compîled using gcc6. Its main development platform is Debian. The IDE used is Eclipse Neon.1 .

Video

RGBcommander running on RetroPie. It runs exactly the same Linux. The PacLed64 starts with a custom flashed animation sequence. After that you see some normal emulators as well as a mame derivative displaying custom roms followed by a clean shutdown. The PI2 is controlled with a gamepad to be able to record the control panel as a whole. Capturing leds is difficult but I hope it gives an idea what it looks like. In reality it looks much cooler... :)

Flashing animations

Very little space is left on the PacLed64 and UltimateIO boards to store data so animations that are normally being used are simply out of the question due to space constraints. Some nice things are still within reach though. The approach taken was to really minimize the changes in between steps. The algorithm accounts for the number of buttons actually present to maximise the possibilites. Have a look in one of the flash files. It'll be clear. Should you make a cool one please email it to me so that I can include it in the download. Thank you.

Extending RGBcommander

RGBcommander features an output hook system allowing user designed extensions. Dynamic marquees, ambient music are some things that come to mind. Whatever you dream up can be created now...

It is an advanced feature that requires bash scripting skills. Be aware that your code runs with root priviliges. If you create an extension make it generic please. Send it to me and if it passes review I'll make it available on this site.

The daemon also supports monitor rotation using the output hook system's capabilities.

Change Log

0.4.0.1 Custom startup sequence animation flashing broken -> regression -> fixed

0.4.0.1 Custom startup flash sequence fails when pin/button layout is not linear -> regression -> fixed

0.4.0.1 UltimateIO -> right hand side colors reversed or plain wrong -> bug -> fixed

0.4.0.2 Added output hook system, added monitor rotation to output hook system

Known issues

none at his time

Contacting me

Care and time has been taken to provide extensive and correct information. Use it please. Sometimes I receive short messages containing content like :

...I’m having trouble trying to adapt the configuration file on a Retropie. Could you add any extra instructions on how do to that?

or

...the idea appeals to me but I have no clue how to install it on an UIO. Can you help me?

I tend to be helpfull and responsive but obviously this is not going to work. If you need help provide adequate and structured information indicating you tried to solve it yourself and fully read the documentation. Several people did that and all of them received assistance. I appreciate that too as it helps me understand what is being perceived as difficult or unclear leading to enhancements. You can always post a question on BYOAC too. It is a thriving community. Thank you for your cooperation.