Configuration

Configuration file

[TOC]
Lets begin creating an imaginary system:

Let's imagine that we have a two players arcade system with two buttons, start, coin and a joystick each, an exit and an enter button using single color buttons, and the controller is an ultimarc ultimate I/O.

  <C1> <S1>      <enter> <exit>     <C2> <S2>
<P1J>   <P1B1> <P1B2>     <P2J>   <P2B1> <P2B2>

The File

The configuration file needs to be named ledspicer.conf (even when is a XML file the .conf extension make it looks more badass) and needs to be located in the system configurations directory (like /etc, this is set during compilation) anyway if you have the file in a different place, you can check the daemon help to load an alternative file.

Root

The configuration is case-sensitive and must have this mandatory nodes and parameters:
the root node is <LEDSpicer><LEDSpicer/> with the following mandatory parameters: version, type, fps, port and colors.

Parameters

version leave it always to 1.0
type is Configuration
fps is the number of times the panel will be drawn per second, I tested several numbers here for different boards and the most stable was 15, if you see that the board freezes or restart, reduce this number until you get it stable.
port The port where LEDSpicer will listen for commands (default 16161).
logLevel (optional, defaults to Info) The minimum logging level: Error, Warning, Notice, Info, Debug.
colors needs to match an existing color configuration file, I provide two samples: basicColors and webColors (from Wikipedia) but you can create your own colors file as well.
userId The user ID to run as.
groupId The group ID to run as.

Code

<LEDSpicer
    version="1.0"
    type="Configuration"
    fps="14"
    port="16161"
    colors="basicColors"
    userId="1000"
    groupId="1000"
>

Inside the root node, you have <devices></devices> and <layout></layout>

Devices

This section tells LedSpicer what devices are plugged in

Parameters

name: The device name, for example UltimarcUltimate or LedWiz32. The names for each device are listed on the Device's page
boardId: In most cases, this will be "1". This ID is set by the manufacturer and hard-coded into the board itself. The boardId is used to differentiate between multiples of the same device when used together.

Device Specific Options

Some devices need special options:
Devices that only can turn ON or OFF their LEDs, can set the value of changePoint to a value between 0 and 255 (default 64), this value will be used to turn on/off the LED as needed, this is because the program handle intensities from 0 to 255.

Code

<device
    name="UltimarcUltimate"
    boardId="1"
/>

Elements

This section tells LedSpicer which LED pins are connected to your controls. Each element is a button, joystick or light on your control panel.
Every element requires a unique name and either the use of the "led" parameter or the RGB parameters
The following standard naming convention is strongly recommended for naming elements:
player number an underline then element type and element number:
P1_CREDIT
P2_BUTTON1
P1_MOUSE1
P3_JOYSTICK1
P1_TRACKBALL1
etc

You can have several joysticks in one player.
Elements that are not attached to a player are named:
POWER, FLOOR, MARQUEE, LIGHT1, LIGHT2, PB_LEFT1, PB_LEFT2

If you intend to use the automatic craftProfile feature you must use the naming convention. If you intend to manually define all of your own profiles,
then the element names can be anything you like.

Notes

• Single LED elements use the "led" parameter
• RGB elements use "red" "green" "blue" parameters
• You can also set Motors and Solenoids using 'solenoid', keep in mind that this special case that will send a PULSE to the hardware, you can set the milliseconds the pulse will ON, then it will go OFF

Parameters

name: The element name.
led: Single color LEDs use this parameter. This is the pin number on the LED driver board that is associated with this element
red: For RGB LEDs this is the RED pin number on the LED driver board
green: For RGB LEDs this is the GREEN pin number on the LED driver board
blue: For RGB LEDs this is the BLUE pin number on the LED driver board
solenoid: For kicks/solenoids/motors/etc. This is the pin number on the controller associated with this element.
timeOn: (optional) Only used for solenoids, sets the time the pin will send a signal, the idea of this setting is to be able to handle heavier solenoids that needs extra time to generate the momentum to "kick" it defaults to 50ms.
defaultColor: (optional) if you wish to provide a default color to avoid having to set this everywhere you turn this element on, use this default color, the default color can be overridden easily be other profiles.

Code Examples

Our imaginary board will look like this:

<element
    name="P1_CREDIT"
    led="3"
/>
<element
    name="P1_START"
    led="4"
    defaultColor="Red"
/>
<element
    name="P1_JOYSTICK"
    red="5"
    green="6"
    blue="7"
/>
<element
    name="P1_BUTTON1"
    red="11"
    green="12"
    blue="13"
/>
<element
    name="P1_BUTTON2"
    red="14"
    green="15"
    blue="16"
/>
<element
    name="P2_CREDIT"
    led="1"
/>
<element
    name="P2_START"
    led="2"
    defaultColor="Blue"
/>
<element
    name="P2_JOYSTICK"
    red="8"
    green="9"
    blue="10"
/>
<element
    name="P2_BUTTON1"
    red="17"
    green="18"
    blue="19"
/>
<element
    name="P2_BUTTON2"
    red="20"
    green="21"
    blue="22"
/>
<element
    name="KNOCKER"
    solenoid="23"
    onTime="75"
/>

Layout

The layout section holds the groups, also specify the default profile, the profile name needs to match a file inside the profiles directory.
You can create as many groups as you need.

Parameters

defaultProfile: The profile file name to be use as the default profile.

Code

<layout defaultProfile="some_profile_name">

Groups

Every group will have a unique name to identify it.

Parameters

name: Each group name must be unique. Create an easy to remember group name, ex: player 1, coin slots, etc.
defaultColor: (optional) if you wish to provide a default color to avoid having to set this everywhere you turn this group on, use this default color, the default color can be overridden easily be other profiles.

Code

<group name="Some cool group name">

Inside the group you will enumerate the elements on the board, the position is very important for animations to work as expected, so you have to place each element in the correct order you want them to be handled by animations.
There is a special group called "All" that is generated automatically using all the elements found in the devices area. To override the automatically generated All group, you may define it yourself in the configuration file.

We can create our first group for our imaginary board as a circle of elements on the panel:

<group name="whole board as a circle">
    <element name="P1_START"/>
    <element name="P1_CREDIT"/>
    <element name="P1_JOYSTICK"/>
    <element name="P1_BUTTON1"/>
    <element name="P1_BUTTON2"/>
    <element name="P2_JOYSTICK"/>
    <element name="P2_BUTTON1"/>
    <element name="P2_BUTTON2"/>
    <element name="P2_CREDIT"/>
    <element name="P2_START"/>
</group>

Then, we can create two more groups with every player elements:

<group name="Player1">
    <element name="P1_START"/>
    <element name="P1_CREDIT"/>
    <element name="P1_JOYSTICK"/>
    <element name="P1_BUTTON1"/>
    <element name="P1_BUTTON2"/>
</group>    
<group name="Player2"  defaultColor="Green">
    <element name="P2_START"/>
    <element name="P2_CREDIT"/>
    <element name="P2_JOYSTICK"/>
    <element name="P2_BUTTON1"/>
    <element name="P2_BUTTON2"/>
</group>

Example

And that is all for the configuration file, all together will looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<LEDSpicer
    version="1.0"
    type="Configuration"
    fps="12"
    colors="basicColors"
>
    <devices>
        <device
            name="UltimarcUltimate"
            boardId="1"
        >
            <element
                name="P1_CREDIT"
                led="3"
            />
            <element
                name="P1_START"
                led="4"
            />
            <element
                name="P1_JOYSTICK"
                red="5"
                green="6"
                blue="7"
            />
            <element
                name="P1_BUTTON1"
                red="11"
                green="12"
                blue="13"
            />
            <element
                name="P1_BUTTON2"
                red="14"
                green="15"
                blue="16"
            />
            <element
                name="P2_CREDIT"
                led="1"
            />
            <element
                name="P2_START"
                led="2"
            />
            <element
                name="P2_JOYSTICK"
                red="8"
                green="9"
                blue="10"
            />
            <element
                name="P2_BUTTON1"
                red="17"
                green="18"
                blue="19"
            />
            <element
                name="P2_BUTTON2"
                red="20"
                green="21"
                blue="22"
            />
        </device>
    </devices>
    <layout defaultProfile="some_profile_name">
        <group name="whole board as a circle">
            <element name="P1_START"/>
            <element name="P1_CREDIT"/>
            <element name="P1_JOYSTICK"/>
            <element name="P1_BUTTON1"/>
            <element name="P1_BUTTON2"/>
            <element name="P2_JOYSTICK"/>
            <element name="P2_BUTTON1"/>
            <element name="P2_BUTTON2"/>
            <element name="P2_CREDIT"/>
            <element name="P2_START"/>
        </group>
        <group name="Player1">
            <element name="P1_START"/>
            <element name="P1_CREDIT"/>
            <element name="P1_JOYSTICK"/>
            <element name="P1_BUTTON1"/>
            <element name="P1_BUTTON2"/>
        </group>    
        <group name="Player2">
            <element name="P2_START"/>
            <element name="P2_CREDIT"/>
            <element name="P2_JOYSTICK"/>
            <element name="P2_BUTTON1"/>
            <element name="P2_BUTTON2"/>
        </group>
    </layout>
</LEDSpicer>

[Chris Newton]

Your Example configuration shown above uses "IPAC_ULTIMATE" which caused errors. It should be "UltimarcUltimate".

On the raspberry pi, Port, UserId, GroupId, are required, but they are not shown in the example configuration shown above.