0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 Remote Controller devices
0004 -------------------------
0005
0006 Remote Controller core
0007 ~~~~~~~~~~~~~~~~~~~~~~
0008
0009 The remote controller core implements infrastructure to receive and send
0010 remote controller keyboard keystrokes and mouse events.
0011
0012 Every time a key is pressed on a remote controller, a scan code is produced.
0013 Also, on most hardware, keeping a key pressed for more than a few dozens of
0014 milliseconds produce a repeat key event. That's somewhat similar to what
0015 a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the
0016 remote controller core is implemented on the top of the linux input/evdev
0017 interface.
0018
0019 .. [#f1]
0020
0021 The main difference is that, on keyboard events, the keyboard controller
0022 produces one event for a key press and another one for key release. On
0023 infrared-based remote controllers, there's no key release event. Instead,
0024 an extra code is produced to indicate key repeats.
0025
0026 However, most of the remote controllers use infrared (IR) to transmit signals.
0027 As there are several protocols used to modulate infrared signals, one
0028 important part of the core is dedicated to adjust the driver and the core
0029 system to support the infrared protocol used by the emitter.
0030
0031 The infrared transmission is done by blinking a infrared emitter using a
0032 carrier. The carrier can be switched on or off by the IR transmitter
0033 hardware. When the carrier is switched on, it is called *PULSE*.
0034 When the carrier is switched off, it is called *SPACE*.
0035
0036 In other words, a typical IR transmission can be viewed as a sequence of
0037 *PULSE* and *SPACE* events, each with a given duration.
0038
0039 The carrier parameters (frequency, duty cycle) and the intervals for
0040 *PULSE* and *SPACE* events depend on the protocol.
0041 For example, the NEC protocol uses a carrier of 38kHz, and transmissions
0042 start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of
0043 scan code, being 8 bits for address (usually it is a fixed number for a
0044 given remote controller), followed by 8 bits of code. A bit "1" is modulated
0045 with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0" is modulated
0046 with 560µs *PULSE* followed by 560µs *SPACE*.
0047
0048 At receiver, a simple low-pass filter can be used to convert the received
0049 signal in a sequence of *PULSE/SPACE* events, filtering out the carrier
0050 frequency. Due to that, the receiver doesn't care about the carrier's
0051 actual frequency parameters: all it has to do is to measure the amount
0052 of time it receives *PULSE/SPACE* events.
0053 So, a simple IR receiver hardware will just provide a sequence of timings
0054 for those events to the Kernel. The drivers for hardware with such kind of
0055 receivers are identified by ``RC_DRIVER_IR_RAW``, as defined by
0056 :c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a
0057 microcontroller that decode the *PULSE/SPACE* sequence and return scan
0058 codes to the Kernel. Such kind of receivers are identified
0059 by ``RC_DRIVER_SCANCODE``.
0060
0061 .. [#f2]
0062
0063 The RC core also supports devices that have just IR emitters,
0064 without any receivers. Right now, all such devices work only in
0065 raw TX mode. Such kind of hardware is identified as
0066 ``RC_DRIVER_IR_RAW_TX``.
0067
0068 When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR
0069 receivers, it needs to decode the IR protocol, in order to obtain the
0070 corresponding scan code. The protocols supported by the RC core are
0071 defined at enum :c:type:`rc_proto`.
0072
0073 When the RC code receives a scan code (either directly, by a driver
0074 of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs
0075 to convert into a Linux input event code. This is done via a mapping
0076 table.
0077
0078 The Kernel has support for mapping tables available on most media
0079 devices. It also supports loading a table in runtime, via some
0080 sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>`
0081 for more details.
0082
0083 Remote controller data structures and functions
0084 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0085
0086 .. kernel-doc:: include/media/rc-core.h
0087
0088 .. kernel-doc:: include/media/rc-map.h
