Configuration guide

About this guide

This guide tries to describe the basic configuration steps for commonly used hardware. It's focused on the basic usage scenario to get the remote up and running, the more advanced features are not covered. This includes irexec, lircmd, ir blasting and the TCP/IP-based remote features.


Why should I use LIRC?

Recent Linux kernels have built-in support for IR remotes. Using that, pressing an up-arrow on the remote works the same way as pressing the up-arrow on a keyboard. This is a modern "just works" solution. On the other hand, LIRC is an old style linux application which can be tweaked to do almost anything, but is tricky to setup. So, why would you use LIRC?

So, while the kernel built-in handling works out of the box in many cases, there are still scenarios when LIRC is the right tool.


The default configuration

From 0.9.4+ LIRC is distributed with a default configuration based on the devinput driver. This should work out of the box with the following limitations:

The easy way to check is to try the remotes without lircd running. If it works this way, it should also work using lircd.

To check the number of supported devices run ls /sys/class/rc. This should list a single entry rc0.

If you want to use the default configuration you should start and enable the lircd service and possibly define lircrc files for your applications. However, you can use the lirc_options.conf file as-is. See systemd-setup


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 similar hardware for the parallel port was added. At that time the focus of the project was to provide an infrared solution that was both very cheap and easy to assemble. There is some more info on this in Appendix 11

Current versions of LIRC now support many more commercially available solutions. As a starter, it can use all devices supported by the kernel. Besides those, it has specific drivers for other devices including the Irman, built-in IrDA ports, TV cards, and consumer devices like Tira and Irtoy.

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.


Overall Configuration Decisions.

       ----------         ---------------                     ----------
       |        |         | Linux input |                     |        |
       |        |---->----| layer       |---------->----------| Appli- |
       |        |         |             |  /dev/input/eventX  | cation |
       |        |         ---------------                     |        |
--->---|        |                |                            ----------
remote | kernel |       devinput v
       |        |                |
       |        |                |                            ----------
       |        |         ---------------                     | Appli- |
       |        |---->----|    lirc     |---------->----------| cation |--
       |        |         |             | /var/run/lirc/lircd |        | |
       ----------         ---------------                     ---------- |--
                                                                |        | |
                                                                ---------- |
                                                                  |        |
                                                                  ----------
    

LIRC can be run together with the kernel in different ways. You need to decide on a general approach.

Depending on whether lirc is used or not application will get data either from the input layer (/dev/input) or from LIRC (/var/run/lirc/lircd). Using the LIRC data requires application support. Support for LIRC is common in typical linux htpc applications like mythtv, kodi and vlc; of course also LIRC applications like irexec, lircmd and irpty supports this.

The /var/run/lirc/lircd interfaces allows several applications to receive input events. On the other hand, the /dev/input interfaces only allows one application to receive each event. Despite these limitations, a common scenario is to not involve lirc at all, the upmost path in the picture (kernel -> Linux input layer -> application). Unless there is reason to use lirc (above)) this is probably the way to go.

If you need to use lirc, there are two cases depending on if your remote is supported by the kernel or not.

It is also possible to use lirc as a pure low-level driver, and let the application receive the data from /dev/input, just as for a device supported by the kernel. See lircd-uinput(8)

The lirc configuration consists of several files described in Appendix 10. There are some tools to aid in the configuration listed in programs overview


Basic setup flow

      ------------
      |  remote  |
      ------------

        (air gap)

      ------------
      ! capture  !
      ! device   !
      ------------
           |
           v
           |
      ------------
      ! kernel   !                   Sometimes needs
      ! driver   !                   modprobe(1) configuration.
      ------------
           |
           v  IR pulse data          Device like /dev/lirc0, /dev/ttyACM0.
           |                         or /dev/ttyS0.
      ------------
      |  lirc    |                   Configure lirc_options.conf
      |  driver  |                   with driver and usually also device.
      ------------
           |
           v  IR pulse data          Use mode2(1) to debug
           |
   ----------------
   |  lirc pass 1 |                  lircd.conf config file.
   ----------------
           |
           v  Key symbols            Output socket e. g.,
           |                         /var/run/lirc/lircd. Use irw(1) to debug.
           |
   ----------------
   |  lirc pass 2 |                  lircrc config file.
   ----------------
           |
           v  Application strings    Use ircat(1) to debug.
           |

      Applications
    

The overall LIRC blues:

This flow is configured in four points:

lircd can handle multiple remotes using the same capture device. This is described in Appendix 8.

To use multiple capture devices you need to setup multiple lircd instances as described in Appendix 9.

lircd can run as a regular user or as root. Some aspects on running as a non-root user is described in Appendix 14.


Determine driver and device

To determine the driver to use you might need to know the name of your capture device, what module the kernel has loaded for it and the kernel device it's connected to.

If our remote is bundled with a capture device such as a usb dongle, your first stop is the remote database. If you can find your device here, look in lircd.conf file's header for the following comment:

        this config file was automatically generated
        # using lirc-0.8.5-CVS(awlibusb) on Thu Oct 30 11:03:30 2008
    

Here you can learn that this file was recorded using the awlibusb driver. Take a note to the final decision.

Next thing to do is to invoke ir-keytable:

    $ ir-keytable
    Found /sys/class/rc/rc0/ (/dev/input/event11) with:
        Driver em28xx, table rc-pinnacle-pctv-hd
        Supported protocols: NEC RC-5 RC-6
        Enabled protocols: RC-5
        Extra capabilities: <access denied>
    

If you get this kind of output you know the event device (/dev/input/event11) and the kernel module loaded (em28xx). Furthermore, since ir-keytable finds the device you know that the driver is part of the rc subsystem. Not all devices are recognized by ir-keytable, though.

Next step is to inspect dmesg, possibly after reconnecting your device. If you have a standard IR remote which is recognized by the kernel you can find how it's registered as rc0:

     usb 3-2: Product: eHome Infrared Transceiver
     Registered IR keymap rc-rc6-mce
     input: Media Center Ed. eHome Infrared Remote Transceiver (0609:031d)
          as /devices/pci0000:00/0000:00:14.0/usb3/3-2/3-2:1.0/rc/rc0/input16
     rc0: Media Center Ed. eHome Infrared Remote Transceiver (0609:031d)
          as /devices/pci0000:00/0000:00:14.0/usb3/3-2/3-2:1.0/rc/rc0
     input: MCE IR Keyboard/Mouse (mceusb) as /devices/virtual/input/input17
     rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0
   

If you just find something like this you have a device which isn't an IR device (in this case an RF remote):

        usb 2-2: Product: RF receiver
        usb 2-2: Manufacturer: X10 WTI
    

Even if you have an IR device, you might see something like this if the kernel sees it as a keyboard rather than a remote. Here, an usb keyboard from JITTEL:

    Product: JTTEL Composite Devices
    hid-generic 0003:20E8:5820.0001: input,hidraw0: USB HID v10.01 Keyboard
        [JTTEL Inc. JTTEL Composite Devices] on usb-0000:00:1d.1-1/input0
    

For devices like these which not are registered as rc devices (and thus not recognized by ir-keytable) you might need to find out the corresponding event device as described in Appendix 2

Knowing the capture device name, the kernel module loaded (if any) and perhaps also a /dev/input device you have to select a driver:

After selecting the driver and device you should check if there is any driver documentation. After this, check the driver and device using using e. g., something like

         mode2 --driver default --device /dev/lirc0

Refer to EXAMPLES in the mode2 manpage too see expected output.

The lirc-setup tool can be used to run mode2 with different drivers and devices in a GUI environment.

If you don't see anything, try to find out: (a) if you selected the correct driver b) If the driver needs settings (I/O base address, IRQ) in modprobe.d, (c) if the remote which works and (d) if your capture hardware works.

If you are to use the devinput driver, read on. Otherwise proceed to Getting the key symbols using lirc driver


Getting the key symbols using linux input layer

  -----------------
  |    kernel     |
  -----------------
        |
        v
        |
  -----------------
  |  input layer  |
  -----------------
        |
        v  /dev/input/eventX         Use ir-keytable to manage and debug
        |
  ----------------
  |    lirc      |                   Use devinput driver
  |              |                   Use lircd.conf.devinput
  ----------------
        |
        v  /var/run/lirc/lircd       Key symbols, use irw to debug
        |

    

If you're lucky, your remote is already supported by the kernel. In order to find out, the first task is to locate the event device, something like /dev/input/event12 which is connected to your IR device. This is described in appendix 2.

With the device known use ir-keytable to test if your remote works:

    # ir-keytable -t -d /dev/input/event13
    

Press buttons on the remote. If it starts to print out scan codes and key symbols everything is fine. Otherwise, try to change the protocol (see the ir-keytable manpage). If this doesn't work, it might be the end of the road and you might need to use the lirc driver option instead.

Check that all buttons generate output when testing. If there are buttons which are not mapped (no key symbol) you might not be able to fix this unless you go for the lirc driver option (to change the key symbol is perfectly possible, but probably not what you want here).

Then, activate the devinput.lircd.conf template which comes with lirc:

    $ cd /etc/lirc/lircd.conf.d; sudo cp devinput.lirc.dist devinput.lircd.conf
    

If the devinput.lircd.dist file is not available or have some problem it can be re-generated using the script lirc-make-devinput(1). This might become necessary if the running kernel is different from the one used when packaging the lirc files.

Start the lircd daemon and use irw to check:

    $ lircd --device /dev/input/event13 --driver devinput
    $ irw
    

Press remote buttons. You should see the key symbols being printed. When so you are done and can proceed to Configure systemd

Depending on your box, it might be that the event device found this way changes after a reboot. If this becomes o problem, look into appendix 6


Getting the key symbols using lirc drivers

  ---------------------------------
  |    kernel devices             |
  ---------------------------------
       |       | kernel rc driver |  Needs configuration
       |       -- -----------------
       |                  |
       v                  v          Pulse data on
       |                  |          a kernel device like
  ---------------         |          /dev/lirc0 or /dev/ttyACM0
  | LIRC driver |----------
  ---------------
       |
       v      pulses                 Use mode2 to debug
       |
  ---------------
  | LIRC pass 1 |                    lircd.conf
  ---------------
       |
       |      keysyms on             Use irw(1) to debug
       v      /var/run/lirc/lircd
       |
    

You have already determined the driver and device to use which is verified using mode2. Make sure the lirc driver can read the remote, and produce pulses:

lirc pass 1: Using lircd.conf, convert pulses to key symbols like KEY_UP:

The lircd.conf is the file which lircd uses to read data from the driver and then convert (or decode) it to key symbols. It's the single most important lirc configuration file. There are some ways to find or create such a file.

Even if you obtain the configuration file without using lirc-setup, you can still use it to verify the configuration. It runs lircd and irw as described below, making testing much simpler.

To install the file it should be copied to the lircd.conf.d directory, usually /etc/lirc/lircd.conf.d. Make sure the name ends with .lircd.conf.

If you are using several remotes you need to combine several lircd.conf files. See Appendix 8

After installation you should be able to start the the lircd daemon using something like:

        $ lircd --nodaemon --device /dev/lirc0 --driver default
        

Verify the results using irw(1) in another window. Pressing buttons should give something like:

        $ irw
        000000037ff07bef 00 KEY_VOLUMEUP Acer_Aspire_6530G_MCE
        000000037ff07bef 01 KEY_VOLUMEUP Acer_Aspire_6530G_MCE
        000000037ff07bdd 00 KEY_ENTER Acer_Aspire_6530G_MCE
        000000037ff07bdd 02 KEY_ENTER Acer_Aspire_6530G_MCE
        

Once irw works you are done with this step: lirc can convert the button presses to key symbols. The next step is to convert the symbols to configure the systemd service.


Configure systemd

By now you should know the driver and device used when running lircd. Update the configuration file /etc/lirc/lirc_options.conf with the driver and device you have determined:

          [lircd]
          nodaemon        = False
          driver          = default
          device          = /dev/lirc0
          ....
      

You should then be able to start, stop and inspect the service using:

          # systemctl start lircd.socket
          # systemctl stop lircd.socket
          # systemctl status lircd.socket lircd.service
          # journalctl -b 0  /usr/sbin/lircd
      

Check that you can start/stop a working service, irw is your friend. If you are using another init system than systemd, you need to make similar steps.


Converting key symbols to application strings

       |
       v      keysyms                Use irw to debug.
       |
  ---------------
  | LIRC pass 2 |                     ~/.config/lircrc
  ---------------
       |
       |      /var/run/lirc/lircX
       v      config strings
       |                             Use ircat to debug.
       |
  ---------------
  | Application |
  ---------------

Using ~/.config/lircrc, convert the key symbols to application-specific strings.

The first step is to create a simple configuration for just one key for the irexec application, dipping a toe into the water. Create the following file and store it as ~/.config/lircrc:

        begin
            remote = mceusb
            button = KEY_RED
            prog   = irexec
            config = echo "foo"
        end
    

Notes:

With this irexec file in place, we use ircat(1) to check what irexec receives when we push the KEY_RED button:

        $ ./ircat irexec
        echo "foo"
        echo "foo"
        echo "foo"
        ^C
        $
    

So, at this point you can start irexec, and it will do actually echo some "foo" when you press the red button:

        $ ./irexec
        foo
        foo
        ^C
        $
    

With this simple example working, you now need to create complete config files for your application(s). First, you should read .lircrc chapter . Then, create your application config setup in ~/.config/lircrc and test it with ircat as above.

Depending on your application, lirc-config-tool might be able to generate a starting point. i See appendix 5.

Once the application is up, you might want to exploit LIRC's capabilities:


Appendixes

A1: Configuring the kernel

When using the default LIRC IR driver, the kernel IR driver must be configured to send the data only to the /dev/lirc device and not to the general input layer. If not, each button event will delivered twice to the application, both through /var/run/lirc and /dev/input.

As of 0.9.1+ this is configured automatically by lircd, and neither the echo 'lirc' >/sys/class/rc/... nor the protocol udev rule should normally be required.

lircd can run either as root or as a regular user. In the latter case you might need to adjust device permissions.

Also, some lirc drivers conflicts with the kernel drivers. A common example is the lirc atilibusb driver which conflicts with the kernel ati_remote driver. Another example is lirc serial drivers which conflicts with the kernel default tty driver. Such conflicts shows up as dmesg output about not being able to open the involved device, plus various other symptoms.

If required, the default driver configuration can be done using /sys/class/rc interfaces or using a udev rule. Conflicting kernel drivers must be blacklisted. Conflicts on serial ports can be handled by disabling the kernel serial driver for that port.

When using serial or parallel port hardware the proper kernel module must be loaded with correct options. This requires modprobe(1) configurationi.

Using TV-cards requires some extra attention.

Kernel IR driver runtime configuration.

The builtin ir driver subsystem is aware of LIRC, and is capable to send all data through /dev/lirc0. If lircd fails to configure this automatically it can be done manually:

        # echo -- 'lirc' > /sys/class/rc/rc0/protocols
    

Here, 'rc0' is OK if you have only one infrared device. Note that this is not persistent, you need to do this after each boot.

Using '-lirc' instead restores the normal kernel operation when stopping LIRC.

Kernel IR driver udev configuration

Likewise, if lircd fails to configure the kernel IR driver automatically you can create a file /etc/udev/rules.d/99-remote-control-lirc like:

       SUBSYSTEM=="rc", ATTR{protocols}="lirc"
    

This is persistent and makes all ir (i. e., rc-based) devices send data only through /dev/lirc0 where it can be retrieved by the 'default' driver. The file is available in the contrib/ directory.

Kernel module conflicts

When using remotes which are not infrared, the corresponding driver is not affected by the methods above. One example is an RF remote which uses the atilibusb LIRC driver. This conflicts with the ati_remote kernel module, which thus needs to be disabled. Do this by creating the file /etc/modprobe.d/blacklist-atiremote.conf like:

        # Conflicts with LIRC.
        blacklist ati_remote
    

For known cases the lirc-setup tool generates blacklisting configuration files.

The contrib directory contains a file 61-lirc.blacklist-all.conf which blacklists all kernel drivers known to conflict with any lirc plugin. While in most cases an overkill, it can be helpful.

In general, finding out what module to blacklist is not always easy. dmesg(1) sometimes gives a hint about conflicts on a device. Another method is to boot the system without the usb device connected, and do a lsmod. After that, connect the device and make a new lsmod. Comparing the different outputs might give a clue.

Adjusting kernel device permissions

When lircd not runs as root, it needs read and write access to the kernel device it communicates with. Since devices in Linux are handled by udev this is handled by udev rules.

Many drivers including the default driver uses the /dev/lirc or USB devices. In the contrib directory is an example file for the these devices called 60-lirc.rules containing:

        KERNEL=="lirc[0-9]*", SUBSYSTEM=="lirc", GROUP="lirc", MODE="0660"
        ACTION=="add", SUBSYSTEM=="usb", \
           RUN+="/usr/bin/setfacl -m g:lirc:rw $env{DEVNAME}"

The file should be stored in /etc/udev/rules.d/60-lirc.rules This example gives users in the group lirc full permissions to the /dev/lirc0 devices using regular group permissions. It also gives members of the same group access to all USB devices using extended permissions (ACL). It should be simple to adopt to other users (USER=), usernames and devices. Refer to more generic udev docs.

The devinput driver uses the /dev/input/event* devices. These are often accessible for members of a specific group; the best solution is then to add this group the the lircd user's supplementary group e. g., using usermod -aG input lirc which adds the input group to user lirc. See Running as a regular user

Disabling kernel serial port reservation

Usually the default kernel 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.

This needs to be resolved using the setserial(1) tool. An example how to load a lirc_serial module on /dev/ttyS0:

        setserial /dev/ttyS0 uart none
        modprobe lirc_serial

This could be added to lirc_options.conf as a modprobe section e. g.,:

        [modprobe]
        code = setserial /dev/ttyS0 uart none; modprobe lirc_serial

This section is parsed by the lircd-setup tool which runs as root when lircd is started.

lirc-setup can generate this section in many cases.

Debian users should adjust their /etc/serial.conf. Note that lirc_serial probably needs some modprobe setup, see below.

modprobe configuration

The kernel loads the appropriate driver for most modern, USB-based using udev hotplugging - as soon as the device is connected the corresponding kernel module is loaded. However, when using hardware connected to e. g., serial or parallel ports the proper kernel module must be manually loaded. This is done using modprobe(1) options or modprobe.d(5) files. Options to modprobe include things like the actual port, interrupt to use etc.

lirc-setup can generate proper /etc/modprobe.d files in such cases. modinfo(1) also provides useful info. In any case, the proper kernel module must be loaded with correct options before lircd is started.

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, as can be checked using dmesg(1).

A2: Finding the event device

For many tasks it's necessary to find out the event device, something like /dev/input/event12, which is connected to your IR input.

The first try is to invoke mode2 to enumerate the available devices:

        $ mode2 --driver devinput --list-devices
        /dev/input/event11 [0bc7:0006] X10 WTI RF receiver version:  1.10 serial: ?
        /dev/input/by-id/usb-X10_WTI_RF_receiver-event-if00 -> ../event11
        /dev/input/by-path/pci-0000:0b:00.0-usb-0:1:1.0-event -> ../event11
    

With this kind of output all is set: the required device is

/dev/input/event11.

The second try is to invoke ir-keytable(1) without any options:

        $ ir-keytable
        Found /sys/class/rc/rc0/ (/dev/input/event11) with:
            Driver em28xx, table rc-pinnacle-pctv-hd
            Supported protocols: NEC RC-5 RC-6
            Enabled protocols: RC-5
            Extra capabilities: <access denied>
    

If the reported device matches your expectations you're done - here we have /dev/input/event11.

If this doesn't work next try is to look in in /dev/input/by-id. If you find a device here which looks like your device, check where it's linked:

    $ ls /dev/input/by-id
    usb-Plus_More_Enterprise_LTD._USB-compliant_keyboard-event-kbd
    usb-_Home_Infrared_Transceiver_TS0013Yn-event-if00

    $ ls -l /dev/input/by-id/usb-eHome_Infrared_Transceiver_TS0013Yn-event-if00
    lrwxrwxrwx [cut] /dev/input/by-id/usb-eHome_Infrared_Transceiver_TS0013Yn-event-if00 -> ../event13
    

So, here your interface is /dev/input/event13, and your're done.

If this does not work, cat the input devices under /sys.

        $ cat /proc/bus/input/devices > foo
    

Look in foo to find this snippet about your device:

        I: Bus=0003 Vendor=2013 Product=024f Version=0001
        N: Name="em28xx IR (em28174 #0)"
        P: Phys=usb-0000:00:1d.7-1/input0
        S: Sysfs=/devices/pci0000:00/0000:00:1d.7/usb1/1-1/rc/rc0/input14
    

Here, the device is /dev/input/event14.

Testing the device.

The easiest way to test if the correct device is found is to just try to print the data like in

        cat /dev/input/event1

This will print garbage on the terminal when remote buttons are pressed if it is the correct device.

A3: Understanding the driver table

The driver list gives some hints on the usage for each driver. The important columns are "Hardware", "Required LIRC kernel module", "lircd driver" and "Default lircd and lircmd config files".

The "Hardware" column should be obvious. Note that it in many cases it refers to the receiver unit (e. g., the name reported by dmesg), not the name of the remote. So, before looking for a suitable driver use dmesg to find out the name as described in Appendix 2

The "lircd driver" refers to the argument you should give to lircd i. e., --driver=... You might need to check that the driver is available using irrecord -H help. If it's not listed here you need to rebuild lirc which is outside the scope of this document.

The "Required LIRC kernel modules" refers to modules that are part of the linux kernel. Some of these are regular modules and should be available in any reasonably updated linux system. However, some of these modules are part of the staging drivers and might not be available on your system.

To look for a particular module just search for it in /lib/modules e. g.,

        $ find  /lib/modules/$(uname -r) -name lirc_imon\*
        /lib/modules/3.12.7-300.fc20.i686/kernel/drivers/staging/media/lirc/lirc_imon.ko
    

If it's listed, kernel should load it automatically on-demand in most cases. If the module exists but isn't loaded you might need to load it manually using modprobe(1). If it does not exist you have to build the staging drivers, also outside the scope of this document.

The Supported Remotes column reflects what kind of lircd.conf files which are supported. Common values are 'Any' meaning that any file from the website could be used or 'bundled' meaning that the driver requires a specific config file. In some cases any file can be used if it conforms to some limitation.

Unfortunately, the driver list does not provide information on the device which should be used for a particular driver. In some cases there is more info in the driver documentation. Besides this, the only way to be sure is actually inspecting he sources. You might try to search the web before walking this path, though.

A4: Normalizing the lircd.conf

Several of the pre-defined remotes uses non-standard key symbols. This is a Bad Thing, which makes it harder to create the ~/.config/lircrc file in next step. It's also a problem when using the uinput option, or when converting to use the build-in decoding.

You should replace all non-standard definitions with standard key symbols where it's possible. Some buttons might not be possible to map to standard symbols is a sane way, and could be left as-is. But the vast majority of buttons should use standard symbols. The standard symbols a. k. a. the namespace, is listed by irrecord -l.

The script lirc-config-tool helpful here. List all non-standard symbols in lircd.conf:

        $ lirc-config-tool -s -c /etc/lirc/lircd.conf
    

Update the lircd.conf file with standard key symbols as applicable:

        $ sudo lirc-config-tool -u -c /etc/lirc/lircd.conf
    

A5: Generating the .lircrc

The .lircrc file basically combines the remote buttons with application capabilities. To actually write a .lircrc file from scratch is not that hard, but it's a lot of work. lirc-config-tool can save some of this work by creating a starting point. For this to work , the lircd.conf file must be in place. It must also use standard key symbols from the namespaceii as described above.

The first step is to check if your application is supported by the script:

        $ ./lirc-config-tool -l
    

if you find your application here, you can make an .lircrc for that app:

        $ ./lirc-config-tool -o . vlc
    

If you're using the devinput lircd.conf, create a new version of that file which only contains the key symbols you are actually using. Use this instead in the -c option to let lirc-config-tool make it's work. The generated file will look like (excerpt!)


    # Created by /home/al/bin/lirc-config-tool at tis dec  3 23:26:18 CET 2013

    # See http://wiki.videolan.org/How_to_Use_Lirc

        begin
            prog   = vlc
            button = KEY_REWIND
            config = key-rewind
        end

        begin
            prog   = vlc
            button = KEY_FASTFORWARD
            config = key-faster
        end


        begin
            prog   = vlc
            button = KEY_NEXT
            config = key-next
        end

    # Unused buttons:
    #
    #    KEY_HOME
    #    KEY_GREEN
    #    KEY_RED
    #    KEY_YELLOW
    #
    # Unused capabilities:
    #
    #
    #    begin
    #        prog   = vlc
    #        button = KEY_EXIT
    #        config = key-quit
    #    end
    #
    #    begin
    #        prog   = vlc
    #        button = KEY_PLAY_PAUSE.
    #        config = key-play-pause
    #    end
    #
    #    begin
    #        prog   = vlc
    #        button = KEY_PLAY
    #        config = key-play
    #    end
    #
    

The comments are about buttons which havn't found a use, and capabilities in the program (vlc) which are not bound to a button. Obviously, this saves some work.

The lirc-config-tool has a -h and a manpage option for more info.

BEWARE: The configuration file generated this way is a starting point. It needs to be inspected and tweaked before it actually does it's job.

A6 : Addressing changing event devices

When using the devinput driver, input devices like /dev/input/event12 might come up as another device after a reboot. If this becomes a problem, you should address the device using it's name or it's physical bus address.

From 0.9.5, the easy way is to let mode2 enumerate the available devices, something like

        $ mode2 --driver devinput  --list-devices
        /dev/input/event11 [1784:0001] Topseed eHome Infrared Transceiver version:  1.10 serial: TS0013Yn
        /dev/input/by-id/usb-Topseed_eHome_Infrared_Transceiver_TS0013Yn-event-if00 -> ../event11
        /dev/input/by-path/pci-0000:0b:00.0-usb-0:1:1.0-event -> ../event11
    

This lists not only /dev/input/event device but also a link in /dev/input/by-id. If there is only one device of each kind the link is stable after reboots.Handling cases with more than one device of the same kind is best handled by creating udev rules. The output from

mode2 --list-devices

can be used to create such rules.

On 0.9.5- versions the first step is to inspect dmesg after connecting the device. There you should find something like:

    rc0: Media Center Ed. eHome Infrared Remote Transceiver (1784:0001) as
        /devices/pci0000:00/0000:00:12.0/usb4/4-4/4-4:1.0/rc/rc0
    

Here you can see the device's name: "Media center Ed. eHome..." and it's address: ...usb4/4-4/4-4:1.0/rc/rc0.

As long as you have only one remote of each kind you can use simple name matching like in

       --device=name='*eHome*'
    

If you have several devices with the same name you need to use the address instead. Since this depends on how the device is connected, you lose if you disconnect the device and reconnect it to another socket. With this limitation you can use phys=*usb4/4-4/4-4:1.0* in the same way as name. However, in complicated cases like these you might be better off creating a fixed device name using a udev rule

A7 : Running irexec

After having configured lirc, you might want to run irexec(1). Using this, you can bind remote buttons to any command you can run. It's typically used to shut down system, system volume controls etc.

There is two ways to run irexec, both with their pros and cons. It is possible to run irexec either way, or both as parallel services.

The first way is to run irexec as a system daemon. This can be done using a systemd service. This way has security problems since running arbitrary commands and scripts as root is generally a bad idea. There is also the problem that irexec runs outside your session which means it's problematic to access the display, sound system and other resources typically bound to the session. On the other hand, this is flexible and since irexec runs as root it can in the end do anything. As shipped, lircd has a service which can be enabled using systemctl start irexec.service etc. It is configured using /etc/lirc/irexec.lircrc

The second way to run irexec is to run it as a part of the session. The standard way to do this is to drop a irexec.desktop file in the config autostart directory, normally ~/.config/autostart. Doing so you can use your desktop tools to control the service. Also, since the service runs as part of your session, it can access the display, sound system etc.

The drawback is that since it runs as a regular user, it might run into permission problems e. g., when trying to shut down the computer. This can be handled using sudo, giving the user running irexec right to run specific commands otherwise requiring root permission. E. g., the following entry in /etc/sudoers allows the htpc user to restart gdm, effectively making a soft reboot:

        ## Allows members of the htpc group to restart session service
        %htpc ALL=NOPASSWD: /usr/bin/systemctl restart gdm.service
    

All in all, to configure irexec as a session service:

A8 : Using multiple remotes

lirc will happily accept several lircd.conf files. When doing so, it will try to match input with each configuration until there is a match. This means that the number of configurations has some limits, otherwise it would take too long time. For practical scenarios say 2-4 remotes this shouldn't really be a problem on modern hardware. There are a number of ways to combine several configurations:

When using multiple remotes lircd tries to sort them so that the ones which decodes faster are used first. Normally you could use this feature as-is. However, if you want to define the order yourself you should set the attribute manual_sort to 1 in any of the configs. Doing so disables the automatic sorting.

In manual sort mode the remotes are used in the order they appear in the config file. Files in lircd.conf.d are used in order defined by the filenames. The recommended way to use this is to name the links to 00-my_first_remote.conf, 01-next-remote.conf etc.

To add the manual_sort attribute to an existing remote is actually a bad idea since it creates cross-dependencies between configurations. A cleaner way is to add a dummy remote like this in lircd.conf.d (the name does not matter):

        begin remote
            name manual_sort
            manual_sort 1
            begin codes
            end codes
        end remote

A9 : Using multiple capture devices

When using using multiple capture devices e. g., two different USB dongles you need to create a separate lircd instance for each device. Setup the first device according to the main flow in this document, then add the second as documented below.

Also, when using multiple capture devices you might run into trouble with several /dev/lirc* devices e. g., /dev/lirc0 and /dev/lirc1. Since udev does not guarantee in which order devices are created, you cannot know which physical device /dev/lirc0 refers to is in this scenario. To handle this you need to define udev rules defining fixed device names.

If running multiple input capture devices you need to connect them using the --listen and --connect options.

Setup a new lircd instance.

To create a new lircd instance serving a separate capture device create a file like /etc/systemd/system/lircd-lirc1.service:

        [Unit]
        Description=LIRC instance on /dev/lirc1
        After=network.target

        [Service]
        Type=simple
        ExecStart=/usr/sbin/lircd --driver=default \
                                  --device=/dev/lirc1 \
                                  --output=/var/run/lirc/lircd-lirc1 \
                                  --pidfile=/run/lirc/dont-use-lirc1.pid \
                                  --nodaemon

        [Install]
        WantedBy=multi-user.target

This will create a new service called lircd-lirc1.service which can be started using # systemd start lircd-lirc1.service etc. Options not defined in the service file will default to the values in lirc_options.conf. Each instance must have unique --device, --output and --pidfile options.

Udev rules handling multiple /dev/lirc* devices.

Udev can be used to define fixed device names which can be used instead of the random /dev/lirc[0-9] devices set up by default. To do this, you need to define udev rules. As an example, a file /etc/udev/rules.d/80-lirc.rules like:

    SUBSYSTEM=="lirc", KERNEL=="lirc*",  DRIVERS=="mceusb", \
    SYMLINK+="lirc-mce"

will create a new device called /dev/lirc-mce which will be connected to a kernel device using the mceusb driver.

Practically, each installation will need to match other attributes depending on the hardware. The command

        # udevadm info --attribute-walk \
        --path $(udevadm info --query path --name=/dev/lirc1)

will list the possible attributes to match for a given /dev/lirc* device.

Creating udev rules is a large topic. Please refer to more generic information to resolve problems.

Connecting several input capture devices.

For each device you want to use you have to setup 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 e. g., look like this:

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

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 add more host:port items to the last lircd instance's --connect option. 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, use irw providing the according socket interface on the command line:

> irw /var/run/lirc/lircd1

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. Resolving this requires recompiling the kernel drivers with different names and device numbers. Lifting this limitation is one of the todo items for future releases.

A10 : Configuration files

The lirc configuration is mostly done in the lirc config directory, usually /etc/lirc. Besides this, there are occasionally needs to configure the kernel drivers using files in /etc/modprobe.d.

           /etc
            |
            |
            |---lirc
            |     |
            |     |-----------  lirc_options.conf
            |     |
            |     |-----------  lircrc
            |     |
            |     |-----------  lircd.conf
            |     |
            |     |-----------  lircd.conf.d
            |                       |
            |                       |------- remote1.lircd.conf
            |                       |
            |                       |------- remote2.lircd.conf
            |
            |---modprobe.d
                    |
                    | --------- blacklist-xxx.conf
                    |
                    | ----------options-xxx.conf

         $HOME
           |
           |----.config
                    |
                    |-----------lircrc
     

The files:

A11 : Using home-brew hardware

The LIRC project began as an attempt to create drivers for home-brew hardware. Some links to build such:

Using home-brew hardware in many cases means using the lirc_serial or lirc_parallel driver. These drivers needs configuration such as I/O base address and IRQ. This is done using modprobe, using command line parameters to modprobe(1) or adding files to the modprobe.d(5) directory. The modinfo(1) command provides useful info how to configure the drivers.

If there is no output when testing with mode2, there are some things to check:

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.

There is also a hardware-related section in the FAQ

A14 : Running lircd as a regular user

Traditionally lircd has been run as user root. However, this raises both stability and security concerns, so running as a regular user is the preferred option. In the following its assumed that this user is called lirc and it's group also is named lirc.

There are two ways to run as a regular user. One is to patch the lircd.service file so the services started as the lirc user. The other is to use the --effective-user option. In this mode, lircd is started as root but drops privileges before actually processing infrared data.

Since lircd repeatedly opens/closes the input device, it always needs write access to it. This can be achieved using group rights and/or udev rules.

In the general case the lirc user should be member of groups owning tty locks, the /dev/input devices and the serial devices. Examples includes the groups lock, input and dialout but ultimately depends on the distribution.

Devices Usage Example group
/dev/lirc* /sys/class/rc devices lirc (see udev rule below)
/dev/ttyS* Serial ports dialout
/dev/input/event[0-9]* Event devices input
/var/lock or /var/lock/lockdev Old style serial locks lock

Some devices are created as accessible only by root. This includes the often used /dev/lirc? and the USB devices. These should be made accessible using udev rules. The contrib/ directory contains an example rule 60-lirc.rules. This sets up the /dev/lirc* devices to be accessible for the lirc group using regular group permissions. It also grants r/w access for the lirc group to USB devices using ACLs.

If there is a need to run setup code as root the lirc_options.conf file supports a section modinit which e. g., might look like

             [modinit]
             code = setserial /dev/ttyS0 uart none; modprobe lirc-serial

The lircd-setup script which by default is run before the lircd service runs this setup code as root. The code is ordinary shell commands.