Using an MCE remote control in Windows

Media Center remote controls fall into two classes, remotes compatible with the Microsoft remote (also known as RC6 or eHome remotes) and remotes that send Media Centre keyboard shortcuts. If you have a Microsoft remote (or a compatible such as the Asrock, HP or Mediagate) see the article Using a Microsoft remote control in Windows. This article discusses the remotes that send MCE keyboard shortcuts.

If you haven't already done so, you might want to look at the article Using a remote control with XBMC for some general notes on remote controllers.

The good news is that from XBMC v10.0 Dharma onwards most MCE remotes will just work with XBMC without needing any tweaking. The only reason for continuing with this article is if you find that some of the buttons on your remote don't work or don't do what you want.

How MCE remotes work
The article Using a remote control with XBMC describes the four ways that MCE remotes work in Windows. There are few standards in the world of MCE remotes, so your remote might work in any combination of three ways:

 The remote can send the Windows message WM_APPCOMMAND. This message is used to send a multimedia application messages like "Play", "Pause", "Stop" etc. 

The remote can simulate multimedia key presses when you press a button. Multimedia keys were introduced with the Microsoft multimedia keyboard, which has extra keys for multimedia functions like "Play" etc. 

Finally the remote can simulate the standard MS Media Center keyboard shortcuts. Many cheap MCE remotes simulate these keyboard shortcuts e.g. when you press the Play button they simulate the key press control-shift-P. To use this type of remote an application has to process the Media Center key presses. 

XBMC handles all the common APPCOMMAND messages, and it handles all the Media Center keyboard shortcuts. XBMC handles some multimedia keyboard keypresses, but in any case Windows has a tendancy to convert multimedia keypresses into APPCOMMAND messages.

The only option available to you for configuring an MCE remote is to modify the XBMC key mapping to make the key do what you want. For example this remote, Remote Control Reviews, helpfully sends a control-alt-F1 keypress when you press the My Music button, and this conforms to no standard that I know of! The remainder of this article describes how to work out what keypress your remote is sending and how to configure XBMC to respond to it.

Configuring your MCE remote
There are two steps required:

 Work out what keypress your remote sends when you press a button Configure the XBMC keymapping to respond to that keypress 

Step 1 is easy because there is an applet available to display keypresses. Grab a copy of the Showkey applet from http://xbmcmce.sourceforge.net/. ''On Linux, you can skip the grab part and run showkey program as root. Use your favorite package manager to find the right package to install. On Debian, install kbd package. [JR 29/11/10 - is this true? My ShowKey applet only works on Windows. Is there an unrelated applet called Showkey on Linux?]'' Run this application. You should find that ShowKey reports any key you press e.g. press the Q key on the keyboard and ShowKey will report:

KeyID 81 (0x51) - VK_Q

Press control-Q and you'll see:

KeyID 81 (0x51) - VK_Q Mod   Ctrl

The ShowKey applet also gives you the line of XML you need in your keyboard.xml file, and this brings us to Step 2.

Configuring your keyboard.xml
Editing the keyboard.xml is described in Modifying keyboard.xml. The remainder of this article specifically addresses creating entries for MCE remotes. The article describes using Notepad to modify keyboard.xml, but there is a keymap editor available from http://xbmcmce.sourceforge.net/ or it's included in the MCERemote addon.

XBMC uses a key mapping file called keyboard.xml to determine how it should respond to key presses. There is a system keyboard.xml in C:\Program Files\XBMC\system\keymaps, and you should normally leave this alone. You need to create a personal keyboard.xml in your userdata folder and update this file with your customised key mappings.

The quickest way to edit your userdata keyboard.xml is to press Windows-R to open the Run dialog then type:

notepad %appdata%\xbmc\userdata\keymaps\keyboard.xml

If you are prompted to create a new file answer "Yes".

If you don't already have a keyboard.xml file copy and paste in this template:

&lt;keymap&gt; &lt;global&gt; &lt;keyboard&gt; &lt;!-- Put your key mappings here --&gt; &lt;/keyboard&gt; &lt;/global&gt; &lt;/keymap&gt;

As an example let's take the control-Q keystroke I mentioned above. When you press control-Q ShowKey generates the XML:

&lt;q mod="ctrl"&gt;Notification(Key, q, 3)&lt;/q&gt;

Copy and paste this into your keyboard.xml, so it looks like:

&lt;keymap&gt; &lt;global&gt; &lt;keyboard&gt; &lt;!-- Put your key mappings here --&gt; &lt;q mod="ctrl"&gt;Notification(Key, q, 3)&lt;/q&gt; &lt;/keyboard&gt; &lt;/global&gt; &lt;/keymap&gt;

Now start XBMC and press control-Q, and a little message should pop up saying you've pressed "q".

The key mappings are fairly obvious: in our example above the &lt;q&gt; means the mapping is for the key "q". The mapping starts with &lt;q&gt; and ends with &lt;/q&gt;. If you want to specify control, shift or alt you use mod="ctrl,shift,alt" or any combination. For example:

&lt;q mod="ctrl,alt"&gt;

means the key control-alt-Q.

The bit in between &lt;q&gt; and &lt;/q&gt; is the action XBMC should take. In this example the "Notification" action pops up a message, which is useful only for debugging.

A quick way to check what keys and actions are available is to open (but don't modify!) C:\Program Files\XBMC\system\keymaps\keyboard.xml as this has lots of useful examples.

There is a list of all the XBMC key names that you can use in keyboard.xml in List of XBMC keynames.

There is a list of all the actions that you can use in keyboard.xml in the articles Action IDs and List of Built In Functions.

Troubleshooting
About the only thing that can go wrong is if you make a mistake in your keyboard.xml. The easy way to check this is to turn on debug logging and check your log file. To turn on debug logging go to the settings and select System, then Debugging, then enable Enable debug logging. When you turn on debug logging you'll see some text at the top of the screen showing various info such as CPU usage. This is a quick way to tell if debug logging is on.

As an example suppose I make a deliberate mistake in my keyboard.xml:

&lt;keymap&gt; &lt;global&gt; &lt;keyboard&gt; &lt;!-- Put your key mappings here --&gt; &lt;q mod="ctrl"&gt;Notification(Key, q, 3)&lt;q&gt; &lt;/keyboard&gt; &lt;/global&gt; &lt;/keymap&gt;

in the &lt;q mod="ctrl"&gt; line i've omitted the "/" in the closing &lt;/q&gt;. Now start XBMC and close it again, and examine the xbmc.log by pressing Windows-R and typing:

%appdata%\xbmc\xbmc.log

and search for the text "ERROR:". A few dozen lines down I find:

ERROR: Error loading keymap: special://masterprofile/keymaps/keyboard.xml, Line 6 Error reading end tag.

which tells me what my mistake is.

You can also the debug log to tell you how XBMC is processing keypresses. Sticking with my example above of mapping control-Q, start XBMC, turn on debugging and press control-Q a few times. Close XBMC and open the debug log and search for the text SDLKeyboard. You should see:

DEBUG: SDLKeyboard: scancode: 16, sym: 113, unicode: 17, modifier: 40 DEBUG: CApplication::OnKey: 127057 pressed, action is Notification(Key, q, 3)

The SDLKeyboard line reports the keypress while the CApplication::OnKey line tells you what action XBMC took.

And finally
That's about it. If your remote is one of those reviewed in the article Remote Control Reviews many of the reviews give you example key mappings for the extra buttons on the remotes.

If you run into any intractable problems please post in http://forum.xbmc.org/ and I'll try to answer there.