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.
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 (
# tar -xzvf lirc-X.X.X.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
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:
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
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
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:
- Those which could and actually have been built with LIRC support. These act as LIRC clients when there is a running LIRC daemon.
- Those which do support LIRC, but have not been compiled with the LIRC support enabled.
- 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:
.lircrcand placed in the user’s home directory.
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.
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:
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
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.
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.
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:
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.
You should read:
- The LIRC Manual (Documentation)
The How to configure and use LIRC by George Notaras, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.