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