LEDSpicer Emitter Plugin & LEDSpicer Tutorial

[mahuti]

For those that use LEDSpicer on Linux platforms, I've written a plugin to interact with it. Updated 12/16/2020

https://github.com/mahuti/Emitter-Plugin

This plugin:

• Changes light profiles while navigating AM based on the currently shown rom.
• Changes light and joystick profiles when a rom is launched.

Plugin Options

Delay Time:
The amount of inactivity (in microseconds) before Launching Emitter

Reset Time:
This is the period of time until the profile resets to the default (if set)

Default Profile:
The name of the profile that should be sent after a game exits & after the reset time. This should be a valid profile name set up in LEDSpicer. If you use dynamic joysticks, the profile should include a rotator profile

Joystick Default Position:
If using dynamic joysticks, you can set a default joystick mode to use while in AttractMode. If you have a default profile set, this option will override it.

The options available for this setting are: Use profile default, Vertical 2-way, 4-way, 8-way, Analog. Your joystick must support the selected mode, or the closest mode will be used instead. In my case, I only have one layout, so my joystick is set to Vertical 2-way by default

Activation Mode:
There are two modes for use in the AM user interface. Manual and Automatic.
Automatic mode: lighting profiles will be changed based on the currently selected rom after an editable period of inactivity.
Manual mode: a button press will change the profile based on currently selected rom.

Key:
The key that will activate the Emitter plugin when in Manual mode

Attract Mode User Interface Navigation

FOR ARCADE SYSTEMS: Emulator System Name must include one of the following words (case doesn't matter), arcade, mame, neo geo, neogeo, fba, final burn, or daphne. Emulator Systems including one of these names will call LEDSpicer to use an arcade profile
 
Example:

Code: [Select]

emitter LoadProfileByEmulator romname arcade --no_rotate

FOR CONSOLES: Emulator System Name must match the LEDSPicer profile name, for instance a system named "Nintendo Entertainment System" will launch a profile named "Nintendo Entertainment System.xml" from the LEDSpicer profiles directory.

Example:

Code: [Select]

emitter LoadProfile systemname --no_rotate
Launching a Game
FOR ARCADE SYSTEMS: This does the same thing as in the user interface, but will allow rotators/restrictors to work.
 
Example:

Code: [Select]

emitter LoadProfileByEmulator romname arcade

FOR CONSOLES: This does the same thing as in the user interface, but will allow rotators/restrictors to work.
Example:

Code: [Select]

emitter LoadProfile systemname
Please check github for other important information.

About LEDSpicer: https://sourceforge.net/p/ledspicer/wiki/Home/
LEDSpicer is used to dynamically change LED colors, manage Joystick profiles (for U360, GGG 49-way, servostiks) and it can also interact with MAME's output system to drive things like Knockers and LCD panels. LEDSpicer has support for controls.ini as well as colors.ini to set LED colors to the original joystick and button colors.

Quick-start tutorial is available a few posts down.

[Sinistar]

For those that use LEDSpicer on Linux platforms, I've written a plugin to interact with it.

The Emitter plugin for AttractMode works with LEDSpicer to change your lighting configuration based on your currently selected ROM in AttractMode.

https://github.com/mahuti/Emitter-Plugin

There are two modes. Manual and Automatic. In Automatic mode, lighting profiles will be changed based on the currently selected rom after an editable period of inactivity. In Manual mode, a button press will change the profile based on currently selected rom.

Please check github for other important information.

I use LEDSpicer to show the keys that will be used when playing a specific game.... trackballs, spinners, etc. LEDSPicer can even change the colors of the buttons/joysticks to the original button color. This plugin just calls the LEDSpicer emitter app to change the profiles dynamically... you need LEDSpicer to do the real work though.

I see you mentioned it working with linux does this work with Rasperry Pi 4 and Attract mode (led spicer that is). I know a ton of people would be all over this if so.

[mahuti]

This was built just for  LEDSpicer. It currently calls LEDspicer's Emitter's LoadProfileByEmulator command based on the rom, either by a command key, or automatically while browsing the romlist.

I am adding the ability to load a profile at game launch as well (which will be useful for also driving U360s and Servostiks, etc.) I should have that up in the next day or so.

It has been tested on Rpi3 and Rpi4. I use Raspberry Pi 4s and 3s on my cabs, so yep.

[mahuti]

This has been updated to include support for ALSO launching LEDSpicer's emitter ToGame, and resetting it FromGame. See the top post for details

[MV19]

Thank you for this! You're a life saver.

[MV19]

Hi. I've got this installed and all seems OK but there's no rom profiles set up. There is a gameData.xml file that comes with LEDSpicer but I don't think that's useable in the way your plugin needs it. Do we have to create all the profiles for each game manually?

Also, does this work with Retroarch or do I have to use a standalone MAME emulator?

Cheers.

[Sinistar]

This was built just for  LEDSpicer. It currently calls LEDspicer's Emitter's LoadProfileByEmulator command based on the rom, either by a command key, or automatically while browsing the romlist.

I am adding the ability to load a profile at game launch as well (which will be useful for also driving U360s and Servostiks, etc.) I should have that up in the next day or so.

It has been tested on Rpi3 and Rpi4. I use Raspberry Pi 4s and 3s on my cabs, so yep.

Hey I hate to ask you to link me to the LED Spicer for PI 4 script as i know google is a thing but i want to make sure im using exactly what you're using (good job by the way) .

[mahuti]

Hey I hate to ask you to link me to the LED Spicer for PI 4 script as i know google is a thing but i want to make sure im using exactly what you're using (good job by the way) .

In the end of my first post, there's an "About LEDSpicer" area with a link to it.

[mahuti]

@MV19. All of your questions are related to how LEDSpicer works. My plugin doesn't pull anything FROM  LEDSpicer, it just pushes data TO LEDSPicer. That said, I'll do my best to answer your questions anyway. I'll admit that LEDSpicer isn't the easiest thing to set up... it takes a bit of understanding to see how things go together. But I think I can give a quick tutorial on it to get anyone interested moving along.

there's no rom profiles set up.

By default no, there aren't. You don't have to set up ANY rom profiles in LEDSpicer, unless you want to, though you do need a default.xml file in the profiles folder. You can use the "craftProfiles" option in the config file for use with arcade games (more on that later) and LEDSpicer will attempt to use the pre-scraped data from mame (gameData.xml) along with controls.ini (if available) and colors.ini (if available) to set lighting based on the games control scheme. So... one profile_arcade.xml file to manage thousands of roms.

There is a gameData.xml file that comes with LEDSpicer but I don't think that's useable in the way your plugin needs it.

My plugin doesn't use anything from LEDSpicer, it just passes the information along to LEDSpicer, and then that does all of the work. gameData.xml is prescraped mame controls data which is used by LEDSpicer to try to dynamically set button configurations based on MAME's reported control scheme for each rom. It's pre-scraped and streamlined to make it work fast and use little memory.

Do we have to create all the profiles for each game manually?

No. For a setup that uses arcade games along side consoles, likely you'd just need one profile per console, and one profile_arcade.xml file for arcades.

Also, does this work with Retroarch or do I have to use a standalone MAME emulator?

It really doesn't interact with the system in any way, it just reacts to information that is passed to it. So, it works with Retroarch (which I use) as well as standalone MAME (which the author of LEDSpicer uses) and can work within AM, and really anything that can call the LEDSpicer Emitter or Rotator apps.

LEDSpicer Setup Tutorial
Before I begin, let me just say, there is a lot of documentation on the LEDSpicer site already. I'm not the author of LEDSpicer, but I do assist on the documentation somewhat, but there's a LOT of capabilities to document. Even though Patricio and I work on the docs to clarify things from time to time, there's just a lot to cover. The following tutorial should get you going with minimal effort hopefully.

Overall concepts
LEDSpicer requires you to:

1. Configure
configure how your LEDs are hooked up to devices, and what you want to call them
configure your logical groupings of LEDs (player1 group, player2 group, marquee, admin button group... whatever. naming is up to you... just know you'll refer to those groups in animations and things. You can have overlapping groups.
configure some options on how you'd like to handle arcade stuff... for instance craftProfiles and some of the other options makes it so you don't have to have a profile for every rom because it will use info from controls.ini and mame (gameData.xml) to try to dynamically light the right leds.

2. Create profiles
create a default profile named default.xml doesn't need much in it...
create a profile_arcade.xml file if you're running craft profiles

3. (optional) Create animations
(if you want animations) create some animation files. refer to them by name in your profiles

4. (optional) Use other plugins
There are a few other plugins available like "input"... if you wanna do that stuff, take a look at the LEDSpicer website for more info.

Step 1: Compile and Install LEDSpicer

Update Retropie to the latest version (Buster as of this writing). LEDSPicer requires tinyxml2 6.0+, which I could not get working on Stretch 4.3(ish) for the life of me due to and endless amount of missing dependencies. Soon as I udpated one thing, I had to update something else. The easiest route is on a fresh install, or a system with tinyxml2 6.0+ already set up.

Download to development folder

Code: [Select]

cd ~/
mkdir develop
cd ~/develop
git clone https://github.com/meduzapat/LEDSpicer.git
cd LEDSpicer
   
Load prerequisites & get tinyxml2

Code: [Select]

sudo apt install build-essential pkg-config libtool libtinyxml2-dev libusb-1.0-0-dev libpthread-stubs0-dev -y
sudo apt install libpulse-dev -y
Compile
my configure options include the boards that I'll use. These are all of the available options: --enable-nanoled--enable-pacdrive --enable-pacled64 --enable-ultimateio --enable-ledwiz32  --enable-howler --enable-raspberrypi Enables RaspberryPi GPIO

Code: [Select]

sudo sh autogen.sh
 ./configure --enable-ultimateio --enable-ledwiz32 --enable-pacdrive --enable-alsaaudio
make clean
make -j5
sudo make install

Figure out where your files are stored
LEDSpicer has 2 important things to edit. 1. ledspicer.conf (configuration file) and 2. ledspicer profile files
The configuration file is either in /etc/ledspicer.conf for most linux systems or the default for raspberry pi is /usr/local/etc/ledspicer.conf
The profiles for ledspicer is either stored in /usr/share/ledspicer  for most linux systems or the default for raspberry pi is /usr/local/share/ledspicer
The rest of the tutorial ASSUMES YOU'RE USING A RASPBERRY PI.

Install UDEV Rules
   

Code: [Select]

sudo cp /usr/local/share/doc/ledspicer/examples/21-ledspicer.rules /etc/udev/rules.d/
sudo chmod 744 /etc/udev/rules.d/21-ledspicer.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
Add your user to users and input groups

Code: [Select]

sudo usermod -a -G users pi #replace user with your username
sudo usermod -a -G input pi #replace user with your username
Step 2: Configure

Copy & edit basic configuration
Here's the raspberry pi version of copying an example ledspicer.conf configuration file. For reference I've also attached my personal configuration file & profiles to this post

Code: [Select]

sudo cp /usr/local/share/doc/ledspicer/examples/ledspicer.conf /usr/local/etc/ledspicer.conf
sudo pico /usr/local/etc/ledspicer.conf
   


Once you have some of the basic files set up, you'll need to configure them. See my ledspicer.conf file for how I use it. Here's some of what i have set up in my conf file:

Code: [Select]

<?xml version="1.0" encoding="UTF-8"?>
<LEDSpicer
    logLevel="Error"
    port="16161"
    version="1.0"
    type="Configuration"
    fps="30"
    userId="1000"
    groupId="1000"
    colors="myColors" <!-- I add stuff (like the colors ON(white) and OFF (black) to the basicColors.xml file, so I use one called myColors.xml -->
    craftProfile="true" <!-- I use craftProfile because this parameter makes it so arcade games can utilize controls.ini, gameData.xml and colors.ini to generate led lighting configurations for multiple roms using a  single profile -->
    colorsFile="true" <!-- uses colors.ini -->
    dataSource="controls.ini,file"  <!-- looks in controls.ini first, then gameData.xml (file) . see craftProfile above-->
>

Add default profile

Profiles basically just tell LEDSpicer if you want to use animations or music or input plugins or whatever. Most of mine are pretty minimal. Check LEDSpicer's docs for more information. Things like "alwaysOnGroups" or "alwaysOnElements" may be important details for you, but i don't use them much. 

Code: [Select]

sudo pico /usr/local/share/ledspicer/profiles/default.xml
Mine has basically just this:

Code: [Select]

<?xml version="1.0" encoding="UTF-8"?>
<LEDSpicer
        version="1.0"
        type="Profile"
        backgroundColor="Off"
>
<!-- whatever animations, plugins, etc goes here -->
</LEDSpicer>
Create a "profile_arcade.xml" profile to use with craftProfile

The file can have basically nothing in it like my default.xml file. Mine says to use the "INPUT" plugin for 3 roms. You wouldn't need to have those in there though.

Here's my profile_arcade.xml file that I use:

Code: [Select]

<?xml version="1.0" encoding="UTF-8"?>
<LEDSpicer
version="1.0"
type="Profile"
backgroundColor="Black"
>
<inputs>
    <input name="digdug"/>
<input name="galaga"/>
<input name="qbert" />
</inputs>
</LEDSpicer>

Craft profile does the heavy lifting for arcade stuff so you don't have to have a profile for EVERY rom. If there is a profile for a specific rom you want to override the craft profile with, just add something like this: profiles/arcade/digdug.xml

Set up profiles for any consoles you want to run
you can name them whatever you'd like: "nes.xml" or "Nintendo Entertainment System.xml"... just remember that the name of the file will be used to load the profile. When using the Emitter plugin I made, whatever the "System Name" is set to in AttractMode will be used to call the profile. They NEED to match otherwise LEDSpicer won't know what you're looking for.

Set up any animations you want.
   
 Take a look at mine for an example.

Step 3: Setup LEDSpicer daemon to run as root at startup

Once you have some basic profiles and the configuration done, set up the system to run as a service. This is OPTIONAL, but if you have a dedicated cabinet, probably a good idea. If you don't want to run it like this, there are instructions further down on just running it in the background
   

Code: [Select]

sudo cp /usr/local/share/doc/ledspicer/examples/ledspicerd.service /etc/systemd/system
sudo systemctl enable ledspicerd.service
Restart.

Once you've restarted you can stop, restart or start the ledspicerd (yes ledspicerd with a d) daemon using:

Code: [Select]

sudo service ledspicerd restart
sudo service ledspicerd stop
sudo service ledspicerd start

ANY TIME a profile is edited, or the conf file is edited, you need to restart the service to use it.

Step 4: Use LEDSpicer's Emitter app to launch profiles

The Emitter app is what sends commands to LEDSPicer. LEDSPICER MUST BE RUNNING FOR THIS TO WORK. Here's an example that will launch a craft profile. All arcade systems (mame, daphne, fba, etc) should be called with "arcade" to use the craft profile system. Any other name will look for profiles in a folder of that name within the profiles folder.

Code: [Select]

    emitter LoadProfileByEmulator digdug arcade
example to load a specific profile. This profile would be named "attract.xml" within the profiles folder

Code: [Select]

    emitter LoadProfile attract
Additional Information and Useful Commands
You can also just launch the daemon any time (if the service is not set up, or not already running)

EACH OF THESE COMMANDS REQUIRES THE SERVICE NOT BE RUNNING ALREADY, so

Code: [Select]

sudo service ledspicerd stop if you want to use these testing capabilities
Run LEDSpicer daemon in the backround

Code: [Select]

    ledspicerd 
Run LEDSpicer daemon in the foreground to check what it's doing

Code: [Select]

    ledspicerd  -f
Get help

Code: [Select]

    ledspicerd  -h

Code: [Select]

    emitter -h
Test Individual Leds

Code: [Select]

    ledspicerd -l   
Test Configured Elements

Code: [Select]

    ledspicerd -e   
Test profile
this is a good way to tell if your profile xml works or not if you're having problems.

Code: [Select]

ledspicerd -p defaultif this errors out, it's likely due to an XML configuration issue.

Look at logs

Code: [Select]

    cat /var/log/syslog | grep ledspicer
    cat /var/log/syslog | grep LEDSpicer
To capture inputs of gamepads

   

Code: [Select]

inputseeker   
To scan for events in MAME games (for the input profile), run this in a separate terminal window while running a mame rom
   
   

Code: [Select]

nc -v localhost 8000
To update: git pull from the development folder, then compile

[Sinistar]

Hey I hate to ask you to link me to the LED Spicer for PI 4 script as i know google is a thing but i want to make sure im using exactly what you're using (good job by the way) .

In the end of my first post, there's an "About LEDSpicer" area with a link to it.

Mahuti is this your software? great job by the way

[mahuti]

The plug-in is. LEDspicer is not. I do help a bit here and there with documentation stuff for it, but its not my software.

And thanks.

[Edge]

Just tried installing this plugin on a fresh AttractMode/linux install.  Unfortunately, the plugin must have a syntax issue.  When I go to the Emitter plugin options in AttractMode, it only allows me to enable/disable the plugin.

I tried looking through the plugin.nut, but couldn't easily find the syntax issue.

Does anyone have this plugin working?