Dependencies

To use LIRC's setup.sh script you need the dialog package. It already should be installed on most systems. The setup.sh script makes configuration of LIRC much easier but using it is not obligatory.

If you want to compile and use all tools, you also need an installed svgalib (used by smode2) and the X Windows header files (needed by irxevent and xmode2). You can get svgalib from ftp://sunsite.unc.edu/pub/Linux/libs/graphics/. The configure script will notify you if some necessary files are missing and the according tools won't be compiled.

Irman (=UIR) : To use your Irman with LIRC you need the latest libirman library. At the time this has been written the current libirman version was 0.4.3. Former versions won't work. Please also read Updating from lirc-0.5.4.

Kernel modules: All devices that require a kernel module will need the properly configured kernel sources being available somewhere in /usr/src/. During the build process of this package the kernel Makefile and the current kernel configuration will be used to work around some other problems that would arise if we used our own Makefile. That means that you might have to build your own kernel which is a good idea anyway. Make sure you use the standard kernel which you can download at www.kernel.org. Don't use any kernel sources that have been modified for your distribution. For example you won't be able to compile some modules for kernels that come with S.u.S.E. 7.0. Please refer to the documentation of your distribution or read the README file in the kernel source directory to get more information on how to compile and set up an own kernel. More documentation is available at the Linux Documentation Project.

If you are still running a stock kernel that came with your distribution and don't want to compile a new kernel you can try the following. Install the kernel sources package of the currently running kernel. Most distributions provide rpm/deb packages of their stock kernels. Double-check that you selected the correct kernel sources. Now make sure that there is a file called .config in the root directory of the kernel source tree. This file holds the configuration used to compile this kernel. If it is not available and you can't get it from a different source (/boot/config-version (Debian), /proc/config.gz (SuSE) or /usr/src/linux-version/configs/ (Red Hat) are good places to look into) you are out of luck and will have to configure and compile your own kernel. Otherwise call make oldconfig && make dep inside the root directory of the kernel source tree. After that you should be able to compile the LIRC modules without problems. Just make sure that the configure script for the LIRC package picked the correct kernel source directory. But be aware that there might still be some problems due to incompatible extensions of the distribution kernels as mentioned in the last paragraph. There are even more pitfalls. The modules should be compiled with the same compiler version. Otherwise you might see strange lockups and kernel oopses. Another problem might be that some distribution vendors also modify the kernel version variables inside the Makefile of the kernel and e.g. add something like custom to the EXTRAVERSION variable. This will result in the modules being installed in the wrong directory. In such cases it is common practice to remove the custom string before proceeding with kernel compilation. This has been only a list of known problems. If you run into such problems I won't be able to help you, so don't even ask.

If you want to use a home-brew receiver, an Anir Multimedia Magic, a Packard Bell receiver, the IRdeo or if you want to use the SIR IrDA driver, I suggest that you compile the Linux kernel serial port driver as a module (however, you can choose not to do so if you use setserial properly, see below). The according kernel option that should be set to M is Standard/generic (dumb) serial support (resp. Standard/generic (8250/16550 and compatible UARTs) serial support for 2.4 kernels) in the Character devices section of the kernel configuration dialogue. Usually the serial port driver grabs all ports it auto-detects as soon as it is loaded and the LIRC modules won't be able to use any of them.

There are two solutions for this problem. Either you load the LIRC module before the kernel serial port driver is loaded (that's why you have to compile it as a module) or you call setserial /dev/ttySx uart none to release the according port. setserial usually is already called during boot-up in some init script whose location depends on the distribution you use. Be aware that setserial might also be the cause of trouble. The reason for this is a kernel bug (known to be true for 2.2.20, patches are on the way). If you tell setserial to configure a port that is already claimed by a LIRC module, the kernel serial driver will steal the port from the LIRC module and LIRC will stop working. So check your setserial configuration to only configure available ports. Debian users should adjust their /etc/serial.conf.

TV cards: To use any remote control receivers connected directly to a bttv based TV card you will need a working bttv setup in your kernel. For most TV cards we rely on bttv autodetection. That way you don't have to give any parameters to the module as they are selected internally depending on the information the bttv module gives us. This means that you should pay attention that your TV card is detected correctly by bttv.

Technisat MediaFocus I: You will have to install the driver for this card.

Supported Hardware

Generally speaking everything that can receive or send infrared signals can be supported by LIRC. The project began with support for home-brew receivers and transmitters for the serial port and later support for analogous hardware for the parallel port was added. At that time the focus of the project was to provide an infrared solution that is both very cheap and easy to assemble. The following links point to instructions how to build your own receiver/transmitter.

• Building a serial port receiver
• Building a serial port transmitter
• Building a parallel port transceiver

Current versions of LIRC now support many more commercially available solutions. Examples are the Irman, built-in IrDA ports or TV cards. Drivers for even more hardware are likely to appear in the future. If you are a programmer who wants to maintain such a driver you are welcome to join the project.

You should locate your device in this list of supported devices and see if there is additional information available regarding the setup of your device.

Compiling

Before compiling the binaries you have to choose which driver to use. This can easily be done with the setup.sh script. Just type ./setup.sh from the shell prompt. After selecting your driver you can exit the setup with "Save configuration & run configure".

If you don't have dialog installed you will have to do it the hard way and give the correct parameters to the configure script manually. See ./configure --help for a detailed description of the possible parameters. You will have to at least choose a driver with the --with-driver=X option.

There are three special drivers:

all

will build multiple drivers into lircd and runtime selection will be possible using the --driver option. However, not all drivers are included, so in some cases you will have to select the appropriate driver and not all. This option will also compile all available kernel modules. Some kernel modules are only supported with recent kernel versions. That means that compilation of these drivers might fail with older kernel versions. If this happens for you, you should consider using the userspace driver described below and only compile the kernel modules that you need separately.

none

will only let lircd talk to other lircd's though the network and not to any local hardware.

userspace

behaves like the all driver option except that no kernel modules will be built.

When running the configure script, please pay attention at its output. At the end of the configuration checks, it will tell you which kernel module (if any) will be required for your hardware. You can also look up this information in the device table. After having configured the package just type make and lean back.

Note: You won't find a configure script in the source repo version of LIRC. You will have to generate it first by executing ./autogen.sh. You need at least libtool-1.3.3, automake-1.4 and autoconf-2.13 to do this properly.

Installation

Installing the compiled programs is really easy, just type make install. All binaries and modules should be installed at the usual places. The necessary devices should be generated in the /dev/ directory and all configuration files should be copied to its proper destination if you happen to use some hardware where configuration files are already available.

When you are using devfs or sysfs with your kernel, the /dev/lirc device node will disappear again once you reboot your machine. In that case the LIRC kernel module will generate the required entry every time it is loaded. But the device node won't be visible as /dev/lirc, but might be located in a different location like e.g. /dev/lirc/0. Please be aware of this fact when starting programs that access the device node like mode2 or lircd. You will have to use the --device command line option of these programs to point them to the correct location. When using sysfs together with the udev daemon you should copy the lirc.rules file located in the contrib directory of the source package to /etc/udev/rules.d/. This will make sure that the device node will be created.

The core program of LIRC is lircd, the LIRC system daemon that does all of the decoding of infrared signals. LIRC comes with a second daemon program: lircmd. lircmd depends on lircd and translates remote control activity to mouse movements. Just like all other daemons both lircd and lircmd should be started at system boot time and do their work in background. If you want to start them automatically at boot time you will have to add an init script for them to your system. Unfortunately the syntax and location of this init script is highly dependent on the distribution you use so you will have to figure it out yourself how this works on your system. Good news is that there already are some init scripts available in the contrib/ directory of the LIRC package.

Warning: Never compile daemons with "Disable daemonize" turned on and place them in some init script unless you have a rescue disc nearby...

Now you should adjust the file permissions of /var/run/lirc/lircd (this is the Unix domain socket that clients use to connect to lircd) so others than root can connect to lircd.

        chmod 666 /var/run/lirc/lircd

should do. You can also create a special group for this purpose.

If your hardware requires a kernel module you should make sure that the kernel will find the correct module if a program tries to access /dev/lirc. This can be done by inserting the following line to your /etc/conf.modules (/etc/modules.conf for current kernel versions):

        alias char-major-61  lirc_driver

Note that here driver is a placeholder for the actual driver you are using (serial, parallel, etc.).

If your driver requires some special parameters to work you can specify them at the same place. For example you can set the IRQ and I/O base the serial port drivers shall use by adding the following line to /etc/conf.modules:

        options lirc_serial irq=4 io=0x3e8

This will override the default values you have selected during setup. The configure script will tell you which kernel module you need.

Finally you might want to add /usr/local/lib to /etc/ld.so.conf so the lirc_client library is found by the run-time linker. Don't forget to call ldconfig afterwards for the change to take effect.

Testing your hardware & configuration

If you have build the infrared hardware yourself you are probably eager to find out if it really works. If you have not build the hardware yourself you can skip the first test. For most receivers it even won't work because it makes no sense.

Type su to get root privileges and start mode2 (Warning: don't confuse mode2 with mode3: mode3 will set your video card to a vesa mode using the vesa bios calls...). This should load the kernel module into the kernel and display the infrared signals. Hold your remote control to your infrared receiver and press some buttons. You should see an output like this (the values of your remote will probably be different):

        pulse 93
        space 4965
        pulse 108
        space 4969
        pulse 93
        space 7496
        pulse 93
        space 7489
        pulse 93
        space 47915
        pulse 138
        space 7475
        pulse 93
        space 7494
        pulse 93

If you don't see anything, try to find out: (a) if you selected the correct driver with the correct settings (I/O base address, IRQ), (b) if you use a remote which works and (c) if your hardware works. The voltage input of the infrared receiver should be 5V +/- 0.5V, the output pin of the receiver should be about 0.5V less than the input voltage.

From time to time there should be long spaces (>30000). If you can see very long pulses this usually means that sense auto detection of your serial port IR receiver circuit has failed. You can override sense auto detection by loading the device driver with the following option:

modprobe lirc_serial sense=0 if your receiver circuit is active high or
modprobe lirc_serial sense=1 if your receiver circuit is active low.

Well, the driver seems to work, now let's test if lircd also does its job. This only works, if lircd uses a config file which fits to your remote control. Use irrecord in the case the LIRC distribution doesn't provide a config file suitable for your remote and it still is not available at the LIRC homepage. A more detailed discussion of creating new config files is available in the section about, you guess it: Adding new remote controls.

Then start the decoder daemon with (make sure it is in your path): lircd [config file]

The following program dumps the decoded key codes from lircd to stdout: irw

This looks like this (depending on your remote):

        0000000000f40bf0 00 1_DOWN ANIMAX
        0000000000f40bf0 01 1_DOWN ANIMAX
        0000000000f40bf0 02 1_DOWN ANIMAX
        0000000000f40bf0 03 1_DOWN ANIMAX
        0000000000f40bf0 04 1_DOWN ANIMAX
        0000000000f40bf0 05 1_DOWN ANIMAX
        0000000000748bf0 00 1_UP ANIMAX
        0000000000748bf0 01 1_UP ANIMAX
        0000000000748bf0 02 1_UP ANIMAX
        0000000000718ef0 00 RED_BUTTON_UP ANIMAX

If the driver test did work, but you now see nothing, then check /var/log/lircd. If you still see nothing suspicious compile lircd in DEBUG mode and look at the log file again. In debug mode lircd has an additional command line option that lets you choose the detail level of debug information.

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 inside the remotes/generic/ directory of the LIRC package.

If you want a graphical interface for controlling your devices using LIRC, you should have a look at xrc. You can download the xrc package from the LIRC homepage. xrc is a Qt based program. Setting up xrc and Qt is a bit tricky so if you don't manage to compile it you can still use irsend. It has the full functionality you need.

Uninstall

• Remove the installed binaries, and device nodes:
  
  make uninstall
  
  
• Remove the config files, if you don't need them anymore:
  
  rm /etc/lirc/lircd.conf /etc/lirc/lircmd.conf /etc/lirc/lircrc ~/.lircrc
  
  

Module specific information

lirc_gpio

This module receives scan codes from the GPIO register of bt8[47]8 chips using polling or interrupts if the card supports this. It is a "plugin" for the lirc_dev module. It loads bttv and lirc_dev modules if they are not loaded yet.

The following gives a list of parameters for the module. If your TV card is already listed as supported than you don't need to care about parameters except debug and card because all other are set to the correct values automatically. Setting the values manually only makes sense while adding support for a new TV card so that you don't have to recompile the module each time you try a different value.

• debug (0) - value other than 0 (zero) enables printing more log messages
• card (0) - number of TV card from which receive scan codes
• minor (-1) - minor device number for /dev/lirc device
• gpio_mask (0) - bit mask used for extracting usable bits from GPIO value
  If this parameter is equal to 0 then the module tries to autodetect the TV card and the remaining parameters are ignored.
• gpio_lock_mask (0) - if this value "anded" with GPIO value is non zero than it indicates that scan code is not ready (value of 0 of this parameter disables checking)
• gpio_xor_mask (0) - bitmask applied (by xor operation) to GPIO value before lock_mask is checked
• soft_gap (0) - minimal gap (in milliseconds) between two scan codes (value of 0 disables checking)
• sample_rate (10) - how often (times per second) GPIO will be polled, set to 0 for interrupt driven input
• bttv_id (unknown) - force given bttv id, signals from some cards are translated to match original codes

Usage example would be e.g:

Autodetection is performed using the API from the bttv module - this means that if bttv doesn't properly recognize the card type the remote control won't work.

Updating from lirc-0.5.4

This section only describes changes that break compatibility with older versions. Please read the NEWS file to learn about all new features of this release.

The config files of lircd and lircmd are now located in /usr/local/etc/ instead of /etc/ per default. Most people prefer to make /usr/local/etc/ a link to /etc/.

The modules no longer are uniformly installed as lirc.o but are called lirc_driver.o depending on the driver you are using. Therefore you might have to edit your /etc/conf.modules and change the line

    alias char-major-61 lirc

to whatever you need.

LIRC now supports the Irman directly. lirmand is no longer necessary. Before installing this version you should call rm /dev/lirc to remove the FIFO that was used in lirc-0.5.4. /dev/lirc now should be a link to the device the Irman is connected to (e.g. /dev/ttyS1).

Updating from lirc-0.6.2

The lirc_gpio_p has been renamed to lirc_gpio. It now also contains support for TV cards that are able to generate interrupts if infra-red commands are received. The lirc_gpio_i driver that implemented this has been removed. The lirc_fly98 also has been removed as it is now supported by the lirc_gpio driver.

The lirc_haup module has been renamed to lirc_i2c.

The transmit code in lirc_serial has been modified slightly. If you have problems transmitting decrease the frequency value in the lircd config file by approximately 2000.

There have been major changes to the SIR driver. If you used this driver before you may have to generate new config files for your remotes. Transmitting is now more likely to work.

The config file for the old AVerMedia TVCapture and TVPhone cards (pre 98) has changed. Please use the new config file that you can find in remotes/avermedia/lircd.conf.avermedia.

Updating from lirc-0.6.3

lircd.conf and lircmd.conf are in /etc again.

Two independend bugs were fixed in the IRdeo and home-brew transmitter code that affected correct pulse/space timings in some situations. This might break config files that did work with previous versions.

Updating from lirc-0.6.4

AVerMedia TV cards with ID 0x00011461 and 0x00041461 should finally work with the provided config files. That means they will no longer work with the config files you have created yourself.

The I/O base address for some modules now is set with the io parameter. (formerly: lirc_sir = iobase, lirc_serial and lirc_parallel = port).

Updating from lirc-0.6.5

The config file for the Pixelview PlayTV pro and compatible TV cards has changed. Please use the config file in remotes/pixelview/lircd.conf.playtv_pro.

The config file for the Winfast TV2000 and compatible TV cards has changed. Please use the config file in remotes/winfast/lircd.conf.tv2000.

Updating from lirc-0.6.6

The config files for all FlyVideo TV cards have changed. Please use the config file in remotes/life-view/lircd.conf.flyvideo.

The config file for the Winfast TV2000 TV card has changed. Please use the config file in remotes/leadtek/lircd.conf.RM-0010.

The lirc_sir now should generate better signals for some remotes. Due to the change some old config files generated with previous versions of the driver might stop working. In this case you should just create a new config file using the new driver. If you want to get the old behaviour of the driver (deprecated) you can insert the module using the threshold=2 parameter. The default of threshold is now set to 3. You might even want to try higher values.

When you are using LIRC with the Linux input layer driver, make sure that your config file contains the following line in its header:

        bits 32
    

Otherwise lircd will not recoginise any events.

Updating from lirc-0.7.x

There is a new program that you probably want to use: lircrcd reads the .lircrc config file and synchronises the mode that the LIRC clients using this config file (irexec, irxevent, etc.) are in. Using lircrcd has to be explicitly enabled in the config file by adding the following line at the beginning of the file:

#! lircrcd

Updating from lirc-0.8.1

The config file for the Pinnacle Systems PCTV (pro) receiver has changed. Please use the config file in remotes/pinnacle_systems/lircd.conf.pctv.

The config file for the Creative Infra Receiver/CIMR100 has changed. Please use the config file in remotes/creative/lircd.conf.creative.

Updating from lirc-0.8.4

Newly added iMon LCD displays with device ids 15c2:0038 and 15c2:0045 use a larger buffer to enable all remote and panel buttons. Consequently, config files for earlier iMon receivers are not compatible with these new devices, and vice versa. Be sure to select the appropriate 64-bit config for a newer iMon LCD. (Early cvs support for the 0038 used only a 32-bit buffer). For the 0038: remotes/imon/lircd.conf.imon-ultrabay. For the 0045: remotes/imon/lircd.conf.imon-antec-veris.

The behaviour of the quit flag in the .lircrc config file has changed slightly concerning button sequences. Previously the quit flag had no effect on button sequences which had partly been entered. Now the quit flag will make execution of further configurations stop even though just part of the button sequence has been entered.

There was an interface change in the lirc_dev kernel module. If you get an error message like

lirc_serial: Unknown symbol lirc_unregister_driver
lirc_serial: Unknown symbol lirc_register_driver

Updating from lirc-0.8.5

The lircd socket was moved from /dev/lircd to /var/run/lirc/lircd to conform to the Filesystem Hierarchy Standard. The default pid file location was moved from /var/run/lircd.pid to /var/run/lirc/lircd.pid.

The default location of lircd, lircmd and lircrcd config files was moved to /etc/lirc/lircd.conf, /etc/lirc/lircmd.conf and /etc/lirc/lircrc. If the config files are not found in that location, they are still searched at the old location in /etc/.

The functionality of the lirc_mceusb2 driver has been merged into the lirc_mceusb driver. The lirc_mceusb2 driver is now obsolete and has been removed. You should use lirc_mceusb from now on.

Updating from lirc-0.9.0

Building kernel modules is not supported from 0.9.1. Most tests are done using 'with-driver=userspace'. Using other options is deprecated and will not be supported in upcoming releases.

From 0.9.1 it's not necessary to setup the kernel rc driver using something like 'echo "lirc" > /sys/class/rc/rco/protocol"; this is done automagically by lircd. Doing it twice does no harm.

From 0.9.1 lirc uses a new configuration file for default option values, normally /etc/lirc/lirc_options.conf. The idea is that setting up the lirc services should not be distribution dependent.

From 0.9.1 lirc has a rather complete systemd support. By default, services are installed in /usr/lib/systemd/system. Note that the service to run lircd is lircd.socket, not lircd.service.

From 0.9.1 the documentation is built by a plain make (earlier, this required a specific target). As a result, the built docs are not part of the distribution. Note that ./ configure affects how the docs are generated.

By default, stub configuration files are installed. This can be disabled using the new --with-install-etc configure option.