1.. SPDX-License-Identifier: GPL-2.0
2..
3.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
4
5.. _Remote_controllers_Protocols:
6
7*****************************************
8Remote Controller Protocols and Scancodes
9*****************************************
10
11IR is encoded as a series of pulses and spaces, using a protocol. These
12protocols can encode e.g. an address (which device should respond) and a
13command: what it should do. The values for these are not always consistent
14across different devices for a given protocol.
15
16Therefore out the output of the IR decoder is a scancode; a single u32
17value. Using keymap tables this can be mapped to linux key codes.
18
19Other things can be encoded too. Some IR protocols encode a toggle bit; this
20is to distinguish whether the same button is being held down, or has been
21released and pressed again. If has been released and pressed again, the
22toggle bit will invert from one IR message to the next.
23
24Some remotes have a pointer-type device which can used to control the
25mouse; some air conditioning systems can have their target temperature
26target set in IR.
27
28The following are the protocols the kernel knows about and also lists
29how scancodes are encoded for each protocol.
30
31rc-5 (RC_PROTO_RC5)
32-------------------
33
34This IR protocol uses manchester encoding to encode 14 bits. There is a
35detailed description here https://www.sbprojects.net/knowledge/ir/rc5.php.
36
37The scancode encoding is *not* consistent with the lirc daemon (lircd) rc5
38protocol, or the manchester BPF decoder.
39
40.. flat-table:: rc5 bits scancode mapping
41   :widths:       1 1 2
42
43   * - rc-5 bit
44
45     - scancode bit
46
47     - description
48
49   * - 1
50
51     - none
52
53     - Start bit, always set
54
55   * - 1
56
57     - 6 (inverted)
58
59     - 2nd start bit in rc5,  re-used as 6th command bit
60
61   * - 1
62
63     - none
64
65     - Toggle bit
66
67   * - 5
68
69     - 8 to 13
70
71     - Address
72
73   * - 6
74
75     - 0 to 5
76
77     - Command
78
79There is a variant of rc5 called either rc5x or extended rc5
80where there the second stop bit is the 6th commmand bit, but inverted.
81This is done so it the scancodes and encoding is compatible with existing
82schemes. This bit is stored in bit 6 of the scancode, inverted. This is
83done to keep it compatible with plain rc-5 where there are two start bits.
84
85rc-5-sz (RC_PROTO_RC5_SZ)
86-------------------------
87This is much like rc-5 but one bit longer. The scancode is encoded
88differently.
89
90.. flat-table:: rc-5-sz bits scancode mapping
91   :widths:       1 1 2
92
93   * - rc-5-sz bits
94
95     - scancode bit
96
97     - description
98
99   * - 1
100
101     - none
102
103     - Start bit, always set
104
105   * - 1
106
107     - 13
108
109     - Address bit
110
111   * - 1
112
113     - none
114
115     - Toggle bit
116
117   * - 6
118
119     - 6 to 11
120
121     - Address
122
123   * - 6
124
125     - 0 to 5
126
127     - Command
128
129rc-5x-20 (RC_PROTO_RC5X_20)
130---------------------------
131
132This rc-5 extended to encoded 20 bits. The is a 3555 microseconds space
133after the 8th bit.
134
135.. flat-table:: rc-5x-20 bits scancode mapping
136   :widths:       1 1 2
137
138   * - rc-5-sz bits
139
140     - scancode bit
141
142     - description
143
144   * - 1
145
146     - none
147
148     - Start bit, always set
149
150   * - 1
151
152     - 14
153
154     - Address bit
155
156   * - 1
157
158     - none
159
160     - Toggle bit
161
162   * - 5
163
164     - 16 to 20
165
166     - Address
167
168   * - 6
169
170     - 8 to 13
171
172     - Address
173
174   * - 6
175
176     - 0 to 5
177
178     - Command
179
180
181jvc (RC_PROTO_JVC)
182------------------
183
184The jvc protocol is much like nec, without the inverted values. It is
185described here https://www.sbprojects.net/knowledge/ir/jvc.php.
186
187The scancode is a 16 bits value, where the address is the lower 8 bits
188and the command the higher 8 bits; this is reversed from IR order.
189
190sony-12 (RC_PROTO_SONY12)
191-------------------------
192
193The sony protocol is a pulse-width encoding. There are three variants,
194which just differ in number of bits and scancode encoding.
195
196.. flat-table:: sony-12 bits scancode mapping
197   :widths:       1 1 2
198
199   * - sony-12 bits
200
201     - scancode bit
202
203     - description
204
205   * - 5
206
207     - 16 to 20
208
209     - device
210
211   * - 7
212
213     - 0 to 6
214
215     - function
216
217sony-15 (RC_PROTO_SONY15)
218-------------------------
219
220The sony protocol is a pulse-width encoding. There are three variants,
221which just differ in number of bits and scancode encoding.
222
223.. flat-table:: sony-12 bits scancode mapping
224   :widths:       1 1 2
225
226   * - sony-12 bits
227
228     - scancode bit
229
230     - description
231
232   * - 8
233
234     - 16 to 23
235
236     - device
237
238   * - 7
239
240     - 0 to 6
241
242     - function
243
244sony-20 (RC_PROTO_SONY20)
245-------------------------
246
247The sony protocol is a pulse-width encoding. There are three variants,
248which just differ in number of bits and scancode encoding.
249
250.. flat-table:: sony-20 bits scancode mapping
251   :widths:       1 1 2
252
253   * - sony-20 bits
254
255     - scancode bit
256
257     - description
258
259   * - 5
260
261     - 16 to 20
262
263     - device
264
265   * - 7
266
267     - 0 to 7
268
269     - device
270
271   * - 8
272
273     - 8 to 15
274
275     - extended bits
276
277nec (RC_PROTO_NEC)
278------------------
279
280The nec protocol encodes an 8 bit address and an 8 bit command. It is
281described here https://www.sbprojects.net/knowledge/ir/nec.php. Note
282that the protocol sends least significant bit first.
283
284As a check, the nec protocol sends the address and command twice; the
285second time it is inverted. This is done for verification.
286
287A plain nec IR message has 16 bits; the high 8 bits are the address
288and the low 8 bits are the command.
289
290nec-x (RC_PROTO_NECX)
291---------------------
292
293Extended nec has a 16 bit address and a 8 bit command. This is encoded
294as a 24 bit value as you would expect, with the lower 8 bits the command
295and the upper 16 bits the address.
296
297nec-32 (RC_PROTO_NEC32)
298-----------------------
299
300nec-32 does not send an inverted address or an inverted command; the
301entire message, all 32 bits, are used.
302
303For this to be decoded correctly, the second 8 bits must not be the
304inverted value of the first, and also the last 8 bits must not be the
305inverted value of the third 8 bit value.
306
307The scancode has a somewhat unusual encoding.
308
309.. flat-table:: nec-32 bits scancode mapping
310
311   * - nec-32 bits
312
313     - scancode bit
314
315   * - First 8 bits
316
317     - 16 to 23
318
319   * - Second 8 bits
320
321     - 24 to 31
322
323   * - Third 8 bits
324
325     - 0 to 7
326
327   * - Fourth 8 bits
328
329     - 8 to 15
330
331sanyo (RC_PROTO_SANYO)
332----------------------
333
334The sanyo protocol is like the nec protocol, but with 13 bits address
335rather than 8 bits. Both the address and the command are followed by
336their inverted versions, but these are not present in the scancodes.
337
338Bis 8 to 20 of the scancode is the 13 bits address, and the lower 8
339bits are the command.
340
341mcir2-kbd (RC_PROTO_MCIR2_KBD)
342------------------------------
343
344This protocol is generated by the Microsoft MCE keyboard for keyboard
345events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded.
346
347mcir2-mse (RC_PROTO_MCIR2_MSE)
348------------------------------
349
350This protocol is generated by the Microsoft MCE keyboard for pointer
351events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded.
352
353rc-6-0 (RC_PROTO_RC6_0)
354-----------------------
355
356This is the rc-6 in mode 0. rc-6 is described here
357https://www.sbprojects.net/knowledge/ir/rc6.php.
358The scancode is the exact 16 bits as in the protocol. There is also a
359toggle bit.
360
361rc-6-6a-20 (RC_PROTO_RC6_6A_20)
362-------------------------------
363
364This is the rc-6 in mode 6a, 20 bits. rc-6 is described here
365https://www.sbprojects.net/knowledge/ir/rc6.php.
366The scancode is the exact 20 bits
367as in the protocol. There is also a toggle bit.
368
369rc-6-6a-24 (RC_PROTO_RC6_6A_24)
370-------------------------------
371
372This is the rc-6 in mode 6a, 24 bits. rc-6 is described here
373https://www.sbprojects.net/knowledge/ir/rc6.php.
374The scancode is the exact 24 bits
375as in the protocol. There is also a toggle bit.
376
377rc-6-6a-32 (RC_PROTO_RC6_6A_32)
378-------------------------------
379
380This is the rc-6 in mode 6a, 32 bits. rc-6 is described here
381https://www.sbprojects.net/knowledge/ir/rc6.php.
382The upper 16 bits are the vendor,
383and the lower 16 bits are the vendor-specific bits. This protocol is
384for the non-Microsoft MCE variant (vendor != 0x800f).
385
386
387rc-6-mce (RC_PROTO_RC6_MCE)
388---------------------------
389
390This is the rc-6 in mode 6a, 32 bits. The upper 16 bits are the vendor,
391and the lower 16 bits are the vendor-specific bits. This protocol is
392for the Microsoft MCE variant (vendor = 0x800f). The toggle bit in the
393protocol itself is ignored, and the 16th bit should be takes as the toggle
394bit.
395
396sharp (RC_PROTO_SHARP)
397----------------------
398
399This is a protocol used by Sharp VCRs, is described here
400https://www.sbprojects.net/knowledge/ir/sharp.php. There is a very long
401(40ms) space between the normal and inverted values, and some IR receivers
402cannot decode this.
403
404There is a 5 bit address and a 8 bit command. In the scancode the address is
405in bits 8 to 12, and the command in bits 0 to 7.
406
407xmp (RC_PROTO_XMP)
408------------------
409
410This protocol has several versions and only version 1 is supported. Refer
411to the decoder (ir-xmp-decoder.c) to see how it is encoded.
412
413
414cec (RC_PROTO_CEC)
415------------------
416
417This is not an IR protocol, this is a protocol over CEC. The CEC
418infrastructure uses rc-core for handling CEC commands, so that they
419can easily be remapped.
420
421imon (RC_PROTO_IMON)
422--------------------
423
424This protocol is used by Antec Veris/SoundGraph iMON remotes.
425
426The protocol
427describes both button presses and pointer movements. The protocol encodes
42831 bits, and the scancode is simply the 31 bits with the top bit always 0.
429
430rc-mm-12 (RC_PROTO_RCMM12)
431--------------------------
432
433The rc-mm protocol is described here
434https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
435the 12 bits.
436
437rc-mm-24 (RC_PROTO_RCMM24)
438--------------------------
439
440The rc-mm protocol is described here
441https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
442the 24 bits.
443
444rc-mm-32 (RC_PROTO_RCMM32)
445--------------------------
446
447The rc-mm protocol is described here
448https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
449the 32 bits.
450
451xbox-dvd (RC_PROTO_XBOX_DVD)
452----------------------------
453
454This protocol is used by XBox DVD Remote, which was made for the original
455XBox. There is no in-kernel decoder or encoder for this protocol. The usb
456device decodes the protocol. There is a BPF decoder available in v4l-utils.
457