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.

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 should check if the drivers
you want are listed now with lircd --driver=?. You
should get something like this:

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):

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:

All events will now be visible at /var/run/lirc/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.

In order to check each lircd instance individually if events are
being received, just use irw providing the according socket
interface on the command line:

> irw /var/run/lirc/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 preferred 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.

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.

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 /var/run/lirc/lircm -t ms3

or

gpm -t ps2 -R -M -m /var/run/lirc/lircm -t imps2

or

gpm -t ps2 -R -M -m /var/run/lirc/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.

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

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/lirc/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:

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

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

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.