User Tools

  • (equal to forum credentials)

Site Tools


Configuring a Remote

For all users that have remotes that don't or only partially work, here is a guide on how to map your specific device. These steps don’t include the loading of the necessary kernel modules and specific LIRC hardware.conf configuration. If you have followed the guide below but your remote still does not work, please ask for help on the forum.

Step 1: Is Your Remote Recognized?

Verify that your remote is recognized by LIRC:

xbian@xbian:~# sudo su
root@xbian:~# /etc/init.d/lirc stop
root@xbian:~# mode2
space 989187
pulse 2650
space 894
pulse 467
space 413
pulse 475
space 387
pulse 475
space 866
pulse 483
space 835
pulse 1364

If mode2 doesn’t output anything, then your remote isn’t recognized by the system. Ask for support so we can figure out what the right hardware.conf should be.

If you use GPIO on the Raspberry Pi, add “lirc_rpi gpio_in_pin=#” to /etc/modules. (Replace # with your input pin.) Also, move and rename /etc/lirc/hardware/lirc_rpi.conf to /etc/lirc/hardware.conf.

Step 2 - Check If LIRC Recognized the Buttons of Your Remote

Start irw and check if it generates output when you press a button on your remote.

root@xbian:~# /etc/init.d/lirc start
root@xbian:~# irw
000000037ff07be1 00 KEY_ARROWUP logitech-harmony-300i
000000037ff07be1 01 KEY_ARROWUP logitech-harmony-300i
000000037ff07be1 02 KEY_ARROWUP logitech-harmony-300i

If all buttons are recognized by LIRC, go directly to Step 4. If some or none of the buttons are recognized, go to Step 3a.

Step 3 - Mapping Your Remote

Step 3a - Check Online to Determine If Your Remote is Already Mapped

Lets say we have a Microsoft XBOX remote.

Go to Look for Microsoft. Then open that folder. There we see three files named XBOX:

  • Xbox
  • Xbox360

Open those files and paste the contents at the end of /etc/lirc/lircd.conf.

Restart LIRC:

root@xbian:~# /etc/init.d/lirc restart

Now recheck if Step 2 generates output. If it does, go to Step 4. If not, then remove the old settings from /etc/lirc/lircd.conf and try one of the other configuration files by repeating step 3a.

If none of these configuration files work, then go to step 3b.

Step 3b - Create a Custom LIRC Config

If no configuration file exists, create a custom one.

One important step for creating a custom LIRC map is that you give logical names to each button. Those names are uniform among remotes.

For that purpose LIRC has create ‘namespaces’. A list of namespaces can be found here or by running:

$ irrecord --list-namespace

Creating a custom LIRC map is done by using irrecord:

root@xbian:~# irrecord /home/xbian/remote.conf

irrecord is pretty verbose so just carefully follow all steps. When you’re done, you will end up with a custom LIRC map for your specific remote in /home/xbian/remote.conf.

Edit this file (/home/xbian/remote.conf) and look for the parameter name. This should say

name /home/xbian/remote.conf

Change this name to the name of your remote e.g.:

name Xbox_Remote

The file should now look similar to this:

begin remote

name Xbox_Remote
bits            8
eps            30
aeps          100

one             0     0
zero            0     0
gap          163983
toggle_bit_mask 0x0

begin codes
left                     0xA9
up                       0xA6
right                    0xA8
down                     0xA7
enter                    0x0B

Now close the new file and append its content to the lircd.conf and start LIRC:

root@xbian:~# cat /home/xbian/remote.conf >> /etc/lirc/lircd.conf
root@xbian:~# /etc/init.d/lircd start

Now repeat Step 2 to check if all buttons of your remote are recognized.

If you miss some buttons, simply redo Step 3b. However, remember to first remove the old config from /etc/lirc/lircd.conf.

If all buttons are recognized by LIRC, go to Step 4.

Step 4 - Create a XBMC lircmap

Create a map that maps the buttons of your remote to XBMC functions.

To do this, create a new file (if it doesn’t already exist):

root@xbian:~# nano /home/xbian/.xbmc/userdata/Lircmap.xml

The content of this file should look similar to this:

<remote device="logitech-harmony-300i">

This file contains three important aspects. All this information can be extracted from the irw output in step 2:

root@xbian:~# irw
000000037ff07be1 00 KEY_ARROWUP logitech-harmony-300i
000000037ff07be1 01 KEY_ARROWUP logitech-harmony-300i
000000037ff07be1 02 KEY_ARROWUP logitech-harmony-300i

The name of your remote, in this case “logitech-harmony-300i”.

<remote device="logitech-harmony-300i">
Make sure this device is the same as the name in your lircd.conf you just made or the irw output.

The second and third aspects are the name of the LIRC button and the make of the XBMC command:

You saw in step 2 that one of my LIRC buttons is called KEY_ARROWUP. In this case KEY_ARROWUP is linked to the XBMC command up.

A full list of all commands XBMC understands can be found in /usr/local/share/xbmc/system/keymaps/remote.xml. The top of this file looks like this:

As you can see, the up is obviously connected to Up. A more interesting example:


This means that KEY_YELLOW from my logitech-remote-300i is linked to the green command of XBMC.


The green command is linked to the internal command XBMC.ActivateWindow(MyVideos). This means that when I push the yellow button of my remote, the MyVideos window is opened.

Now create a Lircmap.xml for all buttons of your remote. When to want to test your config, start XBMC again.

root@xbian:~# service xbmc start
Whenever you change something in your the config files, restart XBMC to let the changes take effect:
root@xbian:~# service xbmc restart

Step 5 - Share Your Remote Config With Us

When you have created a custom lircd.conf + Lircmap.xml that has a generic functionality, please share them with us by mailing these two files to We will include them in our default XBian releases.

Please remember to only change lircd.conf and Lircmap.xml. Also provide your (nick)name and email address in case users have questions.

If you have followed all steps above but your remote does not work: please ask for help at the forum.

Additional Note: If XBMC responds to LIRC after:

root@xbian:~# service xbmc restart
but not on system reboot, you may have a problem with XBMC starting too quickly on boot.

One solution too this is to edit the 4th line of /etc/init/xbmc-preload.conf to read:

start on stopping mountall and started networking and net-device-up wlan0

This only applies to a network-enabled setup. Change wlan0 to eth0 if you use Ethernet.

Known issue with lirc remotes and Kodi: If you press a button on your remote once and the command is executed twice, follow the instructions here:

remotes.txt · Last modified: 2016/02/05 09:38 by jvig