Using an MCE remote control in Windows: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
m (Robot: Substituting template: Name)
mNo edit summary
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Media Center remote controls fall into two classes, remotes compatible
{{cleanup}}
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
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
[[Using a remote control with XBMC]] for some general notes on remote
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.
controllers.
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.


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


The article [[Using a remote control with XBMC]] describes the four
# The remote can send the Windows message WM_APPCOMMAND. This message is used to send a multimedia application messages like "Play", "Pause", "Stop" etc.
ways that MCE remotes work in Windows. There are few standards in the
# 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.
world of MCE remotes, so your remote might work in any combination of
# 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.
three ways:
 
<ol>
  <li>The remote can send the Windows message WM_APPCOMMAND. This
  message is used to send a multimedia application messages like "Play",
  "Pause", "Stop" etc.<br />&nbsp;</li>
 
  <li>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.<br />&nbsp;</li>


  <li>Finally the remote can simulate the standard MS Media Center
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.
  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.</li>
</ol>


XBMC handles all the common APPCOMMAND messages, and it handles all the
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.
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#Unbranded MCE remote]],
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 ==
== Configuring your MCE remote ==
There are two steps required:


There are two steps required:
# Work out what keypress your remote sends when you press a button
# Configure the Kodi keymapping to respond to that keypress


<ol>
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.
  <li>Work out what keypress your remote sends when you press a
  button</li>
  <li>Configure the XBMC keymapping to respond to that keypress</li>
</ol>


Step 1 is easy because there is an applet available to display
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:
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:


<pre>KeyID  81 (0x51) - VK_Q</pre>
<pre>KeyID  81 (0x51) - VK_Q</pre>
Line 77: Line 37:
Mod    Ctrl</pre>
Mod    Ctrl</pre>


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


== Configuring your keyboard.xml ==
== Configuring your keyboard.xml ==


Editing the keyboard.xml is described in [[Modifying keyboard.xml]].
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.
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
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.
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
The quickest way to edit your userdata keyboard.xml is to press Windows-R to open the Run dialog then type:
Windows-R to open the Run dialog then type:


<pre>notepad %appdata%\xbmc\userdata\keymaps\keyboard.xml</pre>
<pre>notepad %appdata%\Kodi\userdata\keymaps\keyboard.xml</pre>


If you are prompted to create a new file answer "Yes".
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
If you don't already have a keyboard.xml file copy and paste in this template:
template:


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


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


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


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


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


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


The key mappings are fairly obvious: in our example above the &lt;q&gt; means
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:
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:


<pre>&lt;q mod="ctrl,alt"&gt;</pre>
<pre><q mod="ctrl,alt"></pre>


means the key control-alt-Q.
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
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.
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.


A quick way to check what keys and actions are available is to open
There is a list of all the Kodi key names that you can use in keyboard.xml in [[List_of_keynames]].
(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 actions that you can use in keyboard.xml in the articles [[Action IDs]] and [[List_of_built-in_functions|List of Built In Functions]].
[[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 ==
== 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.
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:
As an example suppose I make a deliberate mistake in my keyboard.xml:


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


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


%appdata%\xbmc\xbmc.log
%appdata%\Kodi\Kodi.log


and search for the text "ERROR:". A few dozen lines down I find:
and search for the text "ERROR:". A few dozen lines down I find:
Line 188: Line 120:
which tells me what my mistake is.
which tells me what my mistake is.


You can also the debug log to tell you how XBMC is processing
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:
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:


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


The SDLKeyboard line reports the keypress while the CApplication::OnKey
The SDLKeyboard line reports the keypress while the CApplication::OnKey line tells you what action Kodi took.
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.


[[Category:Remotes]]
[[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.