Configuring lircd (the LIRC daemon)

1. Check if there is already a config file in /etc/lircd.conf. If not
2. check if there is a config file available for your remote control at the LIRC homepage and copy it to /etc/lircd.conf. If not
3. start irrecord (finish all applications that access /dev/lirc first) and follow the instructions given to you by this program. Copy the resulting file to /etc/lircd.conf.

If you want to use more than one remote control you can simply concatenate the config files: cat config1 config2 >config

Note: If you already have a config file for the libirman package you can convert it using the irman2lirc script that you can find in the contrib directory.

The lircd.conf file format

A description of the file format is available on the WinLIRC pages. In fact you don't need to know anything about it except that it's maybe the most important part of the package.

Using multiple different devices simultaneously

There are some situations when you might want to use multiple devices with LIRC simultaneously. E.g. you might have a TV card receiver and want to control your set-top box with a home-brew serial port transmitter at the same time. Or you might have a serial port receiver connected to your PC and a different network connected receiver (UDP, different LIRC/WinLIRC instance) in a different room.

The configuration depends much on the type of devices you want to use. If you are using devices that require a kernel module, then you should first compile and install LIRC individually for each device, basically just to get all required kernel modules installed. The further steps depend on which user-space driver is used in lircd for your devices. Most devices (actually all devices that use a kernel module) use the default driver. You can check which user-space is used for your device by running lircd --driver=?. Remember that this might change each time you compile lircd for a different device. If you want to use devices that use different user-space drivers then you have to compile LIRC once again using ./configure --with-driver=any. This will compile almost any user-space driver into lircd that is available (but does not compile any kernel modules, that's why you had to build them individually before). After that you should check if the drivers you want are listed now with lircd --driver=?. You should get something like this:

> lircd --driver=?
Driver `?' not supported.
Supported drivers:
        audio
        bte
        creative
        creative_infracd
        default
        dev/input
        dsp
        ea65
        irman
        livedrive_midi
        livedrive_seq
        logitech
        mp3anywhere
        null
        pcmak
        pinsys
        pixelview
        silitek
        tira
        udp
        uirt2
        uirt2_raw

If you want to use more than one device that uses a kernel module you should now have a look at the character device setup in /dev/. Each LIRC kernel module provides a device with major number 61 and a minor number beginning at 0 which is counted up every time a new driver is loaded (note: both the major number and the minor number concept are subject to change in future LIRC releases). If you want to use two devices then the LIRC related files in /dev/ should look something like this (this might be done automatically if you are using devfs or sysfs):

> ls -l /dev/lirc*
crw-r--r--    1 root     root      61,   0 Apr 25  2001 /dev/lirc
crw-r--r--    1 root     root      61,   1 Nov  6 19:24 /dev/lirc1
srw-rw-rw-    1 root     root            0 Dez 19 09:44 /dev/lircd
prw-r--r--    1 root     root            0 Okt 10 21:16 /dev/lircm

You can create new entries by running:

> mknod /dev/lirc2 c 61 2

For each device you want to use you have to start an individual lircd instance. If you want to receive events from all receivers at one socket interface you have to connect the different lircd interfaces with an additional TCP/IP socket. This could look e.g. like this:

> lircd --driver=default --device=/dev/lirc1 --output=/dev/lircd1 \
    --pidfile=/var/run/lircd1.pid --listen
> lircd --driver=default --device=/dev/lirc --output=/dev/lircd \
    --pidfile=/var/run/lircd.pid --connect=localhost:8765

All events will now be visible at /dev/lircd. The second lircd instance connects to the first instance using a TCP/IP socket. The default port is 8765. It can be changed by providing an optional parameter to the --listen switch. If you have more lircd instances you want to connect to, you can provide multiple --connect parameters to the last lircd instance. Please note that lircd will not relay events received from one lircd to another. So you can't daisy-chain lircds. Instead you need a star topology setup.

> irw /dev/lircd1

Also using a special lircd instance to send infra-red commands is quite easy: use the --device command line option of irsend to provide the desired socket interface.

The only situation where the described procedure will not work is when you have two devices that both use a kernel driver that can only handle one device at once like e.g. lirc_serial, lirc_sir or lirc_parallel. You can still make it work with a trick by compiling the affected driver multiple times using different names and different major numbers. You will find detailed instructions how to achieve this by searching the mailing list. Lifting this limitation is one of the todo items for future releases.

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 prefered protocol.

lircmd can basically be used with two applications: X11 and gpm
Configuration of both is described here:

X11

3.x

Just put this section in your XF86Config file to use the mouse in addition to your normal one.

    Section "XInput"
        Subsection "Mouse"
            Protocol    "IntelliMouse"
            Device      "/dev/lircm"
            DeviceName  "Remote"
            AlwaysCore
        EndSubsection
    EndSection

Additionally you might have to add

        Buttons 5

to your normal "Pointer" Section in order to make the wheel buttons work. Of course you have to replace IntelliMouse with IMPS/2 or MouseSystems if you really want to use one of this protocols. Colas Nahaboo's X mouse wheel scroll page gives you further information how to make use of your new wheel mouse.

Make sure you use a current version of X11. There seems to be a bug in X version 3.3 that can make X crash if you use both mouse and remote control mouse simultaneously. At least I couldn't reproduce this with other versions. I also received some notes that lircmd does not work with certain X11 versions. But almost always at least one of the protocols did work. So try them all before trying another X11 version. But always remember that you have to modify both XF86Config and lircmd.conf so they use the same protocol.

4.x

Put this section in your XF86Config-4 file to use the mouse in addition to your normal one.

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

And add a line to the ServerLayout section like this:

Section "ServerLayout"
        ...
        InputDevice    "LIRC-Mouse"           <-- add this line
EndSection

gpm

You can also e.g. use multimouse (available at ftp://sunsite.unc.edu/ or mirrors) or gpm to use it parallel to your normal mouse. With:

    gpm -t ps2 -R -M -m /dev/lircm -t ms3

    gpm -t ps2 -R -M -m /dev/lircm -t imps2

    gpm -t ps2 -R -M -m /dev/lircm -t msc

I can use my usual PS/2 mouse and my remote control (IntelliMouse, IMPS/2 or MouseSystems protocol) at the same time to control the mouse pointer.

Note: If you update lircmd.conf you can send the HUP signal to lircmd:

    killall -HUP lircmd

This instructs lircmd to reread its config file. The same is true for lircd if you change lircd.conf. lircd will also reopen its log file on SIGHUP.

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 seperate 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

At this point all you need are the tools, which react on the signals decoded by lircd. To do this you need a file called .lircrc. It should be placed in your home directory. Optionally you can create a system-wide configuration file located in /etc/lircrc, which will be used when no .lircrc file 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.

First I will explain the syntax of the .lircrc file itself. The config file for LIRC tools consists of one or more of the following constructions:

    begin
	prog	= ...
	remote	= ...
	button	= ...
	repeat	= ...
	delay	= ...
	config	= ...
	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).

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. 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.

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

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.

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 if they have to be executed. You can stop this immediately with this flag.

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

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 ~/.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.

Ok, now a simple example for a .lircrc file (supposed you use an AnimaX remote and use the sample files for this remote from the remotes/ directory. If you have another remote change remote= and button= according to your remote [this 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 .lircrc in your home directory, 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.

If you start a LIRC client program, it reads your ~/.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 have to maintain may differ between applications. Also key sequences might not be recognized equally because all programs then don't have the same starting point.