| 1 |
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later |
| 2 |
|
| 3 |
.. _lirc_dev_intro: |
| 4 |
|
| 5 |
************ |
| 6 |
Introduction |
| 7 |
************ |
| 8 |
|
| 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. |
| 15 |
|
| 16 |
It is also possible to attach a BPF program to a LIRC device for decoding |
| 17 |
raw IR into scancodes. |
| 18 |
|
| 19 |
Example dmesg output upon a driver registering w/LIRC: |
| 20 |
|
| 21 |
.. code-block:: none |
| 22 |
|
| 23 |
$ dmesg |grep lirc_dev |
| 24 |
rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter |
| 25 |
|
| 26 |
What you should see for a chardev: |
| 27 |
|
| 28 |
.. code-block:: none |
| 29 |
|
| 30 |
$ ls -l /dev/lirc* |
| 31 |
crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 |
| 32 |
|
| 33 |
Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ |
| 34 |
contains tools for working with LIRC devices: |
| 35 |
|
| 36 |
- ir-ctl: can receive raw IR and transmit IR, as well as query LIRC |
| 37 |
device features. |
| 38 |
|
| 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 |
| 41 |
provided. |
| 42 |
|
| 43 |
.. _lirc_modes: |
| 44 |
|
| 45 |
********** |
| 46 |
LIRC modes |
| 47 |
********** |
| 48 |
|
| 49 |
LIRC supports some modes of receiving and sending IR codes, as shown |
| 50 |
on the following table. |
| 51 |
|
| 52 |
.. _lirc-mode-scancode: |
| 53 |
.. _lirc-scancode-flag-toggle: |
| 54 |
.. _lirc-scancode-flag-repeat: |
| 55 |
|
| 56 |
``LIRC_MODE_SCANCODE`` |
| 57 |
|
| 58 |
This mode is for both sending and receiving IR. |
| 59 |
|
| 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. |
| 64 |
|
| 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``. |
| 70 |
|
| 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). |
| 75 |
|
| 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 |
| 80 |
keycode is repeated. |
| 81 |
|
| 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. |
| 86 |
|
| 87 |
The ``timestamp`` field is filled with the time nanoseconds |
| 88 |
(in ``CLOCK_MONOTONIC``) when the scancode was decoded. |
| 89 |
|
| 90 |
.. _lirc-mode-mode2: |
| 91 |
|
| 92 |
``LIRC_MODE_MODE2`` |
| 93 |
|
| 94 |
The driver returns a sequence of pulse and space codes to userspace, |
| 95 |
as a series of u32 values. |
| 96 |
|
| 97 |
This mode is used only for IR receive. |
| 98 |
|
| 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 |
| 102 |
is one of: |
| 103 |
|
| 104 |
``LIRC_MODE2_PULSE`` |
| 105 |
|
| 106 |
Signifies the presence of IR in microseconds, also known as *flash*. |
| 107 |
|
| 108 |
``LIRC_MODE2_SPACE`` |
| 109 |
|
| 110 |
Signifies absence of IR in microseconds, also known as *gap*. |
| 111 |
|
| 112 |
``LIRC_MODE2_FREQUENCY`` |
| 113 |
|
| 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. |
| 117 |
|
| 118 |
``LIRC_MODE2_TIMEOUT`` |
| 119 |
|
| 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. |
| 123 |
|
| 124 |
``LIRC_MODE2_OVERFLOW`` |
| 125 |
|
| 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. |
| 130 |
|
| 131 |
.. _lirc-mode-pulse: |
| 132 |
|
| 133 |
``LIRC_MODE_PULSE`` |
| 134 |
|
| 135 |
In pulse mode, a sequence of pulse/space integer values are written to the |
| 136 |
lirc device using :ref:`lirc-write`. |
| 137 |
|
| 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 |
| 140 |
of entries. |
| 141 |
|
| 142 |
This mode is used only for IR send. |
| 143 |
|
| 144 |
************************************* |
| 145 |
Data types used by LIRC_MODE_SCANCODE |
| 146 |
************************************* |
| 147 |
|
| 148 |
.. kernel-doc:: include/uapi/linux/lirc.h |
| 149 |
:identifiers: lirc_scancode rc_proto |
| 150 |
|
| 151 |
******************** |
| 152 |
BPF based IR decoder |
| 153 |
******************** |
| 154 |
|
| 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. |
| 160 |
|
| 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()``. |
| 169 |
|
| 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. |
| 175 |
|
| 176 |
.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html |