1.. SPDX-License-Identifier: GPL-2.0
2
3Remote Controller devices
4-------------------------
5
6Remote Controller core
7~~~~~~~~~~~~~~~~~~~~~~
8
9The remote controller core implements infrastructure to receive and send
10remote controller keyboard keystrokes and mouse events.
11
12Every time a key is pressed on a remote controller, a scan code is produced.
13Also, on most hardware, keeping a key pressed for more than a few dozens of
14milliseconds produce a repeat key event. That's somewhat similar to what
15a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the
16remote controller core is implemented on the top of the linux input/evdev
17interface.
18
19.. [#f1]
20
21   The main difference is that, on keyboard events, the keyboard controller
22   produces one event for a key press and another one for key release. On
23   infrared-based remote controllers, there's no key release event. Instead,
24   an extra code is produced to indicate key repeats.
25
26However, most of the remote controllers use infrared (IR) to transmit signals.
27As there are several protocols used to modulate infrared signals, one
28important part of the core is dedicated to adjust the driver and the core
29system to support the infrared protocol used by the emitter.
30
31The infrared transmission is done by blinking a infrared emitter using a
32carrier. The carrier can be switched on or off by the IR transmitter
33hardware. When the carrier is switched on, it is called *PULSE*.
34When the carrier is switched off, it is called *SPACE*.
35
36In other words, a typical IR transmission can be viewed as a sequence of
37*PULSE* and *SPACE* events, each with a given duration.
38
39The carrier parameters (frequency, duty cycle) and the intervals for
40*PULSE* and *SPACE* events depend on the protocol.
41For example, the NEC protocol uses a carrier of 38kHz, and transmissions
42start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of
43scan code, being 8 bits for address (usually it is a fixed number for a
44given remote controller), followed by 8 bits of code. A bit "1" is modulated
45with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0"  is modulated
46with 560µs *PULSE* followed by 560µs *SPACE*.
47
48At receiver, a simple low-pass filter can be used to convert the received
49signal in a sequence of *PULSE/SPACE* events, filtering out the carrier
50frequency. Due to that, the receiver doesn't care about the carrier's
51actual frequency parameters: all it has to do is to measure the amount
52of time it receives *PULSE/SPACE* events.
53So, a simple IR receiver hardware will just provide a sequence of timings
54for those events to the Kernel. The drivers for hardware with such kind of
55receivers are identified by  ``RC_DRIVER_IR_RAW``, as defined by
56:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a
57microcontroller that decode the *PULSE/SPACE* sequence and return scan
58codes to the Kernel. Such kind of receivers are identified
59by ``RC_DRIVER_SCANCODE``.
60
61.. [#f2]
62
63   The RC core also supports devices that have just IR emitters,
64   without any receivers. Right now, all such devices work only in
65   raw TX mode. Such kind of hardware is identified as
66   ``RC_DRIVER_IR_RAW_TX``.
67
68When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR
69receivers, it needs to decode the IR protocol, in order to obtain the
70corresponding scan code. The protocols supported by the RC core are
71defined at enum :c:type:`rc_proto`.
72
73When the RC code receives a scan code (either directly, by a driver
74of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs
75to convert into a Linux input event code. This is done via a mapping
76table.
77
78The Kernel has support for mapping tables available on most media
79devices. It also supports loading a table in runtime, via some
80sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>`
81for more details.
82
83Remote controller data structures and functions
84^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
85
86.. kernel-doc:: include/media/rc-core.h
87
88.. kernel-doc:: include/media/rc-map.h
89