LIRC is basically a small server which can decode or transmit infra-red signals. This is a tutorial about how to set up the LIRC server and how to use it in order to control your system or specific LIRC-enabled applications with a remote control. Examples of simple or more complicated setups are also provided.

Prerequisites

In order to use LIRC you will need the necessary hardware components, a remote control and an infrared receiver. LIRC supports a lengthy list of such devices. You can check if your equipment is supported at this page.

Next thing is to download the latest stable LIRC package from the project page and configure it properly for your equipment. For this article I’ll use the traditional way of compiling and installing software, so some such experience is required from your part. Of course, if you are into package building, you can build your own RPM or DEB package.

Configure, Compile, Install

Extract the LIRC package in a temporary directory (~/tmp/):

# tar -xzvf lirc-N.N.N.tar.gz -C ~/tmp/

The most important part of the LIRC pre-compilation configuration is the choice of the appropriate driver for your hardware. For more info check the LIRC Documentation. Normally, if you know your hardware, change to the directory where you have extracted the LIRC package and issue the following command in order to check which driver name you should use:

# ./configure --help

Next, configure the package for your system. Because some kernel modules are built together with LIRC, you will need to have the kernel development package (eg kernel-devel) for your running kernel installed. To configure LIRC issue the command:

# ./configure \
--prefix=/usr \
--with-x \
--with-transmitter \
--enable-sandboxed \
--with-moduledir=/lib/modules/$(uname -r)/extra/lirc \
--with-kerneldir=/path/to/kernel/headers \
--with-driver=DRIVER

Substitute DRIVER with the appropriate driver name and edit the path to your kernel headers/sources in the --with-kerneldir option. Note that the --with-kerneldir option can be safely omitted.
We use the --enable-sandboxed option, so that the installation script does not try to create any device nodes for LIRC. An UDEV rule, that we will create later on, will take care of this.

If the configuration script fails due to missing dependencies, make sure you have all the necessary development tools, libraries and kernel headers installed in your system. Just read carefully the on-screen error messages to see what is missing.

After this configuration is finished, you will see a message in your terminal about which LIRC module will be used. Take a note of the module name, as you will need it later on.

NOTE: On Fedora, I was not able to build the required lirc_gpio module. My IR receiver is attached on my KWorld TV tuner card, so this module was absolutely needed. In such a case you will probably want to read my post about the The Complete Fedora Kernel Headers.

Next, proceed to the LIRC compilation:

# make

and installation. This step is needed to be done as root:

# make install

If for any reason you want to uninstall all LIRC files, from within our current directory, issue the command:

# make uninstall

Special Note: Before you update your system kernel at some later time, you will need to uninstall LIRC. After the kernel upgrade, you will have to repeat the previous configuration, compilation and installation steps, so that the LIRC module is built for your new kernel.

The final step is to create an UDEV rule, so that the LIRC devices are created properly and with appropriate permissions.

Create a text file, named 10-lirc.rules, in the /etc/udev/rules.d/ directory and add the following to it:

KERNEL=="lirc[0-9]*", NAME=="lirc%n", GROUP=="disk", MODE=="0660"
KERNEL=="lirc0", SYMLINK=="lirc"

Finally, make sure you add the users you want to have access to the LIRC server to the group disk. Alternatively, if you want all the users to be able to access LIRC, then modify the MODE in the UDEV rule above from MODE=="0660" to MODE=="0666".

That’s it.

The LIRC Server Configuration

It seems that the LIRC daemon (lircd) does not load the default module (driver) automatically when it starts, so this module should be loaded manually.

To load the appropriate module and the LIRC server at boot time, all you have to do is to add the following lines to the /etc/rc.d/rc.local file. As root:

modprobe MODULE_NAME
lircd

Substitute MODULE_NAME with the module name you had taken a note of when configuring LIRC. For me, it would be lirc_gpio. The LIRC daemon, by default, uses the driver that was defined during the LIRC pre-compilation configuration.

The LIRC daemon also needs a configuration file (/etc/lircd.conf), which contains the proper addresses of your remote control’s buttons. The LIRC package contains some ready made remote configs, but I suggest you create your own. Read on…

The Remote Control Configuration file

In this section we will create a configuration file for our remote control by using an utility named irrecord, which was built together with the rest of the LIRC components. Since irrecord is a lircd client, the LIRC daemon needs to be running prior to using this tool.

So, as root, load the appropriate LIRC module and start the daemon:

# modprobe MODULE_NAME
# lircd

Now, change to a temporary directory and start irrecord:

# irrecord REMOTE_NAME

REMOTE_NAME is the remote control config file that will be created in the current directory. This will also be the name of your remote control that will be used within the created file. If you need to change it, do it by hand after this operation is finished. All you have to do is to follow the on-screen instructions. Generally, you will be asked to give names for the remote control buttons and to press each one of them.

After you are finished, copy the REMOTE_NAME file into /etc/, naming it lircd.conf. As root:

# cp REMOTE_NAME /etc/lircd.conf

Kill the running lircd instance and start the daemon again, so that it uses the new configuration:

# killall lircd
# lircd

Applications and LIRC Support

There are three kinds of applications:

1. Those which could and actually have been built with LIRC support. These act as LIRC clients when there is a running LIRC daemon.
2. Those which do support LIRC, but have not been compiled with the LIRC support enabled.
3. Those which do not support LIRC at all.

Generally, most multimedia applications, video and audio players, TV viewers and FM tuner applications, support LIRC. Also, many applications provide a method (separate utility or options) to send commands to a running instance of the application. This is particularly useful for programs that belong to the 2nd and 3rd categories. LIRC provides an utility, called irexec (LIRC client), which can be used to execute any command we want. This way, those applications can be controlled with the remote control through LIRC.

In order to use our remote control with a certain application, we have to create a configuration file that contains the mappings between the remote control’s buttons and the commands that will be executed when each button is pressed.

This file can be:

• named .lircrc and placed in the user’s home directory.
• named lircrc (without the period in front of the name) and placed in the /etc/ directory for system-wide configuration.

Information about this file’s format can be found in the relevant section of the LIRC Documentation.

Quick Tests

Here are some sample .lircrc files, so that you can test your installation. Make sure you have loaded the proper LIRC module and you have started the LIRC daemon. Save one of them as .lircrc and place it in your home directory.

Special Note: In the following sample config files, substitute the remote control name with the name you have used for your own remote control and the button name with a name of any of your own remote control’s buttons.

The first two samples will work with Xine and MPlayer respectively. These two players are usually built with LIRC support and, when launched, they act as LIRC clients.

Load Xine and press the specified button on your remote control. It should toggle between full-screen and window-mode.

# .lircrc - XINE sample test
begin
    prog = xine
    remote = KWTV878RF
    button = ZOOM
    config = ToggleFullscreen
    repeat = 0
end

Use the following config with MPlayer.

# .lircrc - MPLAYER sample test
begin
    prog = mplayer
    remote = KWTV878RF
    button = ZOOM
    config = vo_fullscreen
    repeat = 0
end

For applications that are not LIRC clients themselves, but which provide a method to send commands to a running instance of the application, the configuration is a bit different. The LIRC client irexec is used in these cases. When you press a button on the remote control, irexec executes the specified command. This requires that irexec is running. Start it as a user:

# irexec

Save the following as .lircrc and launch TVtime. The specified button on the remote control should toggle between full-screen and window-mode.

# .lircrc - TVtime sample test
begin
    prog = irexec
    remote = KWTV878RF
    button = ZOOM
    config = tvtime-command TOGGLE_FULLSCREEN
    repeat = 0
end

To start irexec and have it run in the background, start it as shown below:

# irexec &

To kill it:

# killall irexec

Some hints for more complicated configurations

Here are some hints for those of you who need complicated setups.

Toggle Buttons

You can create toggle buttons, for example you can set the same button to Play or Pause a video stream, by setting two config = command directives. They will be executed in turns. For example:

# Toggle button example
begin
    prog = irexec
    remote = remoteA
    button = buttonA
    config = play_command
    config = pause_command
    repeat = 0
end

Using this configuration, when buttonA is pressed for the first time, the play_command is executed. The second time buttonA is pressed, the pause_command is executed.

Modes

Let’s assume that you want to control many applications with your remote control. Some of them are LIRC clients and some are controlled through irexec. You can define various modes (groups of button to command mappings), one for each application.

First of all, read the .lircrc format page from the LIRC Documentation very carefully.

Keep in mind the following rule:

Each time you start a LIRC client and there is a mode within your configuration with a name equal to the application’s name, then this mode is automatically entered.

This means that if there is a mode named mplayer inside .lircrc and you start the mplayer program, which is a LIRC client, then the mplayer mode is automatically entered and only the button mappings that exist within this mode are functional.

Save the following as ~/.lircrc, substitute the remote control name and button names with your own, and start irexec:

# Example with modes

# MAIN BEGIN (irexec mode) - Application Selection Mode
# ---------------

begin irexec

    begin
        prog   = irexec
        remote = KWTV878RF
        button = 1
        # Start TVtime
        config = tvtime --window &
        # Enter tvtime mode
        mode = tvtime
    end

    begin
        prog   = irexec
        remote = KWTV878RF
        button = 2
        # Start Totem player and play DVD
        config = totem dvd:/ &
        # Enter totem mode
        mode = totem
    end

    begin
        prog   = irexec
        remote = KWTV878RF
        button = 3
        # Start Xine and play DVD
        config = xine dvd:/ --hide-gui &
        # Enter xine mode
        mode = xine
    end

end irexec

# ---------------
# MAIN END (irexec mode end)



# APP MODES BEGIN
# ---------------

# tvtime mode
begin tvtime
    begin
        prog = irexec
        button = POWER
        config = tvtime-command QUIT
        # Enter irexec mode
        mode = irexec
    end
    begin
        prog = irexec
        button = ZOOM
        config = tvtime-command TOGGLE_FULLSCREEN
    end
end tvtime


# totem mode
begin totem
    begin
        prog = irexec
        button = POWER
        config = totem --quit
        # Enter irexec mode
        mode = irexec
    end
    begin
        prog = irexec
        button = ZOOM
        config = totem --fullscreen
    end
end totem


# xine mode
begin xine
    begin
        prog = xine
        button = POWER
        config = Quit
        # Enter irexec mode
        mode = irexec
    end
    begin
        prog = xine
        button = ZOOM
        config = ToggleFullscreen
    end
end xine

# ---------------
# APP MODES END

I hope this example is clear enough. What is going on here is that when irexec (LIRC client) is executed, then the irexec mode is entered. When you press button "1", then TVtime is launched and the tvtime mode is entered. When you press the "POWER" button, TVtime quits and the irexec mode is entered etc. etc.

Furthermore, even if you do not start irexec, when you launch any LIRC enabled application, like Xine, MPlayer, Gnomeradio etc, then the appropriate mode will be entered automatically and you will be able to control this application remotely.

As you have probably already read in the LIRC Documentation, you can modularize this configuration by keeping each application mode in a separate file. Just don’t forget to include those separate files by adding a line like the following in ~/.lircrc. For example:

include ~/.lirc/tvtime.lircrc

Final Notes

Maybe you will need some time to familiarize yourself with the .lircrc format and probably more time reading the LIRC documentation, but you will be satisfied with the result.

For information about what commands are available for each application, please refer to the application’s documentation, project web site or support forum.

Also, if you need more information or support for LIRC, please ask your questions in relevant web forums. I have written all I know in this guide, so I am afraid I cannot help you more.

LIRC can do more things, for example it can be used to transmit IR signals or to connect to other LIRC servers accross the network. These have not been covered, not only because I consider such info as "too much" for a new user, but also because I have not been able to devote any time to experiment with these features.

This guide was written while using a Fedora 4 system.

Further Reading

You should read:

1. The LIRC Manual (Documentation)

How to configure and use LIRC by George Notaras is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Copyright © 2006 - Some Rights Reserved