Documentation/admin-guide/media/remote-controller.rst

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