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. That tool 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. As some people were asking for a standalone Ultimarc ServoStik switch utility I added one in separate download March 2018.

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

SetServoStik

Linux
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 and RecalBox 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.

Windows

There once was... a Windows build. Actually there still is. I develop it in par with the *nix build as a mental challenge. I find it cool I can cross compile the same sources for different platforms and os's. It's not released nor will it be any time soon.

Source code

I've been asked for the source code on several occasions and as such I've set up git repositories. At the moment the site contains 2 joystick utilities, setservostik and the setultrastik360 I've never released before. I will not open source the 0.4.x code base. 0.5 will be open sourced. It is in its very early stages at the moment... Once it has evolved enough I'll make the RGBcommander repository public and further development will be done in the open.

High level

Knowing the way it works combined with the documentation 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 and RecalBox 4.0.1 RetroPie users : 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. RecalBox users : it has been tested on 4.0.1 - Lower version will most likely not work.

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

MAME

MAME is a huge project and it tends to change heavily and as such it has had different communication systems througout its life time. Some 'non official' RetroPie (or others for that matter) builds even come without one so:

'real' MAME:

Linux : 0.? <-> 0.169 - Auto detection works fine. Rom dependant blinking LEDs are functional through old communication system.

Linux : 0.170 <-> 0.187 Linux integration broken and even completely erased up to a certion version number. Nothing works. I strongly advice against it BUT 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 if you can't use +.188 or higher.

Linux : 0.188 <-> current - Auto detection works fine. Rom dependant blinking LEDs are functional through new communication system. For it to work you need to specify network as OSD output system in mame.ini eg.

	#
	# OSD OUTPUT OPTIONS 
	#
	output          network 

'other' MAME:

If the output system is intact it'll work keeping the above in mind. If it isn't RecalBox and Retropie will work, besides blinking leds that is, due to the specific integration that RGBcommander provides for those two distributions (*see 0405 Change Log below).

Installation

Always deinstall an existing version with that version's installer by doing ./setup.sh remove. You can always backup your config file.

On the pi RetroPie: Extract the archive and copy it through ssh to the flash card. Connect to your pi using ssh (default U/P pi/raspberry) 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 systemctl restart rgbcommander

On the pi RecalBox: Extract the archive and copy it through ssh to the flash card. Connect to your pi using ssh (default U/P root/recalboxroot) 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 nano /recalbox/share/system/rgbcommander/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 /etc/init.d/S99rgbcommander 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

Fixed location:
/usr/sbin/rgbcommander/rgbcmdd		the daemon binary
/usr/sbin/rgbcommander/libstd.so.6	C++ lib the binaries have been linked to use
/usr/sbin/rgbcommander/rgbcmdcon	a console program to connect to the daemon	
/usr/sbin/rgbcommander/rgbparse		a RetroPie/RecalBox integration console program
Symlinks:
/usr/sbin/rgbcmdd			symlink pointing to /usr/sbin/rgbcommander/rgbcmdd
/usr/bin/rgbcmdcon			symlink pointing to /usr/sbin/rgbcommander/rgbcmdcon
/usr/bin/rgbparse			symlink pointing to /usr/sbin/rgbcommander/rgbparse
Default location*:
/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/rgbcommander/rgba		a dir containing animation sequences
/usr/sbin/rgbcommander/flash		a dir containing flash animation sequences

*an optional file /usr/sbin/rgbcommander/default_redirection_dir may exists that contains single line that points 
to an alternate location for the files listed under 'Default location'.
This has been implemented for RecalBox as that project uses a root ro mounted fs.

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.

0.4.0.3 rgbcmdcon set,rom command now also works on mame derivatives.

0.4.0.3 Process monitor didn't detect process when that process was being launched from a python script. -> fixed. The get, procdiff command is now 100% in sync with the process monitoring.

0.4.0.3 Ported daemon startup from init.d to systemd to make it behave correctly on more distro's. RGBcommander now plays nice with GroovyArcade. The following commands are available: systemctl start,stop,restart rgbcommander

0.4.0.3 Added restrictor support to UltraStik360's.

0.4.0.4 Added support for RecalBox

0.4.0.4 Added support for 'faulty' arcade roms. Previously if a rom was unknown in in minimame.bin and by extension mame.xml the daemon showed the default leds for that respective emulator even if a custom rom entry existed. Now the daemon shows the custom rom entry for the 'faulty' rom. It is the author's opinion that one should use correct rom names though.

0.4.0.4 Added support for static maps instead of an animation. This can be used to show the frontend controls on start for example. It can, but doesn't have to, be mixed with animations.

0.4.0.4 Added support for partly install relocation to be able to support RecalBox.

0.4.0.4 Upgraded minimame.bin.

0.4.0.4 Enhanced Retropie (and RecalBox) integration using new rgbparse tool

0.4.0.4 beta 2 Fixed a bug that caused connection issues with non gamepad enabled UIO firmwares. RGBcommander should now function with all UIO firmwares.

0.4.0.4 beta 3 Fixed a bug that caused [ERROR] [signalHandler] invalid access to storage raised when non present hardware had been configured in rgbcmdd.xml

0.4.0.4 beta 3 Added support for 2nd UIO board (see release notes in rgbcmdd.xml)

0.4.0.5 rgbcmdcon set,rom now strips file path - if any

0.4.0.5 rgbcmdcon fixed a bug that caused it to segfault(invalid pointer) sometimes when disconnecting from the daemon.

0.4.0.5 added support for +.188 new MAME output system. *Additional testing required to check how/if it interferes with RecalBox and RetroPie specific integrations (should a MAME version exist that supports that output sytstem on RetroPie/RecalBox)

Known facts or issues

none known at this 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.