Using an MCE remote control in Windows: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Jhsrennie
mNo edit summary
>Jhsrennie
No edit summary
Line 1: Line 1:
See [[Using a remote control with XBMC]] for general notes on remote controllers.<br />
Media Center remote controls fall into two classes, remotes compatible
See [[Using a Microsoft remote control in Windows]] for using the official Microsoft remote control.
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.


This article explains how you can make your generic MCE remote work
If you haven't already done so, you might want to look at the article
with XBMC. Note that this is only possible if your remote sends
[[Using a remote control with XBMC]] for some general notes on remote
keypresses when you press the buttons, or can be configured to send
controllers.
keypresses. Examples of remotes that are configurable include the
Microsoft remote and the various types of Logitech harmony remotes.


If you buy a cheap generic remote from eBay the chances are that it
The good news is that from XBMC v10.0 Dharma onwards most MCE remotes
does send keypresses. In fact it probably sends the standard Media
will just work with XBMC without needing any tweaking. The only reason
Centre keyboard shortcuts or the Microsoft multimedia keyboard media
for continuing with this article is if you find that some of the
keypresses, in which case it will work with XBMC out of the box and
buttons on your remote don't work or don't do what you want.
you need read no further. You only reason you need to persist with this
article is if your remote send non-MCE keystrokes, or more likely if
the remote has extra keys that you want to map to XBMC actions.


The essential steps are to work out what keypresses your remote control
== How MCE remotes work ==
is sending and edit keyboard.xml accordingly. The main part of this
article describes these steps.


== Getting started ==
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:


Start by grabbing a copy of mceremote.zip from
<ol>
http://xbmcmce.sourceforge.net/.
  <li>The remote can send the Windows message WM_APPCOMMAND. This
This zip is mainly intended for configuring the official MS remote, but
  message is used to send a multimedia application messages like "Play",
it contains a utility, ShowKey.exe, that is very useful for seeing what
  "Pause", "Stop" etc.<br>&nbsp;</li>
keypresses your remote is sending. Extract ShowKey.exe from the zip
and save it somewhere convenient.


You will need to create a custom keyboard.xml. Rather than starting
  <li>The remote can simulate multimedia key presses when you press a
from scratch I suggest you use the sample keyboard.xml in mceremote.zip.
  button. Multimedia keys were introduced with the Microsoft multimedia
The zip includes a batch file to copy the sample keyboard.xml to your
  keyboard, which has extra keys for multimedia functions like "Play"
userdata folder. Alternatively there is a copy of the sample keyboard.xml at
  etc.<br>&nbsp;</li>
[[Sample MCE remote keyboard.xml]].
Not only does this file contain useful examples, but you can
cut and paste the definitions in it to create new definitions. XBMC is
intolerant of typing mistakes in keyboard.xml, so the less typing the
better!


Finally you need to work out where you need to put your keyboard.xml
  <li>Finally the remote can simulate the standard MS Media Center
file. If you use Linux then your userdata folder is $home/.xbmc/userdata
  keyboard shortcuts. Many cheap MCE remotes simulate these keyboard
so the full path to your keyboard.xml file is
  shortcuts e.g. when you press the Play button they simulate the key
$home/.xbmc/userdata/keymaps/keyboard.xml.
  press control-shift-P. To use this type of remote an application has
  to process the Media Center key presses.</li>
</ol>


If you use Windows the situation is a bit more complicated because
XBMC handles all the common APPCOMMAND messages, and it handles all the
it depends on whether you installed XBMC in default mode or portable
Media Center keyboard shortcuts. XBMC handles some multimedia keyboard
mode. In portable mode the path to the file is
keypresses, but in any case Windows has a tendancy to convert
C:\Program&nbsp;Files\XBMC\userdata\keymaps\keyboard.xml. In default
multimedia keypresses into APPCOMMAND messages.
mode the file is in your profile, in
%APPDATA%\XBMC\userdata\keymaps\keyboard.xml, where APPDATA is an
environment variable. In both default and portable mode, if the
keymaps folder doesn't exist in your userdata folder just create
it.


A side note: if you are using the 64 bit versions of Windows replace
The only option available to you for configuring an MCE remote is to
C:\Program&nbsp;Files\ by C:\Program&nbsp;Files&nbsp;(x86)\. If you
modify the XBMC key mapping to make the key do what you want. For
didn't install XBMC into the Program&nbsp;Files folder then replace
example this remote,
C:\Program&nbsp;Files\XBMC\ by whatever directory you chose at
http://wiki.xbmc.org/?title=Remote_Control_Reviews#Unbranded_MCE_remote,
installation.
helpfully send 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.


== Identifying the keypresses ==
== Configuring your MCE remote ==


This section uses a Windows app I wrote to identify keypresses. I
There are two steps required:
don't have a Linux or OSX version of the app at the moment, though I
might in the future rewrite it in .Net/Mono or possibly Python/QT. For
Linux users the best course is to temporarily bow to Redwood and borrow
a Windows PC to test on.


If you haven't already done so, connect your remote and try it with
<ol>
XBMC. You may be surprised how many buttons work without any special
  <li>Work out what keypress your remote sends when you press a
configuration. Make a note of the buttons that do nothing and decide
  button</li>
what you want them to do.
  <li>Configure the XBMC keymapping to respond to that keypress</li>
</ol>


Now run ShowKey.exe and press a button on your remote. Assuming your
Step 1 is easy because there is an applet available to display
remote sends a keypress ShowKey will show you what the key is. For
keypresses. Grab a copy of the MCERemote addon from
example the Play button may send the MCE shortcut ctrl-shift-P, or it
http://xbmcmce.sourceforge.net/ and unzip it to some convenient
may send the multimedia keypress VK_MEDIA_PLAY_PAUSE. If Showkey
location. Look in the folder plugin.script.mceremote\resources\data
detects a keystroke it will display the line that needs adding to
and you'll find a program called ShowKey.exe. Run this application. You
keyboard.xml. For example, for ctrl-shift-P the line will be:
should find that ShowKey reports any key you press e.g. press the Q key
on the keyboard and ShowKey will report:


<pre>&lt;p mod="ctrl,shift"&gt;Put action here&lt;/p&gt;</pre>
<pre>KeyID  81 (0x51) - VK_Q</pre>


In this case you'd replace "Put action here" by <i>Play</i> so the
Press control-Q and you'll see:
line looked like:


<pre>&lt;p mod="ctrl,shift"&gt;Play&lt;/p&gt;</pre>
<pre>KeyID  81 (0x51) - VK_Q
Mod    Ctrl</pre>


And it's as simple as that. Work through all the keys and add the
The ShowKey applet also gives you the line of XML you need in your
corresponding lines to keyboard.xml.
keyboard.xml file, and this brings us to Step 2.


== Tips and tricks ==
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.


If ShowKey does not show any keypress when you press a button on the
The quickest way to edit your userdata keyboard.xml is to press
remote this means your remote is not sending a keypress. If you have a
Windows-R to open the Run dialog then type:
cheap non-configurable remote there's not much you can do about this.
With a universal remote, like the Logitech Harmony, see the manual for
the remote. For the MS remote see the separate article on
[[Using a Microsoft remote control in Windows]].


The green "Windows" button in the middle of the remote probably
<pre>notepad %appdata%\xbmc\userdata\keymaps\keyboard.xml</pre>
sends Windows-Alt-Enter, which is the standard Windows shortcut for
launching Windows Media Center. I don't know of any way to make this
key launch XBMC instead. Any suggestions gratefully received.


Update: There is a little program written by another helpful XBMC user
If you are prompted to create a new file answer "Yes".
available [http://inchoatethoughts.com/launching-xbmc-with-a-windows-media-center-remote here].
Basically it replaces ehshell.exe which is what the green button on the MCE remote launches. Once
the little program has been installed the green button will launch XBMC.


Remember you can test your config file by pressing keys on the
If you don't already have a keyboard.xml file copy and paste in this
keyboard as well as pressing buttons on the remote. Suppose you've
template:
added:


<pre>&lt;p mod="ctrl,shift"&gt;Play&lt;/p&gt;</pre>
<pre>&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;</pre>


but it isn't working. Well try pressing control-shift-P on the
As an example let's take the control-Q keystroke I mentioned above. When
keyboard. If it still doesn't work there's something wrong with your
you presscontrol-Q ShowKey generates the XML:
config file.


If an apparently perfect keyboard.xml file stubbornly isn't working,
<pre>&lt;q mod="ctrl"&gt;Notification(Key, q, 3)&lt;/q&gt;</pre>
turn on debugging in XBMC (Settings, System, Debugging and Enable
debug logging), start and stop XBMC and look at the xbmc.log file in
C:\Program&nbsp;Files\XBMC. Look for the lines:


<pre>INFO: load keymapping
Copy and paste this into your keyboard.xml, so it looks like:
INFO: Loading special://xbmc/system/keymaps/gamepad.xml
INFO: Loading special://xbmc/system/keymaps/joystick.AppleRemote.xml
INFO: Loading special://xbmc/system/keymaps/joystick.Harmony.xml
INFO: Loading special://xbmc/system/keymaps/joystick.Logitech.RumblePad.2.xml
INFO: Loading special://xbmc/system/keymaps/joystick.Microsoft.Xbox.Controller.S.xml
INFO: Loading special://xbmc/system/keymaps/joystick.WiiRemote.xml
INFO: Loading special://xbmc/system/keymaps/keyboard.xml
INFO: Loading special://xbmc/system/keymaps/remote.xml
INFO: Loading special://masterprofile/keymaps/keyboard.xml
INFO: Loading special://profile/keymaps/keyboard.xml</pre>


special://xbmc/system/keymaps/keyboard.xml is the system
<pre>&lt;keymap&gt;
keyboard.xml, which should always be there, and
  &lt;global&gt;
special://profile/keymaps/keyboard.xml is your keyboard.xml. If there
    &lt;keyboard&gt;
is no masterprofile or profile entry then XBMC isn't loading your
      &lt;!-- Put your key mappings here --&gt;
keyboard.xml so you probably put it in the wrong place. If you look at
      &lt;q mod="ctrl"&gt;Notification(Key, q, 3)&lt;/q&gt;
line 7 or thereabouts of the log file you should see:
    &lt;/keyboard&gt;
  &lt;/global&gt;
&lt;/keymap&gt;<pre>


<pre>NOTICE: special://masterprofile/ is mapped to: C:\Program Files\XBMC\userdata</pre>
Now start XBMC and press control-Q, and a little message should pop up
saying you've pressed "q".


and this will tell you where XBMC is looking for your
The key mappings are fairly obvious: in our example above the &lt;q&gt; means
keyboard.xml.
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:


Also look for any lines following the above that look like:
<pre>&lt;q mod="ctrl,alt"&gt;</pre>


<pre>ERROR: Error loading keymap: special://masterprofile/keymaps/keyboard.xml, Line 14
means the key control-alt-Q.
      Error reading end tag.</pre>


This tells you if XBMC found an error in your keyboard.xml file.
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 list of possible keys and actions ==
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
There is a list of all the XBMC key names that you can use in keyboard.xml in
[[List of XBMC keynames]].
[[List of XBMC keynames]].


There is a list of all the actions that you can use in keyboard.xml in the article
There is a list of all the actions that you can use in keyboard.xml in
[[List of Built In Functions]].
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 ==
== And finally ==


All this probably looks very complicated and you're wondering if it
That's about it. If your remote is one of those reviewed in the article
can't be made simpler. Well on my list of things to do is write a
[[Remote Control Reviews]] many of the reviews give you example key
utility for managing keyboard.xml files, so no more Notepad. Until then
mappings for the extra buttons on the remotes.
it isn't really that complicated. I've probably made it seem so by
 
ranting on in more detail than necessary. Anyhow if you run into any
If you run into any intractable problems please post in
problems please post in http://forum.xbmc.org/ and I'll
http://forum.xbmc.org/ and I'll try to answer there.
try to answer there.


[[category:Remote]]
[[category:Remote]]

Revision as of 11:06, 15 October 2010

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:

  1. The remote can send the Windows message WM_APPCOMMAND. This message is used to send a multimedia application messages like "Play", "Pause", "Stop" etc.
     
  2. 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.
     
  3. 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, http://wiki.xbmc.org/?title=Remote_Control_Reviews#Unbranded_MCE_remote, helpfully send 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:

  1. Work out what keypress your remote sends when you press a button
  2. 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 MCERemote addon from http://xbmcmce.sourceforge.net/ and unzip it to some convenient location. Look in the folder plugin.script.mceremote\resources\data and you'll find a program called ShowKey.exe. 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.

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:

<keymap>
  <global>
    <keyboard>
      <!-- Put your key mappings here -->
    </keyboard>
  </global>
</keymap>

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

<q mod="ctrl">Notification(Key, q, 3)</q>

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

<keymap>
  <global>
    <keyboard>
      <!-- Put your key mappings here -->
      <q mod="ctrl">Notification(Key, q, 3)</q>
    </keyboard>
  </global>
</keymap><pre>

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 <q> means
the mapping is for the key "q". The mapping starts with <q> and ends
with </q>. If you want to specify control, shift or alt you use
mod="ctrl,shift,alt" or any combination. For example:

<pre><q mod="ctrl,alt">

means the key control-alt-Q.

The bit in between <q> and </q> 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:

<keymap>

 <global>
   <keyboard>
     <!-- Put your key mappings here -->
     <q mod="ctrl">Notification(Key, q, 3)<q>
   </keyboard>
 </global>

</keymap>

in the <q mod="ctrl"> line i've omitted the "/" in the closing </q>. 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.