Programs - meduzapat/LEDSpicer GitHub Wiki
Programs and Basic Usage
This section will describe the normal program usage, for development and other uses go to their respective sections.
LEDSpicer daemon
The primary program responsible for direct communication with devices to control LEDs on the board is ledspicerd.
This versatile program is designed to handle different hardware and system setups.
It is intended to be initiated as a daemon when the entire system boots up.
If not configured as a daemon, it can be run in the foreground (details documented below).
Important:
The LEDSpicer daemon can operate as either a normal user or root.
When run under a normal user, ensure that anything the interface is readable and writable by that user.
Configuration files only require read access. For non-root users, a rules file has been included for convenience.
Some plugins also needs special rights to work.
Upon execution, the program first scrutinizes command line parameters and loads the configuration file. The default location for the configuration file can be altered (refer to the help section for more information).
Options
-f --foreground (run LEDSpicer in foreground)
If you don't need to run ledspicerd as a daemon, it can be executed in the foreground.
This is useful for testing, but in regular operation, it's recommended to let the process run as a daemon when the system launches.
When the daemon is executed, it will run detached and independently, logging important information to the system's log (syslog).
ledspicerd -f
or
ledspicerd --foreground
-h --help (get help)
To see the help list, use this command line parameter:
ledspicerd -h
or
ledspicerd --help
-c --config (load a different configuration file)
To use an alternative configuration file, use the -c option
ledspicerd -c /path/to/conf/file
or
ledspicerd --config /path/to/conf/file
-d --dump (dump configurations)
The program can display the current configuration by doing a dump of everything on it:
ledspicerd -d
or
ledspicerd --dump
This will display the program's internal settings as they have been read from the configuration files.
The output is crucial when creating and debugging configurations.
This dump will also read and display the colors file, the default profile, and anything the default profile loads.
Connection diagrams, elements, groups, etc., will also be displayed, along with details about the mapped pins to LEDs and elements.
-p --profile (dump profile)
This will display the current profile by doing a dump
ledspicerd -p profile_name
or
ledspicerd --profile profile_name
This will load the profile and verify that it is compatible with the configuration, and then display the settings on screen.
-l --leds (LEDs test)
This interactive mode will read the user input and turn on LEDs on the board, really useful to map and test your physical setup
ledspicerd -l
or
ledspicerd --leds
-e --elements (elements test)
This interactive mode will use the user's configuration and turn on elements on the layout, useful to test that the LEDs are assigned correctly.
ledspicerd -e
or
ledspicerd --elements
Emitter
This program sends commands to ledspicerd.
Options
-h --help (get help)
Help lists all the available Emitter options. To see the help list, use this command line parameter:
emitter -h
or
emitter --help
-c --config (change configurations)
To use an alternative configuration file, use the -c option
emitter -c /path/to/conf/file
or
emitter --config /path/to/conf/file
Changing to an alternative configuration file is only temporary, and should be paired with a command. This example shows an alternative configuration file being loaded to display a LED profile for galaga.
emitter --config /path/to/conf/file LoadProfileByEmulator galaga arcade
List of commands
LoadProfile
To load the first valid profile from a list of profiles.
emitter LoadProfile profile1 profile2 profileX
LoadProfileByEmulator
This command loads a profile based on information about the ROM and emulator. It takes 2 arguments, ROM name and emulator name.
For all flavors of MAME just use "arcade" as the emulator name.
emitter LoadProfileByEmulator rom emulator
When this command is run, LEDSpicer will attempt this steps in the following order:
- Load Rom Profile inside emulator directory.
- If step 1 fails, if the emulator is "arcade", it will try to load a Controller Profile.
- If the emulator is "arcade", load a Player Profile
- Load an Emulator Default Profile
- Load the default profile
ex: emitter LoadProfileByEmulator galaga arcade to load the profile for galaga.
Rom Profiles
A ROM profile is the most specific profile type.
It must be named after the ROM and placed in a folder named after the emulator.
For instance: ledspicer/profiles/arcade/galaga.xml will have special parameters only for galaga.
You can create symlinks to support several games with the same profile without the need to change multiple files if a change is needed, or just copy paste.
Controller Profiles (for MAME ROMs only)
Controller Profiles is basically, profiles generated by the ROM hardware, are very usefull to group ROM with simillar controller's hardware, is the original implementation of loadable profiles, this is an alternative to the crafted profiles. If crafted profiles are enabled, forget about this.
This feature works out of the box for MAME or any MAME clone, and LEDSpicer will attempt to load a profile based on the controllers a ROM uses.
This is achieved by querying MAME, reading the gameData.xml file, or the controls.ini file if those files are available in your LEDSpicer data directory.
Controller profiles should be named presicely using the following convention: Tx_By where:
- T is the controller name.
Controller names can be any one of the following:- JOYSTICK
- PADDLE
- PEDAL
- DIAL
- MOUSE
- LIGHTGUN
- TRACKBALL
- x is the number of that Controllers, ex 2.
- B is just the letter B, for buttons.
- y is the number of buttons.
example: to create a profile for games with only one player, that use a joystick and have 2 buttons: JOYSTICK1_B2.xml
example: to create a profile for games with two players, that use a trackball and have 3 buttons: TRACKBALL2_B3.xml
Player Profiles need to be placed in the directory named after the emulator. For instance: ledspicer/profiles/arcade/JOYSTICK1_B2.xml
Player Profiles (for MAME ROMs only)
Similar to the Controller Profiles, but it does not concern itself with the type of control the ROM uses, focusing solely on the number of players.
When the emulator is MAME or similar, LEDSpicer will attempt to load a profile based on the number of players and the buttons it uses.
This is achieved by querying MAME, reading the gameData.xml file, or the controls.ini file if those files are available in your LEDSpicer data directory.
Player profiles should be named using the following convention: Px_By
- P is just the letter P, representing player.
- x is the number of players.
- B is just the letter B, representing button.
- y is the number of buttons.
For example, to create a profile for games with only one player that has 2 buttons: P1_B2.xml
For a game with two players and 3 buttons: P2_B3.xml
Player Profiles need to be placed in the directory named after the emulator. For instance: ledspicer/profiles/arcade/P1_B2.xml
Emulator Default Profile
Emulator default profile should be named after the emulator, and placed in the profiles directory.
example: ledspicer/profiles/arcade.xml
This is used to load a profile based only on the emulator name.
FinishLastProfile
To terminate the current profile (doesn't affect the default).
emitter FinishLastProfile
SetElement
To change an element's background color until the profile ends.
emitter SetElement elementName color filter
ClearElement
To remove an element's changed background color.
emitter ClearElement elementName
ClearAllElements
To remove all elements' changed background colors.
emitter ClearAllElements
SetGroup
To change a group's background color until the profile ends.
emitter SetGroup groupName color filter
ClearGroup
To remove a group's changed background color.
emitter ClearGroup groupName
ClearAllGroups
To remove all groups' changed background colors.
emitter ClearAllGroups
Input Seeker
Input seeker simplifies the input plugin setup. When the user interacts with any control or button, it will display the device name and the code needed to setup the input plugin. Note: this program doesn't need configuration and takes no parameters. Call it, and it will display input events for any available control or button.
inputseeker
Inputseeker will display the devices it detects attached to the system. Upon user interaction it will start displaying events; each row will look something like this:
Listen Event: some_device_name-event code: 30 Type: KEY(On)
Listen Event: some_device_name-event code: 30 Type: KEY(Off)
Where:
- some_device_name-event is the device name
- code: 30 is the key code (key 'a' in this case)
- ** Type: KEY(On)** is extra info, it means that you pressed a key/button, and when it says Off means you released that key/button. Normally, key on/off events are shown in pairs
This program also detects other types of events including MOVE and others as well as relative and absolute events like mouse, analog joysticks and more.
Rotator
This program handles dynamic joystick & restrictor mode settings for:
- USB Ultimarc UltraStik 360.
- USB Ultimarc ServoStik.
- USB GroovyGameGear GP-Wiz40 with rotary support.
- USB GroovyGameGear GP-Wiz49 with 49-way support.
- SERIAL GRS TOS Restrictor.
Features:
- Sets joystick encoder modes.
- Loads joystick profiles into UltraStik 360.
- Handles an unlimited number of devices per call.
Usage:
- Add a "restrictors" section to your ledspicerd.conf configuration file located at /etc/ledspicerd.conf (or whatever you have it):
<restrictors>
</restrictors>
- Within the restrictor section, add a node for each joystick.
There are a few parameters required for each node, so that Rotator can make changes to the correct joystick for the correct player.
name: Name can be one of the following: UltraStik360, ServoStik, GPWiz49, GPWiz40RotoX, TOS428.
boardId: For USB restrictors only, unnecessary if you only have one restrictor with ID 1. Specify a boardId if you ordered multiple of the same type to be used together on the same control panel (usually between 1-4 provided by the manufacturer).
port: For SERIAL restrictors only, unnecessary if you only have one GRS TOS Restrictor, the PORT will be detected automatically; In other cases, check the system to find the correct port number, if ignored, it will attempt to auto-detect the port.
Additional parameters are available and vary depending on the hardware. Please refer to the restrictors and ratators section or documented examples for details on these parameters and their specific requirements.
Some hardware, like the servostik, can handle 2 restrictors per controller together, so changing one will also change the second, in this case if you set in the config, ex player 1 and player 2, and you move only player 1 the controller will move both anyway, so setting player 2 is optional in this case.
Example Configurations
<restrictors>
<!-- Ultrastik -->
<!-- Player 1 with UltraStik -->
<restrictor name="UltraStik360" boardId="1">
<map player="1" joystick="1" id="1"/>
</restrictor>
<!-- Player 2 with UltraStik. Has physical restrictor installed & has mouse mode enabled-->
<restrictor name="UltraStik360" boardId="2" hasRestrictor="true" handleMouse="true">
<map player="2" joystick="1" id="1"/>
</restrictor>
<!-- ServoStik -->
<!-- Player 1 and player 2 (optional) with ServoStik -->
<restrictor name="ServoStik" boardId="1">
<map player="1" joystick="1" id="1"/>
<map player="2" joystick="1" id="2"/><!-- optional -->
</restrictor>
<!-- GPWiz49 -->
<!-- Player 1 with GPWiz49 & Happs 49-Way Joystick -->
<restrictor name="GPWiz49" boardId="1">
<map player="1" joystick="1" id="1"/>
</restrictor>
<!-- Player 2 with GPWiz49 & Williams 49-Way Joystick -->
<restrictor name="GPWiz49" boardId="2" williams="true" />
<map player="1" joystick="1" id="1"/>
</restrictor>
<!-- GPWiz40 With Roto-X Rotary Control -->
<!-- The GPWiz40RotoX supports up to 2 joysticks per encoder!-->
<restrictor name="GPWiz40RotoX" boardId="1">
<map player="1" joystick="1" id="1"/>
<map player="2" joystick="1" id="2"/>
</restrictor>
<!-- GRS TOS Restrictor controller serial device -->
<!-- The TOS428 supports up to 4 restrictors per encoder!-->
<restrictor name="TOS428">
<map player="1" joystick="1" id="1"/>
<map player="2" joystick="1" id="2"/>
<map player="3" joystick="1" id="3"/>
<map player="4" joystick="1" id="4"/>
</restrictor>
</restrictors>
Rotator Parameters
-h --help (get help)
To get help use this command line parameter:
rotator -h
or
rotator --help
-c --config (change configurations)
To use an alternative configuration file, use the -c option
rotator -c /path/to/conf/file
or
rotator --config /path/to/conf/file
-v --version (get version number)
rotator -v
or
rotator --version
-r --reset (reset restrictors)
The --reset option will reset all the restrictors on the config to the desired ways.
rotator -r ways (the number of ways)
or
rotator --reset ways (the number of ways)
Usage example
To change player 1 joystick 1 into 4 ways:
rotator 1 1 4
The first number is the player (1, 2, 3, etc.) The second number is the Joystick number (1, 2, etc.) every player can have multiple joysticks with restrictors
The last value is the joystick mode (2-way, 4-way, 8-way, etc.). It uses the same values as MAME, use this table.
Modes Table
| Way | ServoStik | UltraStik360 | GPWiz49 | GPWiz40RotoX | TOS428 | Comments |
|---|---|---|---|---|---|---|
| 1 | 4 | 2 | 2 | - | 4 | Similar to lever or on-off switch |
| 2 | 4 | 2 | 2 | - | 4 | Horizontal 2 ways |
| strange2 | 4 | 2 | 2 | - | 4 | Same as 2 ways |
| vertical2 | 4 | Vertical 2 | Vertical 2 | - | 4 | Vertical 2 ways |
| 3 (half4) | 4 | 4 | 4 | - | 4 | A 4-way joystick with one direction restricted. Like Tetris, only use down, left, right. |
| 4 | 4 | 4 | 4 | - | 4 | Classic 4-way joystick |
| 4x | 4 | 4x | 4x | - | 4 | 4-way joystick turned diagonally (Q-Bert) |
| 5 (half8) | 8 | 8 | 8 | - | 8 | An 8-way joystick with one direction restricted. |
| 8 | 8 | 8 | 8 | - | 8 | Classic 8-way joystick |
| 16 | 8 | Analog | 16 | - | 8 | Too many ways |
| 49 | 8 | Analog | 49 | - | 8 | Similar to analog, used in Sinistar, Arch Rivals, etc. |
| Analog | 8 | Analog | 49 | - | 8 | Analog mode |
| Mouse | 8 | Mouse | 49 | - | 8 | Only used if handle mouse is set on the config for UltraStik360 |
| Rotary8 | - | - | - | Rotary8 | - | Rotary 8 ways (Front Line aim-n-fire) |
| Rotary12 | - | - | - | Rotary12 | - | Rotary 12 ways (Ikari Warriors) |
If you want to change player 1 and 2 just add them together:
rotator 1 1 4 2 1 4
You can add as many as needed as soon as they are available on the config will be used.
To change all joysticks to a specifict way, use -r
processLookup
Process lookup is a daemon that seeks for processes, when they start, it will read the command line to extract the ROM information and calls emitter with that information to load the profiles. Run this command to see the help.
processLookup -h
If you are using MiSTer you need to compile this program for mister, and only add
processLookup runEvery="500"and the program will just work. If you are using retroarch (TODO)
To activate this program, you need to add the <processLookup> section into the configuration file (ledspicer.conf), add some mappings, and run the daemon (you can run it at startup along with ledspicerd).
The only optional parameter is runEvery, in here you set the ms the program wait between checks. if not set the default is 1000 (1 second)
Every map will have a process name (the binary) and two optional parameters position (default to 1) and system (default to arcade)
position is the location where the rom will be find in the command line, lets asume you UI will run mame like this:
mame -parameter1 -parameter2 ronname
1 2 3
in this case position will be 3
system is the system type, for any arcade type this parameter is not needed, but if you run something like snes emulator you need to set it acordely to your snes profile name.
Example:
<processLookup runEvery="500">
<map processName="mame"/>
<map processName="scummvm" system="scummvm"/>
<map processName="vice" position="2" system="c64"/>
</processLookup>
To find the process command line, I suggest checking your UI system rules, in there you will find how the program call the emulators.