1Infrared remote control support in video4linux drivers
2======================================================
3
4Authors: Gerd Hoffmann, Mauro Carvalho Chehab
5
6Basics
7------
8
9Most analog and digital TV boards support remote controllers. Several of
10them have a microprocessor that receives the IR carriers, convert into
11pulse/space sequences and then to scan codes, returning such codes to
12userspace ("scancode mode"). Other boards return just the pulse/space
13sequences ("raw mode").
14
15The support for remote controller in scancode mode is provided by the
16standard Linux input layer. The support for raw mode is provided via LIRC.
17
18In order to check the support and test it, it is suggested to download
19the `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_. It provides
20two tools to handle remote controllers:
21
22- ir-keytable: provides a way to query the remote controller, list the
23  protocols it supports, enable in-kernel support for IR decoder or
24  switch the protocol and to test the reception of scan codes;
25
26- ir-ctl: provide tools to handle remote controllers that support raw mode
27  via LIRC interface.
28
29Usually, the remote controller module is auto-loaded when the TV card is
30detected. However, for a few devices, you need to manually load the
31ir-kbd-i2c module.
32
33How it works
34------------
35
36The modules register the remote as keyboard within the linux input
37layer, i.e. you'll see the keys of the remote as normal key strokes
38(if CONFIG_INPUT_KEYBOARD is enabled).
39
40Using the event devices (CONFIG_INPUT_EVDEV) it is possible for
41applications to access the remote via /dev/input/event<n> devices.
42The udev/systemd will automatically create the devices. If you install
43the `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_, it may also
44automatically load a different keytable than the default one. Please see
45`v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ ir-keytable.1
46man page for details.
47
48The ir-keytable tool is nice for trouble shooting, i.e. to check
49whenever the input device is really present, which of the devices it
50is, check whenever pressing keys on the remote actually generates
51events and the like.  You can also use any other input utility that changes
52the keymaps, like the input kbd utility.
53
54
55Using with lircd
56================
57
58The latest versions of the lircd daemon supports reading events from the
59linux input layer (via event device). It also supports receiving IR codes
60in lirc mode.
61
62
63Using without lircd
64===================
65
66Xorg recognizes several IR keycodes that have its numerical value lower
67than 247. With the advent of Wayland, the input driver got updated too,
68and should now accept all keycodes. Yet, you may want to just reasign
69the keycodes to something that your favorite media application likes.
70
71This can be done by setting
72`v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ to load your own
73keytable in runtime. Please read  ir-keytable.1 man page for details.
74