1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
16 LIRC stands for Linux Infrared Remote Control. The LIRC device interface is
17 a bi-directional interface for transporting raw IR and decoded scancodes
18 data between userspace and kernelspace. Fundamentally, it is just a chardev
19 (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct
20 file_operations defined on it. With respect to transporting raw IR and
21 decoded scancodes to and fro, the essential fops are read, write and ioctl.
23 It is also possible to attach a BPF program to a LIRC device for decoding
24 raw IR into scancodes.
26 Example dmesg output upon a driver registering w/LIRC:
30 $ dmesg |grep lirc_dev
31 rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter
33 What you should see for a chardev:
38 crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
40 Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_
41 contains tools for working with LIRC devices:
43 - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC
46 - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load
47 BPF IR decoders and test IR decoding. Some BPF IR decoders are also
56 LIRC supports some modes of receiving and sending IR codes, as shown
57 on the following table.
59 .. _lirc-mode-scancode:
60 .. _lirc-scancode-flag-toggle:
61 .. _lirc-scancode-flag-repeat:
63 ``LIRC_MODE_SCANCODE``
65 This mode is for both sending and receiving IR.
67 For transmitting (aka sending), create a ``struct lirc_scancode`` with
68 the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
69 set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other
70 members set to 0. Write this struct to the lirc device.
72 For receiving, you read ``struct lirc_scancode`` from the LIRC device.
73 The ``scancode`` field is set to the received scancode and the
74 :ref:`IR protocol <Remote_controllers_Protocols>` is set in
75 :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
76 in the ``keycode`` field, else it is set to ``KEY_RESERVED``.
78 The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle
79 bit is set in protocols that support it (e.g. rc-5 and rc-6), or
80 ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols
81 that support it (e.g. nec).
83 In the Sanyo and NEC protocol, if you hold a button on remote, rather than
84 repeating the entire scancode, the remote sends a shorter message with
85 no scancode, which just means button is held, a "repeat". When this is
86 received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and
89 With nec, there is no way to distinguish "button hold" from "repeatedly
90 pressing the same button". The rc-5 and rc-6 protocols have a toggle bit.
91 When a button is released and pressed again, the toggle bit is inverted.
92 If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set.
94 The ``timestamp`` field is filled with the time nanoseconds
95 (in ``CLOCK_MONOTONIC``) when the scancode was decoded.
101 The driver returns a sequence of pulse and space codes to userspace,
102 as a series of u32 values.
104 This mode is used only for IR receive.
106 The upper 8 bits determine the packet type, and the lower 24 bits
107 the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
108 the macro ``LIRC_MODE2()`` will give you the type, which
113 Signifies the presence of IR in microseconds.
117 Signifies absence of IR in microseconds.
119 ``LIRC_MODE2_FREQUENCY``
121 If measurement of the carrier frequency was enabled with
122 :ref:`lirc_set_measure_carrier_mode` then this packet gives you
123 the carrier frequency in Hertz.
125 ``LIRC_MODE2_TIMEOUT``
127 If timeout reports are enabled with
128 :ref:`lirc_set_rec_timeout_reports`, when the timeout set with
129 :ref:`lirc_set_rec_timeout` expires due to no IR being detected,
130 this packet will be sent, with the number of microseconds with
137 In pulse mode, a sequence of pulse/space integer values are written to the
138 lirc device using :ref:`lirc-write`.
140 The values are alternating pulse and space lengths, in microseconds. The
141 first and last entry must be a pulse, so there must be an odd number
144 This mode is used only for IR send.
150 The kernel has support for decoding the most common
151 :ref:`IR protocols <Remote_controllers_Protocols>`, but there
152 are many protocols which are not supported. To support these, it is possible
153 to load an BPF program which does the decoding. This can only be done on
154 LIRC devices which support reading raw IR.
156 First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
157 program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
158 to the LIRC device, this program will be called for each pulse, space or
159 timeout event on the LIRC device. The context for the BPF program is a
160 pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
161 value. When the program has decoded the scancode, it can be submitted using
162 the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
163 movements can be reported using ``bpf_rc_pointer_rel()``.
165 Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
166 program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
167 The target must be the file descriptor for the LIRC device, and the
168 attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
169 attached to a single LIRC device at a time.
171 .. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html