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  events.  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, but can be used to give the remote control a more descrip‐
25       tive 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  not  currently used. However, this is needed
44       should the keymap be used for sending IR, rather than decoding it.
45
46       The following variants are currently defined:
47
48       Protocol rc-5 has variants rc-5, rc-5x-20, rc-5-sz.
49
50       Protocol nec has variants nec, nec-x, nec-32.
51
52       Protocol sony has variants sony-12, sony-15, sony-20.
53
54       Protocol rc-6 has variants rc-6-0, rc-6-6a-20, rc-6-6a-24,  rc-6-6a-32,
55       rc-6-mce.
56
57       Protocol rc-mm has variants rc-mm-12, rc-mm-24, and rc-mm-32.
58
59   Scancodes field
60       The  scancodes  table list the scancodes and the mapping to linux input
61       key events. Multiple scancodes can map to  the  same  key  event.  This
62       field is not present for raw protocols.
63
64       If  the scancode start with 0x, it is interpreted as a hexadecimal num‐
65       ber. If it starts with a 0, it is interpreted as an octal number.
66
67       The key events are  listed  in  the  input-event-codes.h  header  file.
68       Examples are KEY_ENTER, KEY_ESC or BTN_LEFT for the left mouse button.
69
70   Raw field
71       If  the  protocol  is  raw, the raw field is an array of keycode to raw
72       mapping. For each entry, there is a keycode field and  raw  field.  The
73       keycode is a linux input event, as explained the scancodes section.
74
75       The  raw  field is an string, which lists pulse and space values, sepa‐
76       rated by whitespace. The first is a pulse value microseconds,  and  the
77       second a space, third pulse, etc. The space values can be preceded by a
78       - sign and the pulse value can be preceded by a +sign.  There should be
79       an odd number of value so that the last entry is a pulse.
80
81   Remaining fields (BPF parameters)
82       If  the  protocol  is  a  BPF  based decoder, it may have any number of
83       numeric parameters. These parameters are used to support protocols with
84       non-standard  signaling  lengths  for  standard IR protocols. Any other
85       field specified here which is required by the selected BPF decoder will
86       be used. All other fields are ignored.
87
88       Kernel based non-BPF protocol decoders do not have any parameters.
89

BPF PROTOCOLS

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

EXAMPLE

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

BUGS

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

COPYRIGHT

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