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
16       remotes 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
31       unknown. If it does not match any of these entries, then it is  assumed
32       to  be a BPF based decoder. The unknown and other are protocols decoded
33       by 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
37       below. See ⟨https://lwn.net/Articles/759188/⟩ for  how  to  write  your
38       own.
39
40   Variant Field
41       The  variant  field specifies which variant a particular protocol uses.
42       The sony, rc-5, rc-6 protocols have different bit length variants,  for
43       example. This field is used by ir-ctl when sending IR.
44
45       The following variants are currently defined:
46
47       Protocol rc-5 has variants rc-5, rc-5x-20, rc-5-sz.
48
49       Protocol nec has variants nec, nec-x, nec-32.
50
51       Protocol sony has variants sony-12, sony-15, sony-20.
52
53       Protocol  rc-6 has variants rc-6-0, rc-6-6a-20, rc-6-6a-24, rc-6-6a-32,
54       rc-6-mce.
55
56       Protocol rc-mm has variants rc-mm-12, rc-mm-24, and rc-mm-32.
57
58   Scancodes field
59       The scancodes table list the scancodes and the mapping to  linux  input
60       keycode.  Multiple scancodes can map to the same keycode. The scancodes
61       field is not present for raw protocols.
62
63       If the scancode start with 0x, it is interpreted as a hexadecimal  num‐
64       ber. If it starts with a 0, it is interpreted as an octal number.
65
66       Valid  keycodes  are  listed  in  the  input-event-codes.h header file.
67       Examples are KEY_ENTER, KEY_ESC or BTN_LEFT for the left mouse  button.
68       Note  that if the keymap is only used for sending IR, then the key does
69       not have to be a valid linux keycode. It  can  be  any  string  without
70       whitespace.
71
72   Raw field
73       If  the  protocol  is  raw, the raw field is an array of keycode to raw
74       mapping. For each entry, there is a keycode field and  raw  field.  The
75       keycode  is  a linux input keycode, as explained in the scancodes field
76       above.
77
78       The raw field is an string, which lists pulse and space  values,  sepa‐
79       rated  by  whitespace. The first is a pulse value microseconds, and the
80       second a space, third pulse, etc. The space values can be preceded by a
81       - sign and the pulse value can be preceded by a +sign.  There should be
82       an odd number of value so that the last entry is a pulse.
83
84   Remaining fields (BPF parameters)
85       If the protocol is a BPF based decoder,  it  may  have  any  number  of
86       numeric parameters. These parameters are used to support protocols with
87       non-standard signaling lengths for standard  IR  protocols.  Any  other
88       field specified here which is required by the selected BPF decoder will
89       be used. All other fields are ignored.
90
91       Kernel based non-BPF protocol decoders do not have any parameters.
92

BPF PROTOCOLS

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

EXAMPLE

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

BUGS

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

COPYRIGHT

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