Control LinuxMCE using an Infrared remote

This page was written by Pluto and imported with their permission when LinuxMCE branched off in February, 2007. In general any information should apply to LinuxMCE. However, this page should be edited to reflect changes to LinuxMCE and remove old references to Pluto.

How to set it up

In LinuxMCEAdmin choose Wizard, Devices, Media Directors. Choose the type of Infrared Receiver you have from the pull-down. The list of choices are LIRC drivers, so you can also refer to http://lirc.org/ for details. Most use the "default" driver. Then add all the "Infrared remote controls you will use". You can have as many as you want and they will all work. LinuxMCEAdmin will then add 1 Infrared Receiver device, and 1 device for each remote control you added. After adding any new devices chose Wizard, Restart and click Quick Reload Router so LinuxMCE starts using that device.

How to use it

When the media director starts you will see a graphical user interface with a menu of buttons. This is the "Orbiter". It's the same user interface as on the web-pads and PDA's. The Orbiter that the media director displays on your TV we call the On-screen Orbiter, to distinguish from the other roving Orbiters like the PDA's and mobile phones. What the buttons on the infrared remote control do depends largely on what you see on the On-Screen Orbiter. LinuxMCE is intelligent enough to know that sometimes you push buttons to control the media director's Orbiter, and sometimes you push buttons to control whatever media device you're using. LinuxMCE will handle all the translation for you. In other words you can use one universal remote control to LinuxMCE and other A/V Equipment.

Here's an example. Let's say you have a media director, which is also controlling your satellite TV box as well as a regular DVD player. The media director is controlling both of them via Infrared. You have a universal remote control which you added to LinuxMCE as described above. The On-screen Orbiter is visible on the TV. As you hit the up/down/left/right/enter buttons on the remote you will see that you can select the menu options on the Orbiter. You select the button to watch "Satellite TV", and the TV appears. Now when you hit up/down/left/right/enter LinuxMCE knows you obviously want to control the satellite tv box. So, when you press those buttons LinuxMCE translates the infrared codes into ones that your satellite tv box understands, and you will see the same arrows on the same remote control are now controlling the satellite TV. You hit 'Power Off', and the satellite box shuts off, and the Orbiter's menu is again visible. Now the arrows are again controlling the Orbiter. You choose the button to watch a DVD in your DVD Player. Now the same arrows are controlling the DVD player. And when you hit 'pause' the DVD player will pause, even though you're holding the LinuxMCE remote--not the DVD remote. LinuxMCE is translating everything for you so you don't have to juggle remote controls. Again you hit 'power' and the DVD turns off. Hit 'power' again and the orbiter shuts the TV off. Hit 'power' a third time and the media director itself turns off. This is even better than a universal remote control since you don't need to tell it what device you want to control--LinuxMCE figures it out on its own.

Although you can use all sorts of remote controls, and all have different buttons, they will all control LinuxMCE in a consistent manner. The media-specific buttons, like rewind/fastforward, play/pause, etc., will always control whatever media device you are currently listening to no matter what screen is visible on the on-screen Orbiter. Navigation buttons, like up/down/left/right/enter and the 10-key number pad, will control the currently active media device if the On-screen Orbiter is showing the remote control for that device. Otherwise it controls the On-screen Orbiter. When the main menu is visible on the Orbiter you can select scenarios with the up/down/left/right/enter buttons, or the 10-key pad. To use the 10-key pad, hit the type of scenario you want: the categories are always numbered as follows: 1=Lighting, 2=Media, 3=Climate, 4=Telecom, 5=Security, 6=Misc Then when the list of those scenarios appears, hit the scenario you want, such as 2 for the 2nd scenario. Thus 22 on the remote will start TV (2=Media, TV is always the 2nd option).

You can use different remote controls that have completely different layouts, but they will still control LinuxMCE in a consistent manner. For example you can use a Bang & Olufsen remote which only has a single set of up/down/left/right buttons, and LinuxMCE knows that when there is a menu on screen those buttons should move the highlighter around on the screen, and when there is not a menu on screen, those buttons are used for rewind fast-forward and skip up/down. The logic is all handled automatically so for the user it is a very intuitive experience, allowing all sorts of different devices to be controlled with all sorts of different remote controls without having to do any setup.

Programmer's guide

Be sure to read the How To Use It section above first. As you can see, LinuxMCE provides a highly intelligent interpretation of infrared remote buttons, that automatically change their function based on what the user is doing, what type of remote control layout exists, and where the infrared codes are going. If you have ever worked with infrared remote controls, such as LIRC, you know that there is no standard, and all the remote controls have different buttons with different names. Therefore we had to create a database structure that allows for interpreting the different button names into commands which can change depending upon the context and the layout of the remote.

The DCE Devices (ie the LinuxMCE binary that is run to handle i/r reception) are all of the category Peripherals, Infrared Receivers. In LinuxMCE Admin choose Advanced, Device Templates, and you can see the categories and devices in them. There is a separate folder for the LIRC drivers. In addition to a device for the i/r receiver, there is also a device for the i/r remote. The remote controls are of the type Peripherals, Remote Controls. Since the definition of the infrared codes for a remote control is stored within the remote control device, and that definition varies depending upon the type of receiver, you will see there is a separate subcategory for each type of receiver. For example there is a folder "LIRC Remote Controls" that has all of the remote controls and definition files for the LIRC project. We also created our own DCE devices for other infrared receivers, such as IRTrans and Tira. Although these are supported within the lirc project, we found that we had better control and greater accuracy when we used the native SDKs for these receivers. So, for example, if you have an IRTrans receiver, and an XPMC remote, you have two possibilities. First you could add the LIRC receiver device, and the XPMC remote device that is within the LIRC remote category. In this case the remote control will be using an LIRC config file. Secondly you could add LinuxMCE's native IRTrans receiver device, and then pick the XMPC remote device that is within the IRTrans remotes category, which stores the button codes in a different format, that is in IRTrans' native format. When you are adding your infrared receiver and remote control using the LinuxMCE Admin Wizard/Devices/Media Directors page, the wizard automatically ensures that when you add a remote control it is the correct category.

For each remote control there is a device data "#59 Configuration" which has the remote controls configuration file, which defined all the infrared codes at each button will send and gives each code, or button, a name. So the XPMC remote within the LIRC category has a device data #59 that is the LIRC config file. The XPMC remote within the IRTrans category has a device data #59 that is the same buttons/codes, but in IRTrans format.

When the framework starts an IR receiver device, iIn general this device will first scan for all sister devices within the category remote control, and write out a configuration file. So, for example, when LIRC_DCE runs it finds all LIRC remote controls on that machine, grabs the device data "#59 Configuration" for every one of them and writes that out to a lirc.conf file, and then starts LIRC.

All the logic is in a base class called IRReceiverBase. All of LinuxMCE's infrared receiver devices use this same base class. So the actual code that is specific to each type of receiver is very small, usually around 20 lines. It only needs to write out the configuration file at start up, and then call the member function ReceivedCode within IRReceiverBase when a button is pushed. This function takes the name of the button as a parameter, and converts this into a message.

Since all of the receivers use a common base class to handle the logic, that also means that all of the translation between buttons and actions is also in a shared database. It does not matter whether you are using LIRC or some other infrared receiver, the translation is the same. There is no unified standard for what the buttons are called. The button "SkipFwd" may be called "Fwd", "Skip+", "Jump->", etc. The table RemoteMapping in the main mysql database, pluto_main, has a field Mapping which lists all the button aliases, followed by the command to be executed when any of those buttons is pushed. For example: chup;skipfwd;ChanUp;SkipNext;|0 -106 1 65 5 +1

Whenever any infrared receiver reports any of those button presses, the message "0 -106 1 65 5 +1" gets fired. The format of the message is the same as if you typed it with the MessageSend utility: ie from device, to device message type, message id, followed by parameters.

So if the user presses a button called ChanUp, a message will be sent to device -106 (media plugin) of type 1 (command) id 65 (Jump Position In Playlist) with parameter 5 (Value To Assign) set to "+1". This table is shared amongst all LinuxMCE users, and is updated every time your system upgrades versions. If you make your own manual changes to this table then the next time your core upgrades it will not upgrade the rows in that table that you modified, because SQL CVS does not, by default, overwrite your local changes with global ones. Therefore, if you have a new remote control with some new buttons that we have not yet mapped, it is recommended that you e-mail us or post us a message in the forum, with the button name and the message and then we can add it to our master database and then your system can remain in sync with other users enhancements. If you want to do some mapping that is just for you, you can change the table and know your changes will not be overwritten.

You'll note that the RemoteMapping table has 2 optional fields: ScreenType and RemoteLayout. When the IRReceiverBase base class is deciding what message to send in response to button press, it first looks for a more specific entry where the screen type matches the type of screen currently visible on the orbiter, and the remote layout matches the layout. The on-screen orbiters regularly send messages to the infrared receiver telling them what type of screen is currently visible, using the following codes: M=Main Menu, m=other menu, R=LinuxMCE Remote, r=Non-LinuxMCE remote, F=File Listing. This allows for buttons to behave differently depending upon what type of screen is visible. For example when the main menu is visible, the arrows on a remote control should send a message to the on-screen orbiter to move the highlight pointer around on the screen. However when the user is controlling an external piece of AV equipment, like a DVD player, the arrows should pass through to the DVD player so the user can control its own on-screen menu. Also the type of functionality can vary depending upon the layout of the remote. For example, Bang & Olufsen remotes are quite simple, there is only a single up/down/left/right buttons which are used both to navigate on-screen menus as well as to handle rewind fast-forward and skip. Other remotes have dedicated arrows and media navigation buttons. So one remote layout can be created for Bang & Olufsen-style remote, where the arrows control the menu when there is a menu on screen, and adjust the media when there is not. The remote layout is a device data "#110 Remote Layout" stored with the remote control

When IRReceiverBase looks for a mapping it first looks for records that match the current screen type and remote layout, and then revert to standard records (ie ScreenType and RemoteLayout are null) only if there are no matching results.

See also Add support for new remote controls