Using an MCE remote control in Windows: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Jhsrennie
mNo edit summary
mNo edit summary
 
(24 intermediate revisions by 8 users not shown)
Line 1: Line 1:
See [[Using a remote control with XBMC]] for general notes on remote controllers.
{{cleanup}}
See [[Using a Microsoft remote control in Windows]] for using the official Microsoft remote control.


This article explains how you can make your generic MCE remote work
Most IR Kodi 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
with XBMC. Note that this is only possible if your remote sends
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.
keypresses when you press the buttons, or can be configured to send
If you haven't already done so, you might want to look at the article [[Using an MCE remote]] for some general notes on remote 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 v10.0 Dharma onwards most MCE remotes will just work with Kodi 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.
does send keypresses. In fact it probably sends the standard Media
Centre keyboard shortcuts or the Microsoft multimedia keyboard media
keypresses, in which case it will work with XBMC out of the box and
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.


Assuming you've read [[Using a remote control with XBMC]] you will
know that the essential steps are to
work out what keypresses your remote control is sending and edit
keyboard.xml accordingly. The main part of this article describes these
steps.


== Getting started ==
== How MCE remotes work ==
The article [[Using an MCE remote]] 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
# The remote can send the Windows message WM_APPCOMMAND. This message is used to send a multimedia application messages like "Play", "Pause", "Stop" etc.
http://xbmcmce.sourceforge.net/.
# 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.
This zip is mainly intended for configuring the official MS remote, but
# 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.
it contains a utility, ShowKey.exe, that is very useful for seeing what
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
Kodi handles all the common APPCOMMAND messages, and it handles all the Media Center keyboard shortcuts. Kodi handles some multimedia keyboard keypresses, but in any case Windows has a tendancy to convert multimedia keypresses into APPCOMMAND messages.
from scratch I suggest you grab this
[[Sample MCE remote keyboard.xml]]
and save it into your userdata
folder. 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
The only option available to you for configuring an MCE remote is to modify the Kodi key mapping to make the key do what you want. The remainder of this article describes how to work out what keypress your remote is sending and how to configure Kodi to respond to it.
file. If you use Linux then your userdata folder is $home/.xbmc/userdata
so the full path to your keyboard.xml file is
$home/.xbmc/userdata/keymaps/keyboard.xml.


If you use Windows the situation is a bit more complicated because
it depends on whether you installed XBMC in default mode or portable
mode. In portable mode the path to the file is
C:\Program Files\XBMC\userdata\keymaps\keyboard.xml. In default
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
== Configuring your MCE remote ==
C:\Program Files\ by C:\Program Files (x86)\. If you
There are two steps required:
didn't install XBMC into the Program Files folder then replace
C:\Program Files\XBMC\ by whatever directory you chose at
installation.


== Identifying the keypresses ==
# Work out what keypress your remote sends when you press a button
# Configure the Kodi keymapping to respond to that keypress


This section uses a Windows app I wrote to identify keypresses. I
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.  
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
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:
XBMC. You may be surprised how many buttons work without any special
configuration. Make a note of the buttons that do nothing and decide
what you want them to do.


Now run ShowKey.exe and press a button on your remote. Assuming your
<pre>KeyID  81 (0x51) - VK_Q</pre>
remote sends a keypress ShowKey will show you what the key is. For
example the Play button may send the MCE shortcut ctrl-shift-P, or it
may send the multimedia keypress VK_MEDIA_PLAY_PAUSE. If Showkey
detects a keystroke it will display the line that needs adding to
keyboard.xml. For example, for ctrl-shift-P the line will be:


<pre>&lt;p mod="ctrl,shift"&gt;Put action here&lt;/p&gt;</pre>
Press control-Q and you'll see:


In this case you'd replace "Put action here" by <i>Play</i> so the
<pre>KeyID  81 (0x51) - VK_Q
line looked like:
Mod    Ctrl</pre>


<pre>&lt;p mod="ctrl,shift"&gt;Play&lt;/p&gt;</pre>
The ShowKey applet also gives you the line of XML you need in your keyboard.xml file, and this brings us to Step 2.


And it's as simple as that. Work through all the keys and add the
== Configuring your keyboard.xml ==
corresponding lines to keyboard.xml.


== Tips and tricks ==
Editing the keyboard.xml is described in [[HOW-TO:Modify_keymaps|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.


If ShowKey does not show any keypress when you press a button on the
Kodi 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\Kodi\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.
remote this means your remote is not sending a keypress. If you have a
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
The quickest way to edit your userdata keyboard.xml is to press Windows-R to open the Run dialog then type:
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.


Remember you can test your config file by pressing keys on the
<pre>notepad %appdata%\Kodi\userdata\keymaps\keyboard.xml</pre>
keyboard as well as pressing buttons on the remote. Suppose you've
added:


<pre>&lt;p mod="ctrl,shift"&gt;Play&lt;/p&gt;</pre>
If you are prompted to create a new file answer "Yes".


but it isn't working. Well try pressing control-shift-P on the
If you don't already have a keyboard.xml file copy and paste in this template:
keyboard. If it still doesn't work there's something wrong with your
config file.


If an apparently perfect keyboard.xml file stubbornly isn't working,
<pre><keymap>
turn on debugging in XBMC (Settings, System, Debugging and Enable
  <global>
debug logging), start and stop XBMC and look at the xbmc.log file in
    <keyboard>
C:\Program&nbsp;Files\XBMC. Look for the lines:
      <!-- Put your key mappings here -->
    </keyboard>
  </global>
</keymap></pre>


<pre>INFO: load keymapping
As an example let's take the control-Q keystroke I mentioned above. When you press control-Q ShowKey generates the XML:
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><q mod="ctrl">Notification(Key, q, 3)</q></pre>
keyboard.xml, which should always be there, and
special://profile/keymaps/keyboard.xml is your keyboard.xml. If there
is no masterprofile or profile entry then XBMC isn't loading your
keyboard.xml so you probably put it in the wrong place. If you look at
line 7 or thereabouts of the log file you should see:


<pre>NOTICE: special://masterprofile/ is mapped to: C:\Program Files\XBMC\userdata</pre>
Copy and paste this into your keyboard.xml, so it looks like:


and this will tell you where XBMC is looking for your
<pre><keymap>
keyboard.xml.
  <global>
    <keyboard>
      <!-- Put your key mappings here -->
      <q mod="ctrl">Notification(Key, q, 3)</q>
    </keyboard>
  </global>
</keymap></pre>


Also look for any lines following the above that look like:
Now start Kodi and press control-Q, and a little message should pop up saying you've pressed "q".


<pre>ERROR: Error loading keymap: special://masterprofile/keymaps/keyboard.xml, Line 14
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:
      Error reading end tag.</pre>


This tells you if XBMC found an error in your keyboard.xml file.
<pre><q mod="ctrl,alt"></pre>


== A list of possible keys and actions ==
means the key control-alt-Q.


There is a list of all the XBMC key names that you can use in keyboard.xml
The bit in between <q> and </q> is the action Kodi should take. In this example the "Notification" action pops up a message, which is useful only for debugging.
<a href="list_of_keys.html">here</a>.


There is a list of all the actions that you can use in keyboard.xml
A quick way to check what keys and actions are available is to open (but don't modify!) C:\Program Files\Kodi\system\keymaps\keyboard.xml as this has lots of useful examples.
<a href="list_of_actions.html">here</a>.


== And finally ==
There is a list of all the Kodi key names that you can use in keyboard.xml in [[List_of_keynames]].


All this probably looks very complicated and you're wondering if it
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|List of Built In Functions]].
can't be made simpler. Well on my list of things to do is write a
 
utility for managing keyboard.xml files, so no more Notepad. Until then
 
it isn't really that complicated. I've probably made it seem so by
== Troubleshooting ==
ranting on in more detail than necessary. Anyhow if you run into any
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.
problems please post in
 
<a href="http://forum.xbmc.org/">http://forum.xbmc.org/</a> and I'll
As an example suppose I make a deliberate mistake in my keyboard.xml:
try to answer there.
 
<pre>
<keymap>
  <global>
    <keyboard>
      <!-- Put your key mappings here -->
      <q mod="ctrl">Notification(Key, q, 3)<q>
    </keyboard>
  </global>
</keymap>
</pre>
 
in the <q mod="ctrl"> line i've omitted the "/" in the closing </q>. Now start Kodi and close it again, and examine the Kodi.log by pressing Windows-R and typing:
 
%appdata%\Kodi\Kodi.log
 
and search for the text "ERROR:". A few dozen lines down I find:
 
<pre>ERROR: Error loading keymap: special://masterprofile/keymaps/keyboard.xml, Line 6
            Error reading end tag.</pre>
 
which tells me what my mistake is.
 
You can also the debug log to tell you how Kodi is processing keypresses. Sticking with my example above of mapping control-Q, start Kodi, turn on debugging and press control-Q a few times. Close Kodi and open the debug log and search for the text SDLKeyboard. You should see:
 
<pre>DEBUG: SDLKeyboard: scancode: 16, sym: 113, unicode: 17, modifier: 40
DEBUG: CApplication::OnKey: 127057 pressed, action is Notification(Key, q, 3)</pre>
 
The SDLKeyboard line reports the keypress while the CApplication::OnKey line tells you what action Kodi took.
 
 
 
[[Category:Remotes]]

Latest revision as of 01:02, 10 September 2020

Cleanup.png This page or section may require cleanup, updating, spellchecking, reformatting and/or updated images. Please improve this page if you can. The discussion page may contain suggestions.


Most IR Kodi 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 an MCE remote for some general notes on remote controllers.

The good news is that from v10.0 Dharma onwards most MCE remotes will just work with Kodi 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 an MCE remote 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.

Kodi handles all the common APPCOMMAND messages, and it handles all the Media Center keyboard shortcuts. Kodi 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 Kodi key mapping to make the key do what you want. The remainder of this article describes how to work out what keypress your remote is sending and how to configure Kodi 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 Kodi 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.

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.

Kodi 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\Kodi\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%\Kodi\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 press control-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>

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

<q mod="ctrl,alt">

means the key control-alt-Q.

The bit in between and is the action Kodi 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\Kodi\system\keymaps\keyboard.xml as this has lots of useful examples.

There is a list of all the Kodi key names that you can use in keyboard.xml in List_of_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 line i've omitted the "/" in the closing . Now start Kodi and close it again, and examine the Kodi.log by pressing Windows-R and typing:

%appdata%\Kodi\Kodi.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 Kodi is processing keypresses. Sticking with my example above of mapping control-Q, start Kodi, turn on debugging and press control-Q a few times. Close Kodi 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 Kodi took.