aboutsummaryrefslogtreecommitdiffstats
path: root/utils/keytable/rc_keymap.5.in
blob: d5de657adb57a272417075f40f39890efac636c1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
.TH "RC_KEYMAP" "5" "Thu Mar 7 2019" "v4l-utils @PACKAGE_VERSION@" "File Formats"
.SH NAME
rc_keymap \- toml file describing remote control keymap
.SH DESCRIPTION
An rc_keymap describes a remote control. It list the protocols used, and the
mapping from decoded IR to linux input events. This file is used by
ir\-keytable(1).
.PP
The file format is toml. Since a remote control can use multiple protocols,
the top level is an array of protocols. The vast majority of remotes only use
one protocol.
.PP
.SH KEYMAP PROTOCOL ENTRY
For each protocol the remote uses, there should be one entry in the top level
\fBprotocols\fR array.
.SS Name Field
Each protocols entry has a \fBname\fR field. The name is not used by
ir\-keytable, but can be used to give the remote control a more descriptive
name than the file name, e.g. the model number.
.SS Protocol Field
The \fBprotocol\fR field specifies the protocol. This can either be one of the
linux kernel decoders, in which case it is \fBnec\fR, \fBrc\-5\fR, \fBrc\-6\fR,
\fBjvc\fR, \fBsony\fR, \fBsanyo\fR, \fBrc\-5\-sz\fR, \fBsharp\fR,
\fBmce\-kbd\fR, \fBxmp\fR, \fBimon\fR, \fBrc\-mm\fR, \fBother\fR or
\fBunknown\fR. If it does not match any of these entries, then it is assumed
to be a BPF based decoder. The \fBunknown\fR and \fBother\fR are protocols
decoded by specific RC devices where the protocol is either unknown or
proprietary, respectively.
.PP
There are some pre-defined BPF protocol decoders, which are listed below. See
.UR https://lwn.net/Articles/759188/
.UE
for how to write your own.
.SS Variant Field
The \fBvariant\fR field specifies which variant a particular protocol uses.
The \fBsony\fR, \fBrc-5\fR, \fBrc-6\fR protocols have different bit length
variants, for example. This field is not currently used. However, this is
needed should the keymap be used for sending IR, rather than decoding it.
.PP
The following variants are currently defined:
.PP
Protocol \fBrc-5\fR has variants \fBrc-5\fR, \fBrc-5x-20\fR, \fBrc-5-sz\fR.
.PP
Protocol \fBnec\fR has variants \fBnec\fR, \fBnec-x\fR, \fBnec-32\fR.
.PP
Protocol \fBsony\fR has variants \fBsony-12\fR, \fBsony-15\fR, \fBsony-20\fR.
.PP
Protocol \fBrc\-6\fR has variants \fBrc-6-0\fR, \fBrc-6-6a-20\fR,
\fBrc-6-6a-24\fR, \fBrc-6-6a-32\fR, \fBrc-6-mce\fR.
.PP
Protocol \fBrc\-mm\fR has variants \fBrc-mm-12\fR, \fBrc-mm-24\fR, and
\fBrc-mm-32\fR.
.SS Scancodes field
The \fBscancodes\fR table list the scancodes and the mapping to linux input
key events. Multiple scancodes can map to the same key event. This field
is not present for \fBraw\fR protocols.
.PP
If the scancode start with 0x, it is interpreted as a hexadecimal number. If
it starts with a 0, it is interpreted as an octal number.
.PP
The key events are listed in the \fBinput-event-codes.h\fR header file.
Examples are \fBKEY_ENTER\fR, \fBKEY_ESC\fR or \fBBTN_LEFT\fR for the left
mouse button.
.SS Raw field
If the protocol is \fBraw\fR, the \fBraw\fR field is an array of keycode
to raw mapping. For each entry, there is a \fBkeycode\fR field and \fBraw\fR
field. The \fBkeycode\fR is a linux input event, as explained the scancodes
section.
.PP
The \fBraw\fR field is an array of integers. These are the pulse and space
values of the IR message. The first is a pulse value in microseconds, and
the second a space, third pulse, etc. There should be an odd number of fields
so that the last entry is a pulse.
.SS Remaining fields (BPF parameters)
If the protocol is a BPF based decoder, it may have any number of numeric
parameters. These parameters are used to support protocols with non-standard
signaling lengths for standard IR protocols. Any other field specified here
which is required by the selected BPF decoder will be used. All other fields
are ignored.

Kernel based non-BPF protocol decoders do not have any parameters.
.PP
.SH BPF PROTOCOLS
.PP
Some of the BPF protocol decoders are generic and will need parameters to
work. Other are for specific remotes and should work without any parameters.
The timing parameters are all in microseconds (┬Ás).
.SS raw
This decoder must be used when the keymap is raw; for each key, there is an
entry in raw array with the pulse and space values for that key. No decoding
is done, the incoming IR is simply matched against the different pulse and
space values.
.SS imon_rsc
This decoder is specifically for the iMON RSC remote, which was packaged with
the iMON Station (amongst others). The decoder is for the directional stick in
the middle; it will decode them into mouse movements. The buttons are all
encoded using nec-x so the keymap needs two protocols to work correctly.

This is unrelated to the \fBimon\fR protocol.
.TP
\fBmargin\fR
Define how much tolerance there is for message length. Default 200.
.PP
.SS grundig
This decoder is specifically for old grundig remotes.
.TP
\fBheader_pulse\fR
Length of first pulse, default 900.
.TP
\fBheader_space\fR
Length of following space, default 2900.
.TP
\fBleader_pulse\fR
Length of second pulse, default 1300.
.PP
.SS xbox
This decoder is specifically for the XBox Remote DVD, which is for the first
generation XBox.
.TP
\fBmargin\fR
Define how much tolerance there is for message length. Default 200.
.SS manchester
Most manchester encoded remote controls are either rc\-5, rc\-6, or rc\-mm.
Some remote use a different variant (e.g. they might have a header pulse) and
that is what the decoder is for. Some parameters must be specified, by default
it is set up for rc\-5.
.TP
\fBmargin\fR
Define how much tolerance there is for message length. Default 200.
.TP
\fBheader_pulse\fR
Define how long a leading pulse is. This is not always present. Default 0.
.TP
\fBheader_space\fR
Define how long the space is after the leading pulse. Must be set if
\fBheader\_pulse\fR is set.
.TP
\fBzero\_pulse\fR, \fBzero\_space\fR, \fBone\_pulse\fR, \fBone\_space\fR
Signally lengths for bits. See
.UR https://clearwater.com.au/code/rc5
.UE
for these are defined.
.TP
\fBbits\fR
Number of bits. Default 14.
.TP
\fBscancode\_mask\fR
Bits to mask out of resulting scancode.
.TP
\fBtoggle\_bit\fR
Bit that specifies the toggle. If this value is greater than the number of
bits, no toggle is defined.
.SS pulse\_distance
This is a generic decoder for protocols that define bits by distance between
pulses, and the pulses are always of the same length. The most well known
protocol like this is \fBnec\fR. This decoder is cases where \fBnec\fR is not
used. The parameters must be set.
.TP
\fBmargin\fR
Define how much tolerance there is for message length. Default 200.
.TP
\fBheader_pulse\fR
Length of the first leading pulse. Default 2125.
.TP
\fBheader_space\fR
Length of the space after the leading pulse. Default 1875.
.TP
\fBrepeat_pulse\fR
Length of the leading pulse for key repeat. Default 0.
.TP
\fBrepeat_space\fR
Length of the space after the leading pulse for key repeat. Default 0.
.TP
\fBbit_pulse\fR
Length of the pulse for each bit. Default 625.
.TP
\fBbit_0_space\fR
Length of the space for a zero bit. Default 375.
.TP
\fBbit_1_space\fR
Length of the space for a one bit. Default 1625.
.TP
\fBtrailer_pulse\fR
Length of the pulse after the last bit. Needed to bookend the last bit.
Default 625.
.TP
\fBbits\fR
Number of bits. Default 4.
.TP
\fBreverse\fR
Should the bits be read in least significant bit first. Set to non-zero to
enable. Default 0.
.TP
\fBheader_optional\fR
Some remotes do not send the header pulse and space for key repeats, so set
this to non-zero to make the header optional. Default 0.

An alternative implementation might only allow missing headers for repeat
messages, but this would fail to decode key presses if the first message with
the header did not decode correctly to due interference.
.SS pulse\_length
This is a generic decoder for protocols that define bits by length of pulses,
and the spaces are always the same. The \fBsony\fR protocol is the most
well-known protocol, but this decoder is for protocols which are not
\fBsony\fR.
.TP
\fBmargin\fR
Define how much tolerance there is for message length. Default 200.
.TP
\fBheader_pulse\fR
Length of the first leading pulse. Default 2125.
.TP
\fBheader_space\fR
Length of the space after the leading pulse. Default 1875.
.TP
\fBrepeat_pulse\fR
Length of the leading pulse for key repeat. Default 0.
.TP
\fBrepeat_space\fR
Length of the space after the leading pulse for key repeat. Default 0.
.TP
\fBbit_space\fR
Length of the space for each bit. Default 625.
.TP
\fBbit_0_pulse\fR
Length of the pulse for a zero bit. Default 375.
.TP
\fBbit_1_pulse\fR
Length of the pulse for a one bit. Default 1625.
.TP
\fBtrailer_pulse\fR
Length of the pulse after the last bit. Optional. Default 0.
.TP
\fBbits\fR
Number of bits. Default 4.
.TP
\fBreverse\fR
Should the bits be read in least significant bit first. Set to non-zero to
enable. Default 0.
.TP
\fBheader_optional\fR
Some remotes do not send the header pulse and space for key repeats, so set
this to non-zero to make the header optional. Default 0.

An alternative implementation might only allow missing headers for repeat
messages, but this would fail to decode key presses if only the first message
did not decode correctly to due interference.
.SH EXAMPLE
.EX
[[protocols]]
name = "iMON Station RSC"
protocol = "nec"
variant = "necx"
[protocols.scancodes]
0x801010 = "KEY_EXIT"
0x80102f = "KEY_POWER"
0x80104a = "KEY_SCREENSAVER"
0x801049 = "KEY_TIME"
0x801054 = "KEY_NUMERIC_1"
0x801055 = "KEY_NUMERIC_2"
0x801056 = "KEY_NUMERIC_3"
0x801057 = "KEY_NUMERIC_4"
0x801058 = "KEY_NUMERIC_5"
0x801059 = "KEY_NUMERIC_6"
0x80105a = "KEY_NUMERIC_7"
0x80105b = "KEY_NUMERIC_8"
0x80105c = "KEY_NUMERIC_9"
0x801081 = "KEY_SCREEN"
0x80105d = "KEY_NUMERIC_0"
0x801082 = "KEY_MAX"
0x801048 = "KEY_ESC"
0x80104b = "KEY_MEDIA"
0x801083 = "KEY_MENU"
0x801045 = "KEY_APPSELECT"
0x801084 = "KEY_STOP"
0x801046 = "KEY_CYCLEWINDOWS"
0x801085 = "KEY_BACKSPACE"
0x801086 = "KEY_KEYBOARD"
0x801087 = "KEY_SPACE"
0x80101e = "KEY_RESERVED"
0x801098 = "BTN_0"
0x80101f = "KEY_TAB"
0x80101b = "BTN_LEFT"
0x80101d = "BTN_RIGHT"
0x801016 = "BTN_MIDDLE"
0x801088 = "KEY_MUTE"
0x80105e = "KEY_VOLUMEDOWN"
0x80105f = "KEY_VOLUMEUP"
0x80104c = "KEY_PLAY"
0x80104d = "KEY_PAUSE"
0x80104f = "KEY_EJECTCD"
0x801050 = "KEY_PREVIOUS"
0x801051 = "KEY_NEXT"
0x80104e = "KEY_STOP"
0x801052 = "KEY_REWIND"
0x801053 = "KEY_FASTFORWARD"
0x801089 = "KEY_ZOOM"
[[protocols]]
protocol = "imon_rsc"
.EE
.SH BUGS
Report bugs to \fBLinux Media Mailing List <linux-media@vger.kernel.org>\fR
.SH COPYRIGHT
Copyright (C) 2019 by Sean Young <sean@mess.org>
.PP
License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH SEE ALSO
ir\-keytable(1).
.PP
https://lwn.net/Articles/759188/
.PP
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/input-event-codes.h#n64

Privacy Policy