1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
9 LIRC stands for Linux Infrared Remote Control. The LIRC device interface is
10 a bi-directional interface for transporting raw IR and decoded scancodes
11 data between userspace and kernelspace. Fundamentally, it is just a chardev
12 (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct
13 file_operations defined on it. With respect to transporting raw IR and
14 decoded scancodes to and fro, the essential fops are read, write and ioctl.
16 It is also possible to attach a BPF program to a LIRC device for decoding
17 raw IR into scancodes.
19 Example dmesg output upon a driver registering w/LIRC:
23 $ dmesg |grep lirc_dev
24 rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter
26 What you should see for a chardev:
31 crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
33 Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_
34 contains tools for working with LIRC devices:
36 - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC
39 - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load
40 BPF IR decoders and test IR decoding. Some BPF IR decoders are also
49 LIRC supports some modes of receiving and sending IR codes, as shown
50 on the following table.
52 .. _lirc-mode-scancode:
53 .. _lirc-scancode-flag-toggle:
54 .. _lirc-scancode-flag-repeat:
56 ``LIRC_MODE_SCANCODE``
58 This mode is for both sending and receiving IR.
60 For transmitting (aka sending), create a struct lirc_scancode with
61 the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
62 set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other
63 members set to 0. Write this struct to the lirc device.
65 For receiving, you read struct lirc_scancode from the LIRC device.
66 The ``scancode`` field is set to the received scancode and the
67 :ref:`IR protocol <Remote_controllers_Protocols>` is set in
68 :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
69 in the ``keycode`` field, else it is set to ``KEY_RESERVED``.
71 The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle
72 bit is set in protocols that support it (e.g. rc-5 and rc-6), or
73 ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols
74 that support it (e.g. nec).
76 In the Sanyo and NEC protocol, if you hold a button on remote, rather than
77 repeating the entire scancode, the remote sends a shorter message with
78 no scancode, which just means button is held, a "repeat". When this is
79 received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and
82 With nec, there is no way to distinguish "button hold" from "repeatedly
83 pressing the same button". The rc-5 and rc-6 protocols have a toggle bit.
84 When a button is released and pressed again, the toggle bit is inverted.
85 If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set.
87 The ``timestamp`` field is filled with the time nanoseconds
88 (in ``CLOCK_MONOTONIC``) when the scancode was decoded.
94 The driver returns a sequence of pulse and space codes to userspace,
95 as a series of u32 values.
97 This mode is used only for IR receive.
99 The upper 8 bits determine the packet type, and the lower 24 bits
100 the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
101 the macro ``LIRC_MODE2()`` will give you the type, which
106 Signifies the presence of IR in microseconds, also known as *flash*.
110 Signifies absence of IR in microseconds, also known as *gap*.
112 ``LIRC_MODE2_FREQUENCY``
114 If measurement of the carrier frequency was enabled with
115 :ref:`lirc_set_measure_carrier_mode` then this packet gives you
116 the carrier frequency in Hertz.
118 ``LIRC_MODE2_TIMEOUT``
120 When the timeout set with :ref:`lirc_set_rec_timeout` expires due
121 to no IR being detected, this packet will be sent, with the number
122 of microseconds with no IR.
124 ``LIRC_MODE2_OVERFLOW``
126 Signifies that the IR receiver encounter an overflow, and some IR
127 is missing. The IR data after this should be correct again. The
128 actual value is not important, but this is set to 0xffffff by the
129 kernel for compatibility with lircd.
135 In pulse mode, a sequence of pulse/space integer values are written to the
136 lirc device using :ref:`lirc-write`.
138 The values are alternating pulse and space lengths, in microseconds. The
139 first and last entry must be a pulse, so there must be an odd number
142 This mode is used only for IR send.
144 *************************************
145 Data types used by LIRC_MODE_SCANCODE
146 *************************************
148 .. kernel-doc:: include/uapi/linux/lirc.h
149 :identifiers: lirc_scancode rc_proto
155 The kernel has support for decoding the most common
156 :ref:`IR protocols <Remote_controllers_Protocols>`, but there
157 are many protocols which are not supported. To support these, it is possible
158 to load an BPF program which does the decoding. This can only be done on
159 LIRC devices which support reading raw IR.
161 First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
162 program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
163 to the LIRC device, this program will be called for each pulse, space or
164 timeout event on the LIRC device. The context for the BPF program is a
165 pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
166 value. When the program has decoded the scancode, it can be submitted using
167 the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
168 movements can be reported using ``bpf_rc_pointer_rel()``.
170 Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
171 program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
172 The target must be the file descriptor for the LIRC device, and the
173 attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
174 attached to a single LIRC device at a time.
176 .. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html