Infra-Red Remotes

Introduction

Modern Linux kernels (used in LibreELEC) have built-in support for IR remotes. IR signals are decoded by the kernel and programs see button presses from IR remotes in the same way as key presses from a normal keyboard, as Linux input events. This approach is the successor to LIRC where a separate program, lircd, decodes IR signals and programs obtain button presses from a socket as LIRC events.

While this new scheme is really handy, there's a small gotcha: Kodi's remote handling is built for LIRC and it doesn't cope well with Linux input events. In general all buttons also present on a normal keyboard, like arrows and numbers, work fine but rather important buttons like OK and channel up/down don't. To solve this LibreELEC runs eventlircd in the background to translate Linux input events into LIRC events. So "under the hood" the new scheme is being used, but remote buttons still show up as LIRC events in Kodi.

Kodi translates the received LIRC events to Kodi button names via Lircmap.xml and then buttons are mapped to Kodi actions via remote.xml and keyboard.xml files. This wiki page describes the LibreELEC configuration. Information on Kodi configuration is available in the Kodi LIRC and Kodi Keyboard.xml wiki pages.

LibreELEC still ships with LIRC so IR remotes with non-standard protocols and rather special setups can be supported. In general, use LIRC only in exceptional cases where you actually need it.

Note that LIRC requires compatible hardware to decode IR signals. An in-depth discussion of IR decoder hardware is outside the scope of this document. On a Raspberry Pi, LibreELEC can use the GPIO pins to communicate with a hardware IR receiver diode, as long as config.txt has been suitably modified to enable GPIO support.

Configuration

Like most current Linux distros LibreELEC uses ir-keytable to configure Infra-Red Remotes. Each IR receiver kernel driver installs a default keytable which specifies the IR protocol to use, e.g. RC5, RC6, NEC, and the scancode to Linux keycode mappings.

Most universal receivers work with the rc-rc6-mce table so RC6 MCE remotes can be used without further configuration. Drivers for DVB devices sold with a remote usually install their own keytable, e.g. the Hauppauge remote that came with a Hauppauge DVB stick.

After the kernel driver is loaded ir-keytable -a is automatically run to change the kernel default configuration. First /etc/rc_maps.cfg determines which keytable to load. Then the corresponding keytable file from /usr/lib/udev/rc_keymaps is used to configure the remote control driver.

As most of the LibreELEC filesystem is read-only, we use a system of boot-time file overrides to read user-created configuration from the persistent /storage area:

  • /storage/.config/rc_maps.cfg overrides /etc/rc_maps.cfg

  • /storage/.config/rc_maps.cfg.sample has simple examples

  • /storage/.config/rc_keymaps overrides /usr/lib/udev/rc_keymaps

  • /etc/rc_maps.cfg uses the libreelec_multi keytable instead of rc6_mce

The default libreelec_multi keytable allows us to support Xbox 360/One remotes "out of box" in addition to MCE/RC6 remotes. This is configured via the following change:

# use combined multi-table on MCE receivers
#*      rc-rc6-mce               rc6_mce
*       rc-rc6-mce               libreelec_multi

Can I use?

While most IR receivers can be used with a large variety of remotes the answer to “Can I use remote X with IR receiver Y?” depends on many factors:

  • Some IR receivers cannot be configured and you can only use the remote they came with.

  • Some receivers only support a subset of protocols, e.g. only RC5, not RC6.

  • If a remote uses a protocol not supported by the IR receiver, or a protocol not supported by the Linux kernel, the last option is the RAW (lirc) protocol which allows userspace LIRC to configure it via a custom lirc.conf file.

Configuration (Basic)

LibreELEC includes 100+ remote keytable files included with the upstream Linux kernel so there is a good chance your remote has a known configuration, or a partially working keytable that can be used as a starting point for adding the missing buttons (see the "Advanced" section).

  1. Look at the keytable files in /usr/lib/udev/rc_keymaps/.

  2. If one of the filenames suggests it could match your remote, try using it.

  3. If it doesn't work, keep trying..

To test a different keytable file run ir-keytable -c -w /path/to/keytable-file e.g.

LibreELEC:~ # ir-keytable -c -w /usr/lib/udev/rc_keymaps/samsung
Read samsung table
Old keytable cleared
Wrote 30 keycode(s) to driver
Protocols changed to nec

If the output ends with these lines the protocol is not supported by the IR receiver:

Invalid protocols selected
Couldn't change the IR protocols

If the keytable loaded without errors press the up, down, left, right and OK buttons to see if navigation in Kodi works?

If you find a working keytable file the config can be made persistent by creating /storage/.config/rc_maps.cfg with the name of the keytable, e.g. if the samsung keytable works the file with the following content:

* * samsung

Running ir-keytable -a /storage/.config/rc_maps.cfg and the output should look like:

LibreELEC:~ # ir-keytable -a /storage/.config/rc_maps.cfg
Old keytable cleared
Wrote 30 keycode(s) to driver
Protocols changed to nec

Test the buttons work again, and if all is okay, reboot.

Configuration (Advanced)

If you cannot find a working keymap or the current keymap has missing buttons you can create your own. Since LibreELEC 10.x the keytable file is plain text file in toml markup format. The first section describes the name of the keymap (free text, but avoid special characters and spaces) and the remote protocol and variant. This is followed by lines that map the remote scancode to a Linux keycode. A typical keytable file in toml format looks like this:

[[protocols]]
name = "khadas"
protocol = "nec"
variant = "nec"
[protocols.scancodes]
0x14 = "KEY_POWER"
0x03 = "KEY_UP"
0x02 = "KEY_DOWN"
0x0e = "KEY_LEFT"
0x1a = "KEY_RIGHT"
0x07 = "KEY_OK"
0x01 = "KEY_BACK"
0x5b = "KEY_MUTE"
0x13 = "KEY_MENU"
0x58 = "KEY_VOLUMEDOWN"
0x0b = "KEY_VOLUMEUP"
0x48 = "KEY_HOME"

Older LibreELEC releases (v7.x to v9.x) use a older plain text format not toml which can be seen in the existing keymaps in /usr/lib/udev/rc_keymaps.

To capture the keycodes you must stop Kodi and eventlircd first, or these services capture IR input and you will see no output from ir-keytable:

systemctl stop kodi
systemctl stop eventlircd

Next we have to identify the IR protocol. If you found a partially working keytable file (with the protocol listed in the header) you can skip this step. First we run ir-keytable to find out which protocols the receiver driver supports. Look at the Supported protocols: line, e.g.

LibreELEC:~ # ir-keytable
Found /sys/class/rc/rc0/ (/dev/input/event1) with:
        Driver gpio-rc-recv, table rc-rc6-mce
        Supported protocols: lirc rc-5 rc-5-sz jvc sony nec sanyo mce_kbd rc-6 sharp xmp
        Enabled protocols: lirc nec rc-6
        Name: gpio_ir_recv
        bus: 25, vendor/product: 0001:0001, version: 0x0100
        Repeat delay = 500 ms, repeat period = 125 ms

Run ir-keytable -p PROTOCOL -t and press buttons on the remote. If you discover the correct protocol you will see EV_MSC events and the scancode of the button pressed, e.g.

LibreELEC:~ # ir-keytable -p rc-5 -t
Protocols changed to rc-5
Testing events. Please, press CTRL-C to abort.
1503592437.660155: event type EV_MSC(0x04): scancode = 0x101a
1503592437.660155: event type EV_SYN(0x00).
1503592437.774129: event type EV_MSC(0x04): scancode = 0x101a
1503592437.774129: event type EV_SYN(0x00).
1503592437.921009: event type EV_MSC(0x04): scancode = 0x101a

If you see no events stop ir-keytable with CTRL-C and try another protocol from the list. You can ignore lirc as this is not a real protocol.

Once you find the correct IR protocol create /storage/.config/rc_keymaps/custom_remote and set the header file. In the example above the protocol is rc-5 so we set:

# table custom_remote, type: rc-5

If you found a partially working keytable, clone it and then edit the header to say custom_remote:

cp /usr/lib/udev/rc_keymaps/samsung /storage/.config/rc_keymaps/custom_remote

Next we capture the scancodes and document the keycode mapping. Some users find it easiest to open two SSH connections; one to see ir-keytable scancode output in, and one so they can copy/paste scancodes directly into the custom_remote keytable file, e.g. in one open the nano editor:

nano /storage/.config/rc_keymaps/custom_remote

And in the second run ir-keytable -t to find out the scancode of each button. For each button do the following:

  • Press a button and note the scancode (the 0x… value after scancode:)

  • Add a new line with the scancode (including 0x).

  • Add the Linux keycode in "quoted" format and separated with a blank.

You can get a list of all supported Linux keycodes via irrecord -l | grep ^KEY but it is easiest to use keycodes listed in the <remote device=“devinput”> section of /usr/share/kodi/system/Lircmap.xml else you must also create a Kodi lircmap.xml with Linux keycode to action mappings.

The table below has a selection of common keycodes:

Keycode
Keycode
Keycode
Keycode

KEY_LEFT

KEY_STOPCD

KEY_INFO

KEY_TEXT

KEY_RIGHT

KEY_FASTFORWARD

KEY_PROPS

KEY_1

KEY_UP

KEY_FORWARD

KEY_ZOOM

KEY_2

KEY_DOWN

KEY_REWIND

KEY_ANGLE

KEY_3

KEY_OK

KEY_VOLUMEUP

KEY_MUTE

KEY_4

KEY_ENTER

KEY_VOLUMEDOWN

KEY_POWER

KEY_5

KEY_SELECT

KEY_CHANNELUP

KEY_SLEEP

KEY_6

KEY_DELETE

KEY_CHANNELDOWN

KEY_WAKEUP

KEY_7

KEY_ESC

KEY_PAGEUP

KEY_EJECTCD

KEY_8

KEY_MEDIA

KEY_PAGEDOWN

KEY_EJECTCLOSECD

KEY_9

KEY_HOME

KEY_NEXT

KEY_DVD

KEY_0

KEY_EXIT

KEY_NEXTSONG

KEY_MENU

KEY_NUMERIC_STAR

KEY_BACK

KEY_PREVIOUS

KEY_VIDEO

KEY_NUMERIC_POUND

KEY_BACKSPACE

KEY_PREVIOUSSONG

KEY_AUDIO

KEY_RED

KEY_ESC

KEY_EPG

KEY_MP3

KEY_GREEN

KEY_RECORD

KEY_TITLE

KEY_CAMERA

KEY_BLUE

KEY_PLAY

KEY_TV2

KEY_IMAGES

KEY PVR

KEY_PLAYPAUSE

KEY_CONTEXT_MENU

KEY_TUNER

KEY_RADIO

KEY_PAUSE

KEY_SUBTITLE

KEY_TV

KEY_STOP

KEY_LANGUAGE

KEY_PVR

Once you are finished with the keytable, save the file, stop ir-keytable -t with CTRL-C and then restart it with the keytable file:

LibreELEC:~ # ir-keytable -c -w /storage/.config/rc_keymaps/custom_remote
Read justboom table
Old keytable cleared
Wrote 12 keycode(s) to driver
Protocols changed to rc-5

Now run ir-keytable -t and press buttons. In addition to EV_MSC scancode events you should now see EV_KEY events, e.g.

LibreELEC:~ # ir-keytable -t
Testing events. Please, press CTRL-C to abort.
1503599395.150849: event type EV_MSC(0x04): scancode = 0x1019
1503599395.150849: event type EV_KEY(0x01) key_down: KEY_VOLUMEUP(0x0073)
1503599395.150849: event type EV_SYN(0x00).
1503599395.264827: event type EV_MSC(0x04): scancode = 0x1019
1503599395.264827: event type EV_SYN(0x00).
1503599395.413668: event type EV_MSC(0x04): scancode = 0x1019
1503599395.413668: event type EV_SYN(0x00).
1503599395.673626: event type EV_KEY(0x01) key_up: KEY_VOLUMEUP(0x0073)
1503599395.673626: event type EV_SYN(0x00).

If the test is successful, make the keytable persistent by creating /storage/.config/rc_maps.cfg with the following content:

* * custom_remote

Reboot and you should have a working remote in Kodi.

Troubleshooting

Check the obvious. Batteries run down and either stop the remote from working or reduce the working range. Try using the remote in-front of the receiver. You can also try pointing the IR transmitter at the sensor of a digital camera or smartphone in a dark room. If the IR transmitter works you should see it light up the camera/smartphone screen.

If the remote is sending signals, there are several steps until a button press on your remote triggers an action in Kodi. Use this guide to check each step and trace the problem:

To check if the IR receiver driver is loaded run ir-keytable. If you see the error message /sys/class/rc/: No such file or directory no driver is loaded.

To check if the IR receiver is receiving any signals, see if ir-keytable shows lirc as a supported protocol. If yes, run ir-ctl -r to show raw, undecoded signals from the receiver. If IR reception works you will see lots of pulse and space lines when pressing a button. Note: On kernels before 4.3 lirc may be listed in Supported protocols but not in Enabled protocols. In this case run ir-keytable -p lirc to enable it first (remembering this will disable other decoders).

To check if lircd is running run ir-keytable. If only lirc shows up in Enabled protocols: lircd is running. When it starts it disables all other protocols). You can also run ps | grep /usr/sbin/lircd to check for /usr/sbin/lircd and /usr/sbin/lircd-uinput processes. If you see them LIRC enabled. If LIRC is enabled, disable it in LibreELEC Settings > Services and reboot.

To check if the correct keytable is loaded run ir-keytable -r to show the current keytable and protocol. Compare this to the header in /storage/.config/rc_keymaps/custom_remote and check /storage/.config/rc_maps.cfg references the correct keytable name.

To check if IR decoding works correctly stop Kodi and eventlircd:

systemctl stop kodi
systemctl stop eventlircd

Then run ir-keytable -t and press buttons on the remote. You should see EV_MSC events with the scancode and EV_KEY events with the Linux keycode, e.g.

LibreELEC:~ # ir-keytable -t
Testing events. Please, press CTRL-C to abort.
1503599395.150849: event type EV_MSC(0x04): scancode = 0x1019
1503599395.150849: event type EV_KEY(0x01) key_down: KEY_VOLUMEUP(0x0073)

If you only get EV_MSC but no EV_KEY events, verify if the correct keytable is configured.

After this test, restart eventlircd and Kodi (or reboot):

systemctl start eventlircd
systemctl start kodi

To check if eventlircd translates the input events to LIRC events run irw to show the translated LIRC events Kodi sees. When pressing a button you should see messages like this:

LibreELEC:~ # irw
72 0 KEY_VOLUMEDOWN devinput
72 1 KEY_VOLUMEDOWN devinput
72 2 KEY_VOLUMEDOWN devinput

To check if Kodi receives the translated LIRC events enable debug logging in System Settings > Logging then watch the logfile:

tail -f /storage/.kodi/temp/kodi.log

When you press a button you should see log entries with LIRC: Update like this:

21:55:33.891 T:1945866240   DEBUG: LIRC: Update - NEW at 60659:6c 0 KEY_DOWN devinput (KEY_DOWN)
21:55:33.891 T:1945866240   DEBUG: OnKey: 167 (0xa7, obc88) pressed, action is Down

The LIRC line indicates Kodi received the LIRC event. The OnKey: line shows the action generated after applying Lircmap.xml and remote.xml. If you see LIRC lines but incorrect actions, check your Kodi Lircmap.xml and remote.xml config files are correct.

Known Issues

USB data transfers can interfere with GPIO IR receivers on Raspberry Pi 0/1/2/3 hardware, and since Ethernet is internally connected via USB playing large movies from a NAS can exhibit the problem. This is a known issue: see this forum post for details and there is nothing we can do. Common workarounds are to use a USB IR receiver like Flirc or CEC.

LIRC Support

Most remotes are now supported by the Linux kernel but "LIRC" (the userspace lircd daemon and tools) is still useful for handling unusual remotes with odd protocols and no kernel drivers. Since LibreELEC 8.2.0 LIRC is disabled by default, but can be enabled in LibreELEC Settings > Services > Lirc. Configuration is handled in (almost) the same way as most desktop Linux distros:

  • The /etc/lirc/lirc_options.conf file configures the default LIRC driver and /dev/lirc0.

  • The /etc/lirc/lircd.conf file includes remote configs for MCE, Xbox 360, Xbox One, and a few others.

The embedded files can be overridden at boot time by creating /storage/.config/lircd.conf and /storage/.config/lirc_options.conf with needed changes.

In LibreELEC lircd-uinput reads decoded LIRC events from /run/lirc/lircd.socket and translates these to Linux input events via the Linux uinput driver. The Linux input events from lircd-uinput are then picked up by eventlircd and fed to Kodi as LIRC events via the /run/lirc/lircd socket.

It might seem odd to translate between LIRC, Linux input and (again) LIRC events, but Kodi can only receive LIRC events on a single LIRC socket, and this allows eventlircd to collect all remote events and feed them to Kodi so we can support LIRC-decoded and kernel-decoded remotes without needing user input or complex scripts to change the configuration.

To use LIRC with an IR receiver that supports in-kernel decoding it's best to disable ir-keytable auto configuration with an empty rc_maps.cfg file:

touch /storage/.config/rc_maps.cfg

Although lircd disables all remote protocols (and thus in-kernel decoding) on startup ir-keytable auto-configuration runs in parallel, and if it happens to run after lircd starts it can re-enable in-kernel decoding. This causes duplicate decoding as both lircd and kernel will receive and process the IR signals. This issue is often intermittent since it depends on the timing of lircd start. Sometimes lircd will run after ir-keytable and in-kernel decoding is disabled as expected.

Note: If you stop or disable LIRC in LibreELEC Settings you will need too reboot or set ir-keytable manually from the SSH console. Disabling LIRC does not automatically re-enable in-kernel decoding.

Apple IR Remotes

Older LibreELEC releases used atvclient to support the Apple IR sensor and send LIRC events to Kodi. Since 9.2.0 we use the native Linux kernel driver for the IR sensor, which sends normal HID events. Create a custom keymap in /storage/.kodi/userdata/keymaps/keymap.xml with the following content to map a White or Silver remote:

<keymap>
    <global>
        <keyboard>
            <browser_back>Left</browser_back>
            <browser_forward>Right</browser_forward>
            <volume_up>Up</volume_up>
            <volume_down>Down</volume_down>
            <key id="61952">Back</key>
        </keyboard>
    </global>
    <Visualisation>
        <keyboard>
            <volume_up>VolumeUp</volume_up>
            <volume_down>VolumeDown</volume_down>
        </keyboard>
    </Visualisation>
    <FullscreenVideo>
        <keyboard>
            <volume_up>VolumeUp</volume_up>
            <volume_down>VolumeDown</volume_down>
        </keyboard>
    </FullscreenVideo>
</keymap>
PreviousHyperionNextLCDProc

Last updated