Menu ▾ ▴

Programs

MeduZaPaT Chris Newton

Programs and Basic Usage

[TOC]
This section will describe the normal program usage, for development and other uses go to their respective sections.

LEDSpicer daemon

The main program, that is the one that will speak directly with the USB interface, in order to control the LEDs on the board, is ledspicerd, this program is capable of handling different boards (1) and settings.
It's intended to be started when the whole system boots up as a daemon. If not set to run as a daemon, it should be run in the foreground (documented below.)

Important
The LEDSPicer daemon can be run as a normal user or root, if running under a normal user, be sure that the USB is readable and writable by that user, configuration files only need read access. I added a USB rules file to be used in case of running the program as non-root users.

The first thing the program does is check the command line parameters and load the configuration file.
The default location for the configuration file can be changed, (check the help for more information)

Options

-f --foreground (run LEDSpicer in foreground)

If not running as a daemon, ledspicerd can be run in the foreground. This is useful for testing, but otherwise should be run when the system launches as a daemon. When the daemon is executed, it will run detached and independently, and will log anything important to the system's log (syslog).

ledspicerd -f
ledspicerd --foreground

-h --help (get help)

To see the help list, use this command line parameter:

ledspicerd -h
ledspicerd --help

-c --config (change configurations)

To use an alternative configuration file, use the -c option

ledspicerd -c /path/to/conf/file
ledspicerd --config /path/to/conf/file

Changing to an alternative configuration file is only temporary, and should be paired with a command.

-d --dump (dump configurations)

The program can display the current configuration by doing a dump:

ledspicerd -d
ledspicerd --dump

This will display the program's internal settings after read the configuration files. This dump is really important when creating and debugging configurations.
This dump will also read and display the colors file.

-p --profile (dump profile)

This will display the current profile by doing a dump

ledspicerd -p profile_name
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
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
ledspicerd --elements

1 The number of boards depends on development, check the main section for more information on supported devices

Emitter

This program sends commands to the running daemon.

Options

-h --help (get help)

Help lists all the available Emitter options. To see the help list, use this command line parameter:

emitter -h
emitter --help

-c --config (change configurations)

To use an alternative configuration file, use the -c option

emitter -c /path/to/conf/file
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
ex: emitter LoadProfileByEmulator galaga arcade

When this command is run, in the following order LEDSpicer will attempt to:

  1. Load a Rom Profile
  2. If the emulator is "arcade", load a Controller Profile
  3. if the emulator is "arcade", load a Player Profile
  4. Load an Emulator Default Profile
  5. Load the default profile
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

Controller Profiles (for MAME ROMs only)

When the emulator is MAME, LEDSpicer will attempt to load a profile based on the controls listed in MAME, or the controls.ini file (if found in your LEDSpicer directory.) Controller profiles should be named using the following convention: Tx_By

  • T is the controller name. Controller names can be any one of the following
    • JOYSTICK
    • PADDLE
    • PEDAL
    • DIAL
    • MOUSE
    • LIGHTGUN
    • TRACKBALL
  • x is player number
  • B is just the letter B, for "button"
  • 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)

When the emulator is MAME, LEDSpicer will attempt to load a profile based on the number of players listed for the game in MAME, or the controls.ini file (if found in your LEDSpicer directory.) Player profiles should be named using the following convention: Px_By

  • P is just the letter P, for "player"
  • x is the player number
  • B is just the letter B, for "button"
  • y is the number of buttons

example: to create a profile for games with only one player that have 2 buttons: P1_B2.xml
example: to create a profile for games with two players, that have 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

Emultator default profile should be named after the emulator, and placed in the profiles directory.
example: ledspicer/profiles/arcade.xml

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:

  • Ultimarc UltraStik 360
  • Ultimarc Servostik
  • GroovyGameGear GP-Wiz40 with rotary support
  • GroovyGameGear GP-Wiz49 with 49-way support

Features:

  • Sets joystick encoder modes
  • Loads joystick profiles into UltraStik 360
  • Can handle an unlimted number of devices per call

Usage:

  • Add a restrictors section to your ledspicerd.conf configuration file (/etc/ledspicerd.conf)
<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
boardId: When only using one of a specific joystick/encoder, use "1". If you ordered more than one to be used together on the same control panel and had to specify a boardId (usually between 1-4) when ordering, use that number here.
joystick: When using 1 joystick for a specific player, just use "1". When using more than 1 joystick for a player, set a unique number for each of that player's joysticks. This number is not unique across ALL players, but must be unique for every joystick that a specific player will use.

Additional parameters are available and vary from item to item. Please review the additional parameters and requirements documented in the following examples.

Example Configurations

<restrictors>
    <!-- Ultrastik -->
    <!-- Player 1 with UltraStik -->
    <restrictor name="UltraStik360" boardId="1" player="1" joystick="1" />
    <!-- Player 2 with UltraStik. Has physical restrictor installed & has mouse mode enabled-->
    <restrictor name="UltraStik360" boardId="2" player="2" joystick="1" hasRestrictor="true"  handleMouse="true" />

    <!-- ServoStik -->
    <!-- Player 1 with ServoStik -->
    <restrictor name="ServoStik" boardId="1" player="1" joystick="1" />
        <!-- Player 2 with ServoStik -->
      <restrictor name="ServoStik" boardId="2" player="2" joystick="1" />

    <!-- GPWiz49 -->
    <!-- Player 1 with GPWiz49 & Happs 49-Way Joystick -->
    <restrictor name="GPWiz49" boardId="1" player="1" joystick="1" />
    <!-- Player 2 with GPWiz49 & Williams 49-Way Joystick -->
    <restrictor name="GPWiz49" boardId="1" player="2" joystick="1"  williams="true" />

       <!-- GPWiz40 With Roto-X Rotary Control -->
     <!-- The GPWiz40RotoX supports up to 2 joysticks per encoder. This requires additional map nodes for each joystick --> 
    <restrictor name="GPWiz40RotoX" boardId="1">
        <map player="1" joystick="1" id="1"/>
        <map player="2" joystick="1" id="2"/>
    </restrictor>
</restrictors>

Rotator Parameters

-h --help (get help)

To get help use this command line parameter:

rotator -h
rotator --help

-c --config (change configurations)

To use an alternative configuration file, use the -c option

rotator -c /path/to/conf/file
rotator --config /path/to/conf/file

-v --version (get version number)

rotator -v
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)
rotator --reset ways (the number of ways)

Config parameters:

ultraStik360:
hasRestrictor true|false if you have the restrictor set this to true, other case is optional.
handleMouse true|false if a game uses a mouse and this is true, the joystick will be set as a mouse.

servoStik:
none

GPWiz49:
williams true|false handle the Williams Sinistar hardware.

GPWiz40RotoX:
This controller can handle two players,
speedOn a number from 1 to 255 for the length of time the button is depressed and released before sending a signal again.
speedOff a number from 1 to 255 for the length of time the button is depressed and released before sending a signal again.

Examples and Modes

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:

Way servoStik ultraStik360 GPWiz49 GPWiz40RotoX Comments
1 4 2 2 - similar to lever or on-off switch
2 4 2 2 - horizontal 2 ways
strange2 4 2 2 - same as 2 ways
vertical2 4 vertical 2 vertical 2 - vertical 2 ways
3 (half4) 4 4 4 - A 4-way joystick with one direction restricted. Like tetris, only use down, left, right.
4 4 4 4 - Classic 4-way joystick
4x 4 4x 4x - 4-way joystick turned diagonally (Q-Bert)
5 (half8) 8 8 8 - An 8-way joystick with one direction restricted.
8 8 8 8 - Classic 8-way joystick
16 8 analog 16 - too many ways
49 8 analog 49 - Similar to analog, used in Sinistar, Arch Rivals, etc
analog 8 analog 49 - analog mode
mouse 8 mouse 49 - 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.

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)</processlookup>

To activate this program you need to add into the config (ledspicer.conf), the section <processlookup> and add some mappings and run the daemon (you can run it at startpup along with ledspicerd).</processlookup>

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.

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.