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