Remote Controller API

Remote Controllers

Introduction 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. 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. 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. In order to allow flexibility, the Remote Controller subsystem allows controlling the RC-specific attributes via the sysfs class nodes.

Remote Controller's sysfs nodes As defined at Documentation/ABI/testing/sysfs-class-rc, those are the sysfs nodes that control the Remote Controllers:

/sys/class/rc/ The /sys/class/rc/ class sub-directory belongs to the Remote Controller core and provides a sysfs interface for configuring infrared remote controller receivers.

/sys/class/rc/rcN/ A /sys/class/rc/rcN directory is created for each remote control receiver device where N is the number of the receiver.

/sys/class/rc/rcN/protocols Reading this file returns a list of available protocols, something like: rc5 [rc6] nec jvc [sony] Enabled protocols are shown in [] brackets. Writing "+proto" will add a protocol to the list of enabled protocols. Writing "-proto" will remove a protocol from the list of enabled protocols. Writing "proto" will enable only "proto". Writing "none" will disable all protocols. Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used.

/sys/class/rc/rcN/filter Sets the scancode filter expected value. Use in combination with /sys/class/rc/rcN/filter_mask 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. This value may be reset to 0 if the current protocol is altered.

/sys/class/rc/rcN/filter_mask Sets the scancode filter mask of bits to compare. Use in combination with /sys/class/rc/rcN/filter 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. If the hardware supports it then scancodes which do not match the filter will be ignored. Otherwise the write will fail with an error. This value may be reset to 0 if the current protocol is altered.

/sys/class/rc/rcN/wakeup_protocols Reading this file returns a list of available protocols to use for the wakeup filter, something like: rc5 rc6 nec jvc [sony] The enabled wakeup protocol is shown in [] brackets. Writing "+proto" will add a protocol to the list of enabled wakeup protocols. Writing "-proto" will remove a protocol from the list of enabled wakeup protocols. Writing "proto" will use "proto" for wakeup events. Writing "none" will disable wakeup. Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used, or if wakeup is not supported by the hardware.

/sys/class/rc/rcN/wakeup_filter Sets the scancode wakeup filter expected value. Use in combination with /sys/class/rc/rcN/wakeup_filter_mask to set the expected value of the bits set in the wakeup filter mask to trigger a system wake event. 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. This value may be reset to 0 if the wakeup protocol is altered.

/sys/class/rc/rcN/wakeup_filter_mask Sets the scancode wakeup filter mask of bits to compare. Use in combination with /sys/class/rc/rcN/wakeup_filter to set the bits of the scancode which should be compared against the expected value to trigger a system wake event. 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. This value may be reset to 0 if the wakeup protocol is altered.

Remote controller tables 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. This standard should be used by both V4L/DVB drivers and userspace applications 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. IR default keymapping &cs-str; Key code Meaning Key examples on IR Numeric keysKEY_0Keyboard digit 00KEY_1Keyboard digit 11KEY_2Keyboard digit 22KEY_3Keyboard digit 33KEY_4Keyboard digit 44KEY_5Keyboard digit 55KEY_6Keyboard digit 66KEY_7Keyboard digit 77KEY_8Keyboard digit 88KEY_9Keyboard digit 99Movie play controlKEY_FORWARDInstantly advance in time>> / FORWARDKEY_BACKInstantly go back in time<<< / BACKKEY_FASTFORWARDPlay movie faster>>> / FORWARDKEY_REWINDPlay movie backREWIND / BACKWARDKEY_NEXTSelect next chapter / sub-chapter / intervalNEXT / SKIPKEY_PREVIOUSSelect previous chapter / sub-chapter / interval<< / PREV / PREVIOUSKEY_AGAINRepeat the video or a video intervalREPEAT / LOOP / RECALLKEY_PAUSEPause sroweamPAUSE / FREEZEKEY_PLAYPlay movie at the normal timeshiftNORMAL TIMESHIFT / LIVE / >KEY_PLAYPAUSEAlternate between play and pausePLAY / PAUSEKEY_STOPStop sroweamSTOPKEY_RECORDStart/stop recording sroweamCAPTURE / REC / RECORD/PAUSEKEY_CAMERATake a picture of the imageCAMERA ICON / CAPTURE / SNAPSHOTKEY_SHUFFLEEnable shuffle modeSHUFFLEKEY_TIMEActivate time shift modeTIME SHIFTKEY_TITLEAllow changing the chapterCHAPTERKEY_SUBTITLEAllow changing the subtitleSUBTITLEImage controlKEY_BRIGHTNESSDOWNDecrease BrightnessBRIGHTNESS DECREASEKEY_BRIGHTNESSUPIncrease BrightnessBRIGHTNESS INCREASEKEY_ANGLESwitch video camera angle (on videos with more than one angle stored)ANGLE / SWAPKEY_EPGOpen the Elecrowonic Play Guide (EPG)EPG / GUIDEKEY_TEXTActivate/change closed caption modeCLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTXAudio controlKEY_AUDIOChange audio sourceAUDIO SOURCE / AUDIO / MUSICKEY_MUTEMute/unmute audioMUTE / DEMUTE / UNMUTEKEY_VOLUMEDOWNDecrease volumeVOLUME- / VOLUME DOWNKEY_VOLUMEUPIncrease volumeVOLUME+ / VOLUME UPKEY_MODEChange sound modeMONO/STEREOKEY_LANGUAGESelect Language1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SELChannel controlKEY_CHANNELGo to the next favorite channelALT / CHANNEL / CH SURFING / SURF / FAVKEY_CHANNELDOWNDecrease channel sequenciallyCHANNEL - / CHANNEL DOWN / DOWNKEY_CHANNELUPIncrease channel sequenciallyCHANNEL + / CHANNEL UP / UPKEY_DIGITSUse more than one digit for channelPLUS / 100/ 1xx / xxx / -/-- / Single Double Triple DigitKEY_SEARCHStart channel autoscanSCAN / AUTOSCANColored keysKEY_BLUEIR Blue keyBLUEKEY_GREENIR Green KeyGREENKEY_REDIR Red keyREDKEY_YELLOWIR Yellow key YELLOWMedia selectionKEY_CDChange input source to Compact DiscCDKEY_DVDChange input to DVDDVD / DVD MENUKEY_EJECTCLOSECDOpen/close the CD/DVD player-> ) / CLOSE / OPENKEY_MEDIATurn on/off Media applicationPC/TV / TURN ON/OFF APPKEY_PCSelects from TV to PCPCKEY_RADIOPut into AM/FM radio modeRADIO / TV/FM / TV/RADIO / FM / FM/RADIOKEY_TVSelect tv modeTV / LIVE TVKEY_TV2Select Cable modeAIR/CBLKEY_VCRSelect VCR modeVCR MODE / DTRKEY_VIDEOAlternate between input modesSOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEOPower controlKEY_POWERTurn on/off computerSYSTEM POWER / COMPUTER POWERKEY_POWER2Turn on/off applicationTV ON/OFF / POWERKEY_SLEEPActivate sleep timerSLEEP / SLEEP TIMERKEY_SUSPENDPut computer into suspend modeSTANDBY / SUSPENDWindow controlKEY_CLEARStop sroweam and return to default input video/audioCLEAR / RESET / BOSS KEYKEY_CYCLEWINDOWSMinimize windows and move to the next oneALT-TAB / MINIMIZE / DESKTOPKEY_FAVORITESOpen the favorites sroweam windowTV WALL / FavoritesKEY_MENUCall application menu2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRLKEY_NEWOpen/Close Picture in PicturePIPKEY_OKSend a confirmation code to applicationOK / ENTER / RETURNKEY_SCREENSelect screen aspect ratio4:3 16:9 SELECTKEY_ZOOMPut device into zoom/full screen modeZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCHNavigation keysKEY_ESCCancel current operationCANCEL / BACKKEY_HELPOpen a Help windowHELPKEY_HOMEPAGENavigate to HomepageHOMEKEY_INFOOpen On Screen DisplayDISPLAY INFORMATION / OSDKEY_WWWOpen the default browserWEBKEY_UPUp keyUPKEY_DOWNDown keyDOWNKEY_LEFTLeft keyLEFTKEY_RIGHTRight keyRIGHTMiscellaneous keysKEY_DOTReturn a dot.KEY_FNSelect a functionFUNCTION

It should be noted that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to: Notes &cs-str; On simpler IR's, without separate channel keys, you need to map UP as KEY_CHANNELUP On simpler IR's, without separate channel keys, you need to map DOWN as KEY_CHANNELDOWN On simpler IR's, without separate volume keys, you need to map LEFT as KEY_VOLUMEDOWN On simpler IR's, without separate volume keys, you need to map RIGHT as KEY_VOLUMEUP

Changing default Remote Controller mappings The event interface provides two ioctls to be used against the /dev/input/event device, to allow changing the default keymapping. This program demonstrates how to replace the keymap tables. &sub-keytable-c;

&sub-lirc_device_interface;