rc_keymap(5)

1RC_KEYMAP(5)                     File Formats                     RC_KEYMAP(5)
2
3
4

NAME

6       rc_keymap - toml file describing remote control keymap
7

DESCRIPTION

9       An  rc_keymap  describes  a remote control. It list the protocols used,
10       and the mapping from decoded IR to linux input keycodes. This  file  is
11       used  by  ir-keytable(1)  for IR decoding, and by ir-ctl(1) for sending
12       IR.
13
14       The file format is toml. Since a remote control can use multiple proto‐
15       cols,  the top level is an array of protocols. The vast majority of re‐
16       motes only use one protocol.
17

KEYMAP PROTOCOL ENTRY

19       For each protocol the remote uses, there should be one entry in the top
20       level protocols array.
21
22   Name Field
23       Each  protocols  entry  has  a  name  field.  The  name  is not used by
24       ir-keytable or ir-ctl, but can be used to give  the  remote  control  a
25       more descriptive name than the file name, e.g. the model number.
26
27   Protocol Field
28       The  protocol  field  specifies the protocol. This can either be one of
29       the linux kernel decoders, in which case it is nec,  rc-5,  rc-6,  jvc,
30       sony,  sanyo,  rc-5-sz,  sharp, mce-kbd, xmp, imon, rc-mm, other or un‐
31       known. If it does not match any of these entries, then it is assumed to
32       be  a BPF based decoder. The unknown and other are protocols decoded by
33       specific RC devices where the protocol is  either  unknown  or  propri‐
34       etary, respectively.
35
36       There  are some pre-defined BPF protocol decoders, which are listed be‐
37       low. See ⟨https://lwn.net/Articles/759188/⟩ for how to write your own.
38
39   Variant Field
40       The variant field specifies which variant a particular  protocol  uses.
41       The  sony, rc-5, rc-6 protocols have different bit length variants, for
42       example. This field is used by ir-ctl when sending IR.
43
44       The following variants are currently defined:
45
46       Protocol rc-5 has variants rc-5, rc-5x-20, rc-5-sz.
47
48       Protocol nec has variants nec, nec-x, nec-32.
49
50       Protocol sony has variants sony-12, sony-15, sony-20.
51
52       Protocol rc-6 has variants rc-6-0, rc-6-6a-20, rc-6-6a-24,  rc-6-6a-32,
53       rc-6-mce.
54
55       Protocol rc-mm has variants rc-mm-12, rc-mm-24, and rc-mm-32.
56
57   Scancodes field
58       The  scancodes  table list the scancodes and the mapping to linux input
59       keycode. Multiple scancodes can map to the same keycode. The  scancodes
60       field is not present for raw protocols.
61
62       If  the scancode start with 0x, it is interpreted as a hexadecimal num‐
63       ber. If it starts with a 0, it is interpreted as an octal number.
64
65       Valid keycodes are listed in the input-event-codes.h header file.   Ex‐
66       amples  are  KEY_ENTER,  KEY_ESC or BTN_LEFT for the left mouse button.
67       Note that if the keymap is only used for sending IR, then the key  does
68       not  have  to  be  a  valid linux keycode. It can be any string without
69       whitespace.
70
71   Raw field
72       If the protocol is raw, the raw field is an array  of  keycode  to  raw
73       mapping.  For  each  entry, there is a keycode field and raw field. The
74       keycode is a linux input keycode, as explained in the  scancodes  field
75       above.
76
77       The  raw  field is an string, which lists pulse and space values, sepa‐
78       rated by whitespace. The first is a pulse value microseconds,  and  the
79       second a space, third pulse, etc. The space values can be preceded by a
80       - sign and the pulse value can be preceded by a +sign.  There should be
81       an odd number of value so that the last entry is a pulse.
82
83   Remaining fields (BPF parameters)
84       If  the  protocol is a BPF based decoder, it may have any number of nu‐
85       meric parameters. These parameters are used to support  protocols  with
86       non-standard  signaling  lengths  for  standard IR protocols. Any other
87       field specified here which is required by the selected BPF decoder will
88       be used. All other fields are ignored.
89
90       Kernel based non-BPF protocol decoders do not have any parameters.
91

BPF PROTOCOLS

93       Some  of the BPF protocol decoders are generic and will need parameters
94       to work. Other are for specific remotes and should work without any pa‐
95       rameters.  The timing parameters are all in microseconds (µs).
96
97   raw
98       This  decoder  must be used when the keymap is raw; for each key, there
99       is an entry in raw array with the pulse and space values for that  key.
100       No decoding is done, the incoming IR is simply matched against the dif‐
101       ferent pulse and space values.
102
103   imon_rsc
104       This decoder is specifically for the iMON RSC remote, which  was  pack‐
105       aged with the iMON Station (amongst others). The decoder is for the di‐
106       rectional stick in the middle; it will decode  them  into  mouse  move‐
107       ments.  The buttons are all encoded using nec-x so the keymap needs two
108       protocols to work correctly.
109
110       This is unrelated to the imon protocol.
111
112       margin Define how much tolerance there is for message  length.  Default
113              200.
114
115   grundig
116       This decoder is specifically for old grundig remotes.
117
118       header_pulse
119              Length of first pulse, default 900.
120
121       header_space
122              Length of following space, default 2900.
123
124       leader_pulse
125              Length of second pulse, default 1300.
126
127   xbox
128       This  decoder is specifically for the XBox Remote DVD, which is for the
129       first generation XBox.
130
131       margin Define how much tolerance there is for message  length.  Default
132              200.
133
134   manchester
135       Most  manchester  encoded  remote  controls  are  either rc-5, rc-6, or
136       rc-mm.  Some remote use a different variant (e.g.  they  might  have  a
137       header pulse) and that is what the decoder is for. Some parameters must
138       be specified, by default it is set up for rc-5.
139
140       margin Define how much tolerance there is for message  length.  Default
141              200.
142
143       header_pulse
144              Define  how long a leading pulse is. This is not always present.
145              Default 0.
146
147       header_space
148              Define how long the space is after the leading  pulse.  Must  be
149              set if header_pulse is set.
150
151       zero_pulse, zero_space, one_pulse, one_space
152              Signally          lengths          for         bits.         See
153              ⟨https://clearwater.com.au/code/rc5⟩ for these are defined.
154
155       bits   Number of bits. Default 14.
156
157       scancode_mask
158              Bits to mask out of resulting scancode.
159
160       toggle_bit
161              Bit that specifies the toggle. If this value is greater than the
162              number of bits, no toggle is defined.
163
164   pulse_distance
165       This  is  a  generic decoder for protocols that define bits by distance
166       between pulses, and the pulses are always of the same length. The  most
167       well  known  protocol like this is nec. This decoder is cases where nec
168       is not used. The parameters must be set.
169
170       margin Define how much tolerance there is for message  length.  Default
171              200.
172
173       header_pulse
174              Length of the first leading pulse. Default 2125.
175
176       header_space
177              Length of the space after the leading pulse. Default 1875.
178
179       repeat_pulse
180              Length of the leading pulse for key repeat. Default 0.
181
182       repeat_space
183              Length  of the space after the leading pulse for key repeat. De‐
184              fault 0.
185
186       bit_pulse
187              Length of the pulse for each bit. Default 625.
188
189       bit_0_space
190              Length of the space for a zero bit. Default 375.
191
192       bit_1_space
193              Length of the space for a one bit. Default 1625.
194
195       trailer_pulse
196              Length of the pulse after the last bit. Needed  to  bookend  the
197              last bit.  Default 625.
198
199       bits   Number of bits. Default 4.
200
201       reverse
202              Should  the  bits be read in least significant bit first. Set to
203              non-zero to enable. Default 0.
204
205       header_optional
206              Some remotes do not send the header pulse and space for key  re‐
207              peats,  so set this to non-zero to make the header optional. De‐
208              fault 0.
209
210              An alternative implementation might only allow  missing  headers
211              for  repeat  messages, but this would fail to decode key presses
212              if the first message with the header did not decode correctly to
213              due interference.
214
215   pulse_length
216       This  is  a generic decoder for protocols that define bits by length of
217       pulses, and the spaces are always the same. The sony  protocol  is  the
218       most  well-known  protocol, but this decoder is for protocols which are
219       not sony.
220
221       margin Define how much tolerance there is for message  length.  Default
222              200.
223
224       header_pulse
225              Length of the first leading pulse. Default 2125.
226
227       header_space
228              Length of the space after the leading pulse. Default 1875.
229
230       repeat_pulse
231              Length of the leading pulse for key repeat. Default 0.
232
233       repeat_space
234              Length  of the space after the leading pulse for key repeat. De‐
235              fault 0.
236
237       bit_space
238              Length of the space for each bit. Default 625.
239
240       bit_0_pulse
241              Length of the pulse for a zero bit. Default 375.
242
243       bit_1_pulse
244              Length of the pulse for a one bit. Default 1625.
245
246       trailer_pulse
247              Length of the pulse after the last bit. Optional. Default 0.
248
249       bits   Number of bits. Default 4.
250
251       reverse
252              Should the bits be read in least significant bit first.  Set  to
253              non-zero to enable. Default 0.
254
255       header_optional
256              Some  remotes do not send the header pulse and space for key re‐
257              peats, so set this to non-zero to make the header optional.  De‐
258              fault 0.
259
260              An  alternative  implementation might only allow missing headers
261              for repeat messages, but this would fail to decode  key  presses
262              if only the first message did not decode correctly to due inter‐
263              ference.
264

EXAMPLE

266       [[protocols]]
267       name = "iMON Station RSC"
268       protocol = "nec"
269       variant = "necx"
270       [protocols.scancodes]
271       0x801010 = "KEY_EXIT"
272       0x80102f = "KEY_POWER"
273       0x80104a = "KEY_SCREENSAVER"
274       0x801049 = "KEY_TIME"
275       0x801054 = "KEY_NUMERIC_1"
276       0x801055 = "KEY_NUMERIC_2"
277       0x801056 = "KEY_NUMERIC_3"
278       0x801057 = "KEY_NUMERIC_4"
279       0x801058 = "KEY_NUMERIC_5"
280       0x801059 = "KEY_NUMERIC_6"
281       0x80105a = "KEY_NUMERIC_7"
282       0x80105b = "KEY_NUMERIC_8"
283       0x80105c = "KEY_NUMERIC_9"
284       0x801081 = "KEY_SCREEN"
285       0x80105d = "KEY_NUMERIC_0"
286       0x801082 = "KEY_MAX"
287       0x801048 = "KEY_ESC"
288       0x80104b = "KEY_MEDIA"
289       0x801083 = "KEY_MENU"
290       0x801045 = "KEY_APPSELECT"
291       0x801084 = "KEY_STOP"
292       0x801046 = "KEY_CYCLEWINDOWS"
293       0x801085 = "KEY_BACKSPACE"
294       0x801086 = "KEY_KEYBOARD"
295       0x801087 = "KEY_SPACE"
296       0x80101e = "KEY_RESERVED"
297       0x801098 = "BTN_0"
298       0x80101f = "KEY_TAB"
299       0x80101b = "BTN_LEFT"
300       0x80101d = "BTN_RIGHT"
301       0x801016 = "BTN_MIDDLE"
302       0x801088 = "KEY_MUTE"
303       0x80105e = "KEY_VOLUMEDOWN"
304       0x80105f = "KEY_VOLUMEUP"
305       0x80104c = "KEY_PLAY"
306       0x80104d = "KEY_PAUSE"
307       0x80104f = "KEY_EJECTCD"
308       0x801050 = "KEY_PREVIOUS"
309       0x801051 = "KEY_NEXT"
310       0x80104e = "KEY_STOP"
311       0x801052 = "KEY_REWIND"
312       0x801053 = "KEY_FASTFORWARD"
313       0x801089 = "KEY_ZOOM"
314       [[protocols]]
315       protocol = "imon_rsc"
316

BUGS

318       Report bugs to Linux Media Mailing List <linux-media@vger.kernel.org>
319

COPYRIGHT

321       Copyright (C) 2019 by Sean Young <sean@mess.org>
322
323       License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
324       This is free software: you are free  to  change  and  redistribute  it.
325       There is NO WARRANTY, to the extent permitted by law.
326