About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / remote_controllers.xml




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

1	<partinfo>
2	<authorgroup>
3	<author>
4	<firstname>Mauro</firstname>
5	<surname>Chehab</surname>
6	<othername role="mi">Carvalho</othername>
7	<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
8	<contrib>Initial version.</contrib>
9	</author>
10	</authorgroup>
11	<copyright>
12		<year>2009-2014</year>
13	        <holder>Mauro Carvalho Chehab</holder>
14	</copyright>
15	
16	<revhistory>
17	<!-- Put document revisions here, newest first. -->
18	<revision>
19	<revnumber>3.15</revnumber>
20	<date>2014-02-06</date>
21	<authorinitials>mcc</authorinitials>
22	<revremark>Added the interface description and the RC sysfs class description.</revremark>
23	</revision>
24	<revision>
25	<revnumber>1.0</revnumber>
26	<date>2009-09-06</date>
27	<authorinitials>mcc</authorinitials>
28	<revremark>Initial revision</revremark>
29	</revision>
30	</revhistory>
31	</partinfo>
32	
33	 <title>Remote Controller API</title>
34	 <chapter id="remote_controllers">
35	
36	<title>Remote Controllers</title>
37	
38	<section id="Remote_controllers_Intro">
39	<title>Introduction</title>
40	
41	<para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each
42	manufacturer has their own type of control. It is not rare for the same manufacturer to ship different
43	types of controls, depending on the device.</para>
44	<para>A Remote Controller interface is mapped as a normal evdev/input interface, just like a keyboard or a mouse.
45	So, it uses all ioctls already defined for any other input devices.</para>
46	<para>However, remove controllers are more flexible than a normal input device, as the IR
47	receiver (and/or transmitter) can be used in conjunction with a wide variety of different IR remotes.</para>
48	<para>In order to allow flexibility, the Remote Controller subsystem allows controlling the
49	RC-specific attributes via <link linkend="remote_controllers_sysfs_nodes">the sysfs class nodes</link>.</para>
50	</section>
51	
52	<section id="remote_controllers_sysfs_nodes">
53	<title>Remote Controller's sysfs nodes</title>
54	<para>As defined at <constant>Documentation/ABI/testing/sysfs-class-rc</constant>, those are the sysfs nodes that control the Remote Controllers:</para>
55	
56	<section id="sys_class_rc">
57	<title>/sys/class/rc/</title>
58	<para>The <constant>/sys/class/rc/</constant> class sub-directory belongs to the Remote Controller
59	core and provides a sysfs interface for configuring infrared remote controller receivers.
60	</para>
61	
62	</section>
63	<section id="sys_class_rc_rcN">
64	<title>/sys/class/rc/rcN/</title>
65	<para>A <constant>/sys/class/rc/rcN</constant> directory is created for each remote
66	  control receiver device where N is the number of the receiver.</para>
67	
68	</section>
69	<section id="sys_class_rc_rcN_protocols">
70	<title>/sys/class/rc/rcN/protocols</title>
71	<para>Reading this file returns a list of available protocols, something like:</para>
72	<para><constant>rc5 [rc6] nec jvc [sony]</constant></para>
73	<para>Enabled protocols are shown in [] brackets.</para>
74	<para>Writing "+proto" will add a protocol to the list of enabled protocols.</para>
75	<para>Writing "-proto" will remove a protocol from the list of enabled protocols.</para>
76	<para>Writing "proto" will enable only "proto".</para>
77	<para>Writing "none" will disable all protocols.</para>
78	<para>Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used.</para>
79	
80	</section>
81	<section id="sys_class_rc_rcN_filter">
82	<title>/sys/class/rc/rcN/filter</title>
83	<para>Sets the scancode filter expected value.</para>
84	<para>Use in combination with <constant>/sys/class/rc/rcN/filter_mask</constant> to set the
85	expected value of the bits set in the filter mask.
86	If the hardware supports it then scancodes which do not match
87	the filter will be ignored. Otherwise the write will fail with
88	an error.</para>
89	<para>This value may be reset to 0 if the current protocol is altered.</para>
90	
91	</section>
92	<section id="sys_class_rc_rcN_filter_mask">
93	<title>/sys/class/rc/rcN/filter_mask</title>
94	<para>Sets the scancode filter mask of bits to compare.
95	Use in combination with <constant>/sys/class/rc/rcN/filter</constant> to set the bits
96	of the scancode which should be compared against the expected
97	value. A value of 0 disables the filter to allow all valid
98	scancodes to be processed.</para>
99	<para>If the hardware supports it then scancodes which do not match
100	the filter will be ignored. Otherwise the write will fail with
101	an error.</para>
102	<para>This value may be reset to 0 if the current protocol is altered.</para>
103	
104	</section>
105	<section id="sys_class_rc_rcN_wakeup_protocols">
106	<title>/sys/class/rc/rcN/wakeup_protocols</title>
107	<para>Reading this file returns a list of available protocols to use for the
108	wakeup filter, something like:</para>
109	<para><constant>rc5 rc6 nec jvc [sony]</constant></para>
110	<para>The enabled wakeup protocol is shown in [] brackets.</para>
111	<para>Writing "+proto" will add a protocol to the list of enabled wakeup
112	protocols.</para>
113	<para>Writing "-proto" will remove a protocol from the list of enabled wakeup
114	protocols.</para>
115	<para>Writing "proto" will use "proto" for wakeup events.</para>
116	<para>Writing "none" will disable wakeup.</para>
117	<para>Write fails with EINVAL if an invalid protocol combination or unknown
118	protocol name is used, or if wakeup is not supported by the hardware.</para>
119	
120	</section>
121	<section id="sys_class_rc_rcN_wakeup_filter">
122	<title>/sys/class/rc/rcN/wakeup_filter</title>
123	<para>Sets the scancode wakeup filter expected value.
124	Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter_mask</constant> to
125	set the expected value of the bits set in the wakeup filter mask
126	to trigger a system wake event.</para>
127	<para>If the hardware supports it and wakeup_filter_mask is not 0 then
128	scancodes which match the filter will wake the system from e.g.
129	suspend to RAM or power off.
130	Otherwise the write will fail with an error.</para>
131	<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
132	
133	</section>
134	<section id="sys_class_rc_rcN_wakeup_filter_mask">
135	<title>/sys/class/rc/rcN/wakeup_filter_mask</title>
136	<para>Sets the scancode wakeup filter mask of bits to compare.
137	Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter</constant> to set
138	the bits of the scancode which should be compared against the
139	expected value to trigger a system wake event.</para>
140	<para>If the hardware supports it and wakeup_filter_mask is not 0 then
141	scancodes which match the filter will wake the system from e.g.
142	suspend to RAM or power off.
143	Otherwise the write will fail with an error.</para>
144	<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
145	</section>
146	</section>
147	
148	<section id="Remote_controllers_tables">
149	<title>Remote controller tables</title>
150	<para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for
151	different devices.  This caused the same IR keyname to be mapped completely differently on
152	different IR devices. This resulted that the same IR keyname to be mapped completely different on
153	different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para>
154	<para>This standard should be used by both V4L/DVB drivers and userspace applications</para>
155	<para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para>
156	
157	<table pgwide="1" frame="none" id="rc_standard_keymap">
158	<title>IR default keymapping</title>
159	<tgroup cols="3">
160	&cs-str;
161	<tbody valign="top">
162	<row>
163	<entry>Key code</entry>
164	<entry>Meaning</entry>
165	<entry>Key examples on IR</entry>
166	</row>
167	
168	<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row>
169	
170	<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row>
171	<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row>
172	<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row>
173	<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row>
174	<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row>
175	<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row>
176	<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row>
177	<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row>
178	<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row>
179	<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row>
180	
181	<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row>
182	
183	<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>&gt;&gt; / FORWARD</entry></row>
184	<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry>&lt;&lt;&lt; / BACK</entry></row>
185	<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>&gt;&gt;&gt; / FORWARD</entry></row>
186	<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row>
187	<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row>
188	<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry>&lt;&lt; /  PREV / PREVIOUS</entry></row>
189	<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row>
190	<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row>
191	<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / &gt;</entry></row>
192	<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row>
193	<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row>
194	<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row>
195	<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row>
196	<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row>
197	<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row>
198	<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row>
199	<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row>
200	
201	<row><entry><emphasis role="bold">Image control</emphasis></entry></row>
202	
203	<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row>
204	<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row>
205	
206	<row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row>
207	<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row>
208	<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row>
209	
210	<row><entry><emphasis role="bold">Audio control</emphasis></entry></row>
211	
212	<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row>
213	<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row>
214	<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row>
215	<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row>
216	<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row>
217	<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row>
218	
219	<row><entry><emphasis role="bold">Channel control</emphasis></entry></row>
220	
221	<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row>
222	<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row>
223	<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row>
224	<row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx /  -/--  / Single Double Triple Digit</entry></row>
225	<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row>
226	
227	<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row>
228	
229	<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row>
230	<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row>
231	<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row>
232	<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row>
233	
234	<row><entry><emphasis role="bold">Media selection</emphasis></entry></row>
235	
236	<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row>
237	<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row>
238	<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-&gt; ) / CLOSE / OPEN</entry></row>
239	
240	<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV /  TURN ON/OFF APP</entry></row>
241	<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row>
242	<row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row>
243	<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row>
244	<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row>
245	<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row>
246	<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row>
247	
248	<row><entry><emphasis role="bold">Power control</emphasis></entry></row>
249	
250	<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row>
251	<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row>
252	<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row>
253	<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row>
254	
255	<row><entry><emphasis role="bold">Window control</emphasis></entry></row>
256	
257	<row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row>
258	<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row>
259	<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row>
260	<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row>
261	<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row>
262	<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row>
263	<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row>
264	<row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row>
265	
266	<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row>
267	
268	<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row>
269	<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row>
270	<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row>
271	<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row>
272	<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row>
273	<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row>
274	<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row>
275	<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row>
276	<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row>
277	
278	<row><entry><emphasis role="bold">Miscellaneous keys</emphasis></entry></row>
279	
280	<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row>
281	<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row>
282	
283	</tbody>
284	</tgroup>
285	</table>
286	
287	<para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para>
288	
289	<table pgwide="1" frame="none" id="rc_keymap_notes">
290	<title>Notes</title>
291	<tgroup cols="1">
292	&cs-str;
293	<tbody valign="top">
294	<row>
295	<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry>
296	</row><row>
297	<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry>
298	</row><row>
299	<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry>
300	</row><row>
301	<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry>
302	</row>
303	</tbody>
304	</tgroup>
305	</table>
306	
307	</section>
308	
309	<section id="Remote_controllers_table_change">
310	<title>Changing default Remote Controller mappings</title>
311	<para>The event interface provides two ioctls to be used against
312	the /dev/input/event device, to allow changing the default
313	keymapping.</para>
314	
315	<para>This program demonstrates how to replace the keymap tables.</para>
316	&sub-keytable-c;
317	</section>
318	
319	&sub-lirc_device_interface;
320	</chapter>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.