[% pagetitle = 'Button Mapping' %] [% techinfo = '1' %] [% lefttoright = '1' %] [% PROCESS helpheader.html %]

#### Overview

The Player IR interface to the Squeezebox associates human actions (pressing a button on the remote) with functions on the server (jumping to the next song). There are a number of translations, or mappings between the human action and the server function.

The remote translates the particular button pressed into a series of pulses of infrared light. The player recieves these pulses, and translates them into a four byte code, which is sent to the server. The server looks up this code in a table and tranlates it into a button name. The button name is then looked up in another table to produce the function which should be called.

The button to IR pulse mapping depends on the remote used, and is not generally customizable, although programmable remotes can be used. The IR pulse to code mapping is controlled in the firmware of the player, and cannot be modified without updating that firmware. The code to button name mapping is controlled through .ir files, typically one for each type of remote used to control the player. The final button name to function mapping is controlled through .map files, consisting of a default mapping file, and any custom maps which may have been created.

The mapping files, both .ir and .map, are stored in the IR subfolder of the folder where the Squeezebox software was installed. Included with the software are two .ir files: jvc_dvd.ir and Slim_Devices_Remote.ir which handle the codesets sent by the JVC DVD player (which is the codeset most commonly used by the player prior to the production of the product specific remotes) and the product specific remote respectively. One .map file(Default.map), representing the default mapping is included.

#### Mappings

##### Code to Button Name

The code to button name mapping is contained within .ir files located in the IR subfolder of the Squeezebox Server folder. The files consist of lines with the button name followed by an equals sign (=) followed by the IR code in hex (no 0x necessary). Everything after a # is considered a comment. Leading and trailing whitespace is ignored, as is whitespace around the = and preceding the #. The = and # characters are not allowed within the button name, but embedded whitespace (except newlines) is allowed. Due to the implementation of button pressing styles (explained below), the period (.) is not recommended for use within a button name.

Multiple codes can map to the same button name. On the other hand, if a particular code is repeated within the same file, only the last mapping will actually be used.

The server will load all .ir files within the IR subfolder. Individual mappings can be disabled for a particular player by using the disabledirsets client array preference. This is configurable from the web interface by following the "[% "REMOTE_SETTINGS" | string %]" link from the "[% "PLAYER_SETTINGS" | string %]" page. This can be useful if you have JVC equipment co-located with the player and want to prevent it from reacting to remote signals intended for the other equipment.

Examples:

    play = 0000f732
    play = 0000f7d6 #alternate code for play, with a comment
        pause     =      0000f7b2   # extra spacing ignored
    play=this = 0000f123 #BAD! = not allowed in button names
    B# = 0000f7c6        #BAD! # also not allowed in button names

##### Button Name to Function

The button name to function mapping is contained within .map files located in the IR subfolder of the Squeezebox Server folder. The files consist of lines with the button name followed by an equals sign (=) followed by the function. Everything after a # is considered a comment. Leading and trailing whitespace is ignored, as is whitespace around the = and preceding the #. The = and # characters are not allowed within either the button name or the function, but embedded whitespace (except newlines) is allowed. Due to the implementation of button pressing styles (explained below), the period (.) is not recommended for use within a button name, but would be fine for inclusion in a function. Similarly, use of the underscore (_) is not recommended in naming functions, but is fine for button names.

The map file is divided up into a number of sections corresponding to the various modes of operation, plus a [common] section whose mappings apply to all modes. Sections start with the name of the section enclosed in square brackets ([]). Mode classes, prefixed by all caps (eg, INPUT.list) will first match to a section headed by [INPUT.list] then, if no matches found will take functions from an [input] section.

Multiple button names can map to the same function. On the other hand, if a particular button name (including pressing style) is repeated within the same section, only the last mapping in that section will actually be used.

Button pressing styles are indicated by appending a period (.) to the end of the button name, followed by the desired style.

Functions can be passed a single parameter by appending an underscore (_) to the end of the function name, followed by the parameter

Examples:

    [common]
    arrow_down = down
    arrow_down.repeat = down #alternate pressing style for same function
        rew.single     =     jump_rew     #this function uses a parameter, spacing unimportant
    fwd.single = jump_fwd #same function, different parameter
    [off]
    arrow_down = dead #in a different section now, so ok to redefine button names

#### Timing

When a code is first received by the server, the plain button mapping is triggered. Also, a timer is set to go off in IRSINGLETIME seconds (currently 0.256).

If the button on the remote is held down, the server will receive additional codes identical to the initial one. If the repeated codes are each received within IRMINTIME seconds (currently 0.128) of each other, the button.repeat mapping is triggered for each repeated code. If one of those repeated codes happens between IRHOLDTIME (currently 0.512) and IRHOLDTIME + IRMINTIME seconds, the button.hold mapping is triggered.

When either IRSINGLETIME seconds pass or a code comes in more than IRMINTIME seconds from the previous code, the pending timer is fired. If the code is different from the code which initiated the timer, the mapping for button.single (for the first code) is triggered. If the new code is the same as the old one, the mapping for button.double is triggered.

If the timer fired as a result of the time elapsing, then it must be determined if the button is still being held. This is the case if the last code received was received within the last IRMINTIME seconds. If the button is no longer being held, the mapping for button.single is triggered. Otherwise the timer is rescheduled for another IRSINGLETIME seconds, or for however long it takes to make the total time be IRHOLDTIME seconds. The same checks apply for the next time the timer is fired.

After IRHOLDTIME seconds have passed, the timer will no longer trigger the button.single or button.double mappings. From that point forward, the mapping triggered will be button.hold_release when it is finally determinied that the button is no longer being held.

Multiple button pressing styles can be included in the mapping with the use of the '*' wildcard. Thus button.* will match all styles. Specific sytles will override the for that style.

More to come...

[% PROCESS helpfooter.html %]