321 lines
19 KiB
XML
321 lines
19 KiB
XML
<partinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Mauro</firstname>
|
|
<surname>Chehab</surname>
|
|
<othername role="mi">Carvalho</othername>
|
|
<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
|
|
<contrib>Initial version.</contrib>
|
|
</author>
|
|
</authorgroup>
|
|
<copyright>
|
|
<year>2009-2014</year>
|
|
<holder>Mauro Carvalho Chehab</holder>
|
|
</copyright>
|
|
|
|
<revhistory>
|
|
<!-- Put document revisions here, newest first. -->
|
|
<revision>
|
|
<revnumber>3.15</revnumber>
|
|
<date>2014-02-06</date>
|
|
<authorinitials>mcc</authorinitials>
|
|
<revremark>Added the interface description and the RC sysfs class description.</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>1.0</revnumber>
|
|
<date>2009-09-06</date>
|
|
<authorinitials>mcc</authorinitials>
|
|
<revremark>Initial revision</revremark>
|
|
</revision>
|
|
</revhistory>
|
|
</partinfo>
|
|
|
|
<title>Remote Controller API</title>
|
|
<chapter id="remote_controllers">
|
|
|
|
<title>Remote Controllers</title>
|
|
|
|
<section id="Remote_controllers_Intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each
|
|
manufacturer has their own type of control. It is not rare for the same manufacturer to ship different
|
|
types of controls, depending on the device.</para>
|
|
<para>A Remote Controller interface is mapped as a normal evdev/input interface, just like a keyboard or a mouse.
|
|
So, it uses all ioctls already defined for any other input devices.</para>
|
|
<para>However, remove controllers are more flexible than a normal input device, as the IR
|
|
receiver (and/or transmitter) can be used in conjunction with a wide variety of different IR remotes.</para>
|
|
<para>In order to allow flexibility, the Remote Controller subsystem allows controlling the
|
|
RC-specific attributes via <link linkend="remote_controllers_sysfs_nodes">the sysfs class nodes</link>.</para>
|
|
</section>
|
|
|
|
<section id="remote_controllers_sysfs_nodes">
|
|
<title>Remote Controller's sysfs nodes</title>
|
|
<para>As defined at <constant>Documentation/ABI/testing/sysfs-class-rc</constant>, those are the sysfs nodes that control the Remote Controllers:</para>
|
|
|
|
<section id="sys_class_rc">
|
|
<title>/sys/class/rc/</title>
|
|
<para>The <constant>/sys/class/rc/</constant> class sub-directory belongs to the Remote Controller
|
|
core and provides a sysfs interface for configuring infrared remote controller receivers.
|
|
</para>
|
|
|
|
</section>
|
|
<section id="sys_class_rc_rcN">
|
|
<title>/sys/class/rc/rcN/</title>
|
|
<para>A <constant>/sys/class/rc/rcN</constant> directory is created for each remote
|
|
control receiver device where N is the number of the receiver.</para>
|
|
|
|
</section>
|
|
<section id="sys_class_rc_rcN_protocols">
|
|
<title>/sys/class/rc/rcN/protocols</title>
|
|
<para>Reading this file returns a list of available protocols, something like:</para>
|
|
<para><constant>rc5 [rc6] nec jvc [sony]</constant></para>
|
|
<para>Enabled protocols are shown in [] brackets.</para>
|
|
<para>Writing "+proto" will add a protocol to the list of enabled protocols.</para>
|
|
<para>Writing "-proto" will remove a protocol from the list of enabled protocols.</para>
|
|
<para>Writing "proto" will enable only "proto".</para>
|
|
<para>Writing "none" will disable all protocols.</para>
|
|
<para>Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used.</para>
|
|
|
|
</section>
|
|
<section id="sys_class_rc_rcN_filter">
|
|
<title>/sys/class/rc/rcN/filter</title>
|
|
<para>Sets the scancode filter expected value.</para>
|
|
<para>Use in combination with <constant>/sys/class/rc/rcN/filter_mask</constant> to set the
|
|
expected value of the bits set in the filter mask.
|
|
If the hardware supports it then scancodes which do not match
|
|
the filter will be ignored. Otherwise the write will fail with
|
|
an error.</para>
|
|
<para>This value may be reset to 0 if the current protocol is altered.</para>
|
|
|
|
</section>
|
|
<section id="sys_class_rc_rcN_filter_mask">
|
|
<title>/sys/class/rc/rcN/filter_mask</title>
|
|
<para>Sets the scancode filter mask of bits to compare.
|
|
Use in combination with <constant>/sys/class/rc/rcN/filter</constant> to set the bits
|
|
of the scancode which should be compared against the expected
|
|
value. A value of 0 disables the filter to allow all valid
|
|
scancodes to be processed.</para>
|
|
<para>If the hardware supports it then scancodes which do not match
|
|
the filter will be ignored. Otherwise the write will fail with
|
|
an error.</para>
|
|
<para>This value may be reset to 0 if the current protocol is altered.</para>
|
|
|
|
</section>
|
|
<section id="sys_class_rc_rcN_wakeup_protocols">
|
|
<title>/sys/class/rc/rcN/wakeup_protocols</title>
|
|
<para>Reading this file returns a list of available protocols to use for the
|
|
wakeup filter, something like:</para>
|
|
<para><constant>rc5 rc6 nec jvc [sony]</constant></para>
|
|
<para>The enabled wakeup protocol is shown in [] brackets.</para>
|
|
<para>Writing "+proto" will add a protocol to the list of enabled wakeup
|
|
protocols.</para>
|
|
<para>Writing "-proto" will remove a protocol from the list of enabled wakeup
|
|
protocols.</para>
|
|
<para>Writing "proto" will use "proto" for wakeup events.</para>
|
|
<para>Writing "none" will disable wakeup.</para>
|
|
<para>Write fails with EINVAL if an invalid protocol combination or unknown
|
|
protocol name is used, or if wakeup is not supported by the hardware.</para>
|
|
|
|
</section>
|
|
<section id="sys_class_rc_rcN_wakeup_filter">
|
|
<title>/sys/class/rc/rcN/wakeup_filter</title>
|
|
<para>Sets the scancode wakeup filter expected value.
|
|
Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter_mask</constant> to
|
|
set the expected value of the bits set in the wakeup filter mask
|
|
to trigger a system wake event.</para>
|
|
<para>If the hardware supports it and wakeup_filter_mask is not 0 then
|
|
scancodes which match the filter will wake the system from e.g.
|
|
suspend to RAM or power off.
|
|
Otherwise the write will fail with an error.</para>
|
|
<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
|
|
|
|
</section>
|
|
<section id="sys_class_rc_rcN_wakeup_filter_mask">
|
|
<title>/sys/class/rc/rcN/wakeup_filter_mask</title>
|
|
<para>Sets the scancode wakeup filter mask of bits to compare.
|
|
Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter</constant> to set
|
|
the bits of the scancode which should be compared against the
|
|
expected value to trigger a system wake event.</para>
|
|
<para>If the hardware supports it and wakeup_filter_mask is not 0 then
|
|
scancodes which match the filter will wake the system from e.g.
|
|
suspend to RAM or power off.
|
|
Otherwise the write will fail with an error.</para>
|
|
<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="Remote_controllers_tables">
|
|
<title>Remote controller tables</title>
|
|
<para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for
|
|
different devices. This caused the same IR keyname to be mapped completely differently on
|
|
different IR devices. This resulted that the same IR keyname to be mapped completely different on
|
|
different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para>
|
|
<para>This standard should be used by both V4L/DVB drivers and userspace applications</para>
|
|
<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>
|
|
|
|
<table pgwide="1" frame="none" id="rc_standard_keymap">
|
|
<title>IR default keymapping</title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>Key code</entry>
|
|
<entry>Meaning</entry>
|
|
<entry>Key examples on IR</entry>
|
|
</row>
|
|
|
|
<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row>
|
|
<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row>
|
|
<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row>
|
|
<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row>
|
|
<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row>
|
|
<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row>
|
|
<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row>
|
|
<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row>
|
|
<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row>
|
|
<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>>> / FORWARD</entry></row>
|
|
<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry><<< / BACK</entry></row>
|
|
<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>>>> / FORWARD</entry></row>
|
|
<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row>
|
|
<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row>
|
|
<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry><< / PREV / PREVIOUS</entry></row>
|
|
<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row>
|
|
<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row>
|
|
<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / ></entry></row>
|
|
<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row>
|
|
<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row>
|
|
<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row>
|
|
<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row>
|
|
<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row>
|
|
<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row>
|
|
<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row>
|
|
<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Image control</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row>
|
|
<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row>
|
|
|
|
<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>
|
|
<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row>
|
|
<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Audio control</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row>
|
|
<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row>
|
|
<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row>
|
|
<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row>
|
|
<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row>
|
|
<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Channel control</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row>
|
|
<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row>
|
|
<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row>
|
|
<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>
|
|
<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row>
|
|
<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row>
|
|
<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row>
|
|
<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Media selection</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row>
|
|
<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row>
|
|
<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-> ) / CLOSE / OPEN</entry></row>
|
|
|
|
<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row>
|
|
<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row>
|
|
<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>
|
|
<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row>
|
|
<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row>
|
|
<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row>
|
|
<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Power control</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row>
|
|
<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row>
|
|
<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row>
|
|
<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Window control</emphasis></entry></row>
|
|
|
|
<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>
|
|
<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row>
|
|
<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row>
|
|
<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row>
|
|
<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row>
|
|
<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row>
|
|
<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row>
|
|
<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>
|
|
|
|
<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row>
|
|
<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row>
|
|
<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row>
|
|
<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row>
|
|
<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row>
|
|
<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row>
|
|
<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row>
|
|
<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row>
|
|
<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row>
|
|
|
|
<row><entry><emphasis role="bold">Miscellaneous keys</emphasis></entry></row>
|
|
|
|
<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row>
|
|
<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row>
|
|
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<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>
|
|
|
|
<table pgwide="1" frame="none" id="rc_keymap_notes">
|
|
<title>Notes</title>
|
|
<tgroup cols="1">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry>
|
|
</row><row>
|
|
<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry>
|
|
</row><row>
|
|
<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry>
|
|
</row><row>
|
|
<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</section>
|
|
|
|
<section id="Remote_controllers_table_change">
|
|
<title>Changing default Remote Controller mappings</title>
|
|
<para>The event interface provides two ioctls to be used against
|
|
the /dev/input/event device, to allow changing the default
|
|
keymapping.</para>
|
|
|
|
<para>This program demonstrates how to replace the keymap tables.</para>
|
|
&sub-keytable-c;
|
|
</section>
|
|
|
|
&sub-lirc_device_interface;
|
|
</chapter>
|