LIRC - Linux Infrared Remote Control
Keywords: linux remote control, multimedia

# The lircd.conf file format

A description of the format is available in the lircd.conf(5) manpage. In fact you probably don't need to know anything about it except that it's maybe the most important part of the package.

# Configuring lircmd (the LIRC mouse daemon)

lircmd can be used to emulate a mouse with your remote control. Depending on the config file described in the next section it converts IR signals into mouse events. It currently supports three mouse protocols (MouseSystems, IntelliMouse and IMPS/2). For compatibility reasons the default protocol is the MouseSystems protocol but the preferred is the IntelliMouse protocol. The advantage of this protocol is its wheel-mouse support. That way you can for example configure Netscape to scroll if you press certain buttons.

IMPS/2 used to be the preferred protocol since it also has wheel-mouse support and IntelliMouse was not available. However PS/2 protocol specifies that the mouse must accept and reply to specific commands, and that can not be done through the pipe lircmd uses. For this reason IntelliMouse support was written and is currently the preferred protocol.

lircmd can basically be used with two applications: X11 and gpm Using gpm makes no sense with a modern X installation since this supports multiple mouses natively.

### X11

Put this section in your Xorg.conf file to use the lircmd emulated mouse in addition to your normal one.

                 Section "InputDevice"
                         Identifier  "LIRC-Mouse"
                         Driver      "mouse"
                         Option      "Protocol" "IntelliMouse"
                         Option      "SendCoreEvents"
                         Option      "Buttons" "5"
                         Option      "ZAxisMapping" "4 5"
                 EndSection

### uinput and effective user

If your distribution does not have uinput enabled by default (i. e., there is a /dev/uinput device) add to the file /etc/modules the entry:

                 uinput

To make this device writable for regular users create a new file /etc/udev/rules.d/55-uinput with one line

                 KERNEL=="uinput", MODE="0666"

However, this has security implications. The preferred setup is to use the example rule in the contrib directory which makes /dev/uinput accessible for the lirc user, and then run lircmd as this user

Another alternative is to run lircmd as root. In this case this no udev rule is required, but it raises other security concerns.

Finally, run lircmd with the --uinput option (which can be set in lirc_options.conf).

### systemd

LIRC ships with systemd support files. To start lircmd, use

                 # systemd start lircmd.service

To make it start at boot time use:

                 # systemd enable lircmd.service

# The lircmd.conf file format

The config file for lircmd is quite simple. Just look at the example in the contrib directory. Some drivers even already bring their config file for lircmd with them so lircmd is ready to run.

PROTOCOL <protocol>

  You can choose between MouseSystems, IntelliMouse and IMPS/2 protocol. The default is MouseSystems protocol.

ACCELERATOR <start> <max> <multiplier>

  Change the values here if your mouse pointer is moving too fast/slow. Usually the mouse pointer moves 1 pixel every time it receives a signal. The values here specify how much mouse movement accelerates if you hold down the according button on your remote control for a longer timer. The start value is the threshold that starts acceleration. Then the amount of pixels is calculated with the following formula: x=repeat*multiplier, where repeat is the number of repeated signals. max specifies the maximum number of pixels the pointer can move due to a single command.

ACTIVATE <remote> <button>
TOGGLE_ACTIVATE <remote> <button>

  I recommend that you use a special button to activate the mouse daemon with this command. You will see whenever the daemon is activated/deactivated directly on the screen. If you omit this command the daemon will always be active.

  The difference between ACTIVATE and TOGGLE_ACTIVATE is how you leave the mouse mode. With TOGGLE_ACTIVATE you have to press the button that you use to enter the mode to leave it. With ACTIVATE you will leave mouse mode as soon as you press a button that is not used for any function in the config file.

MOVE_ [ N [ E | W ] | E | S [ E | W ] | W ] <remote> <button>

  The obvious functionality. You can even get better granularity by combing different commands (copied from the config file for AnimaX remotes):

      MOVE_N    ANIMAX_MOUSE_PAD   MOUSE_NNE
      MOVE_NE   ANIMAX_MOUSE_PAD   MOUSE_NNE

  This also demonstrates that all commands are executed beginning at the top.

MOVE_[IN|OUT] <remote> <button>

  This will only work with IntelliMouse and IMPS/2 protocols and indicates movement of the wheel.

BUTTONx_CLICK, BUTTONx_DOWN, BUTTONx_UP, BUTTONx_TOGGLE <remote> <button>

  This simulates according events for the left (x=1), middle (x=2) or right (x=3) mouse button.

IGNORE <remote> <button>

  Pressing ignored buttons won't cause the mouse daemon to deactivate. This is useful, for example, if your remote sends separate press or release codes that you have mapped in your lircd.conf. This only makes sense if you use ACTIVATE instead of TOGGLE_ACTIVATE.

'*' is allowed as wild card for button and remote. Please note that every line that fits to the received signal will be executed. Parsing starts at the top of the file.

# The lircrc file format

The lircrc file is used to map the key symbols defined in lircd.conf to application-specific strings. Thus, this file cannot be configured until lircd has been configured to provide proper key symbols as displayed by irw.

The lircrc file should be placed in the home directory as ~/.config/lircrc. Optionally you can create a system-wide configuration file located in /etc/lirc/lircrc which will be used when no lircrcfile can be found in the user's home directory. The idea is to have configuration information of all clients in one place. That lets you keep a better overview of clients and simplifies the use of modes explained later.

The preferred setup is to have a main ~/.lircrc which includes a number of other files, typically living in ~/.config/lircrc/*. The contrib directory contains a number of example files, most of which created using lirc-config-tool for an ordinary MCE remote

First I will explain the syntax of the lircrcfile itself. The file consists of one or more of the following constructions:

        begin
            prog    = ...
            remote  = ...
            button  = ...
            [button = ...] (optional, for key sequences)
            repeat  = ...
            delay   = ...
            ignore_first_events = ...
            config  = ...
            [config = ...] (optional, for toggle button behaviour)
            mode    = ...
            flags   = ...
        end

Bringing it to the point the above says which program (prog) should do what (config, mode, flags) if you press a certain button (remote, button) a specified time (repeat, delay). By default for each remote signal received the lircrc config file is read from top to bottom and each matching configuration is executed in order of appearance.

prog
  gives the name of the program that should receive the configstring given in config.
remote, button
  specify a key of a remote control that launches an action. Key sequences can be specified by giving more then one remote/button string (not on the same line, but using separate remote/button tokens on separate lines). The character '*' can be used as a wild card for remote or button. The default for remote is '*'. The remote name must always be given before its according button. When using key sequences a given remote is valid for all following buttons until you specify another remote.
repeat
  tells the program what shall happen if a key is repeated. A value of zero tells the program to ignore repeated keys. Any other positive value 'n' tells the program to pass the config string every 'n'-th time to the according application, when a key is repeated. The default for repeat is zero.
delay
  tells the program to ignore the specified number of key repeats before using the "repeat" configuration directive above. This is used to prevent double triggers of events when using a fast repeat rate. A value of zero, which also is the default, will disable the delay function. If "repeat" value is zero but "delay" is set, there will be a single event generated after the delay period expires (with another one before delay period starts).
ignore_first_events
  ignores the specified amount of first events. Same as "delay" but without an event before delay period starts. This allows to define the reaction on the long key presses. Should not be set together with "delay".
config
  is the string that will be passed to the according application whenever the specified key sequence is received by lircd. If you give more than one config string, the config strings will be passed to the applications by turns. With this feature you can for example implement toggle buttons.
  You can pass non-printable characters to applications with all standard C escape sequences (most common are: \n = line-feed, \r = carriage return, \t = tab, \e = escape, \<n> = ASCII code in octal representation, \x<n> = ASCII code in hexadecimal representation, \\ = backslash). Additionally you can supply Ctrl-X by specifying \X where X is an upper character or @. For example \C is Ctrl-C.
mode
  tells the program to enter a special mode. You can group several configurations by putting them into the following, where mode stands for the mode where these configurations should be active:

          begin mode
              ...
          end mode

  All configurations embraced by this mode construct will stay inactive until the program enters the given mode by using the mode token. Please note that configurations outside a mode will always stay active even though you enter a specific mode. To prevent the execution of such "global" configurations you can place these at the end of the config file below all mode constructs and use the quit flag described below to stop execution of further configurations when a match happens inside a mode block. If mode is equal to the name of a client application this application will always start in this mode. Consider this situation: you want to start xawtv with irexec and enter the tv mode. Then irexec would enter the tv mode but xawtv would begin without any mode enabled. By renaming the mode from tv to xawtv you can solve this problem.
  Another way to specify a startup mode is by using the startup_mode flag as described below.
  Caveat: In order to avoid many identical entries all actions that modify the mode a program currently is in are independent of the prog token.

The following are valid flags:

once
  This is only allowed in conjunction with the mode directive. The config string is passed to the application only the first time the mode is entered or you have explicitly left this mode. This is useful for starting an application whenever you enter a special mode.
quit
  Usually all configurations are examined whether they have to be executed. You can stop this immediately with this flag. Configurations further below will not be executed if the current button press matches the current configuration. A match also happens if the current configuration defines a button sequence and only part of the sequence already was entered.
mode
  This is only allowed within a mode block. It tells the program to leave this mode.
startup_mode
  Tells the program to start in the mode given in the mode keyword. The following example tells the program to start in the browser mode

      begin
              flags = startup_mode
              mode = browser
      end

toggle_reset
  This will only have an effect if you have specified several config lines to implement a toggle button. Usually the toggle state is always saved for the button regardless of other button presses. But with this flag the toggle state will be reset to the first config entry as soon as a different button not matching the specification in the current block is pressed.

If you press a button on your remote the lircrc is searched from top to bottom for matching configurations. Be aware that the search is not stopped by a match unless you have specified the quit flag in the matching configuration. You should also be aware that if a configuration changes the current mode, the change takes effect immediately, which means that the further search for matching configurations beginning at the next configuration further down will take place with the new mode setting.

It is possible to split the lirc configuration into several files by using the include command. It tells the parser to read the specified file before resuming the current one:

    include ~/.config/lirc/xawtv

If the specified filename begins with "~/", "~" will be substituted with the content of the HOME environment variable. The filename also can be put inside <> and "" characters which in contrast to the C preprocessor do not have special meanings.

A simple example for a lircrc file (supposing you using an AnimaX remote and use the sample files for this remote from the remotes database. If you have another remote change remote= and button= according to your remote [t definitions are made in the lircd.conf file]):

        begin
            remote = ANIMAX
            button = MENU_DOWN
            prog   = irexec
            repeat = 0
            config = echo "Hello world!"
        end

If you have saved this as ~/.config/lircrc , start irexec. Press the button which is selected in the button= line and you will see a 'Hello world!' on your screen. As you can see irexec is a simple program launcher. Of course you can do a lot more than just start programs. Be aware that irexec will wait for the started program to finish, before it will resume it function. If this is not what you want, you should add a "&" at the end of the config line to start the desired program in background.

Differences in the order of configurations in lircrc can lead to completely different results, as this example shows:

          begin order
          begin
               button = OK
               prog = irexec
               config = echo "This is printed last"
          end
          end order

          begin
               button = OK
               prog = irexec
               config = echo "This is printed first"
               mode = order
               flags = quit
          end

Using this order on first key stroke of OK

          "This is printed first"

will appear - the command is executed and the mode 'order' is entered. The second stroke (and every further one) will lead to

          "This is printed last"
          "This is printed first"

Both configs are executed, even though the second is outside the mode; the quit flag has no effect - no other config is following it in the lircrc file.

Changing the order within the lircrc to

          begin
               button = OK
               prog = irexec
               config = echo "This is printed first"
               mode = order
               flags = quit
          end

          begin order
          begin
               button = OK
               prog = irexec
               config = echo "This is printed last"
          end
          end order

will lead to

          "This is printed first"

on every stroke. The second config is never executed: even though the mode is changed it can not take effect (because of the quit flag). To achieve unrestricted usage of keys within modes place all mode-configurations before all other configurations; and use quit flags within the mode if you don't want other configurations to be executed.

If you start a LIRC client program, it reads your ~/.config/lircrc and reacts only on prog= entries which point to itself. All programs should give you the possibility to use an alternative config file. If you have included more than one program in your lircrc, then start all these programs, they react only to their according entries in lircrc. This also leads to a disadvantage of the mode concept. If you don't start all client programs at a time the mode they currently are in may differ between applications. Also key sequences might not be recognized equally because all programs then don't have the same starting point. In order to solve this problem there is the lircrcd program since version 0.8.0. lircrcd's purpose is to synchronise all clients and maintain a common mode for all applications. In order to use the lircrcd feature you have to explicitly enable it by adding the following line at the beginning of the file:

    lircrc_class default

This directive can only be used in a top-level file, not in an included one. The string `default` could actually be any identifier; clients using a lircrc with the same string will synchronized.

In versions before 0.9.2 the same effect was acheived with a "shebang", a first line in the file `#! lircrcd` From 0.9.2+, the support for this deprecated and it will be removed in an upcoming release.

# Sending infrared signals

The LIRC package contains the irsend tool for sending infrared signals to e.g. your TV or CD player. For reliable transmission a good config file is even more important than for receiving. A discussion of all the infrared protocols is way beyond the scope of this manual but when creating a config file at least read the hints at the end of this manual. You can find exact timing specifications for most common protocols in files retrieved from the remotes database located using irdb-get find generic

LIRC also provides interfaces to develop applications which sends data. Sine 0.9.2, the primary interface is the client API.