Author: raffe
Date: 4 Apr 2011

Quick Links

• Main Forum Thread for plugin
• Forum thread (test cases)
• IR Server Suite (remote plugin)
• AutoHotkey (shortcut tool)

The Generic Keyboard Remote Input Plugin  or KeyboardInputPlugin allows you to map arbitrary key presses to MediaPortal actions, windows, etc. The main differences with the standard MediaPortal keyboard or remote handling are as follows:

• This plug-in takes the Ctrl, Alt, Shift and Win modifier keys into account
• This plug-in allows you to map key combinations not only to actions, but also to windows
• Configuration of this plug-in is similar to the standard MediaPortal Remote Plugin configurations

If you need to get remote buttons to work before MediaPortal has started, you can consider trying the AutoHotkey open source tool (scroll down to 'Other tools').

Background

In some cases the built-in support won't work for all remotes, or mappings you may want:

• Many remote controls act like an HID keyboard, where each button corresponds with a specific keystroke. Most remote controls send keystroke combinations that include Ctrl, Alt, Shift and sometimes Win modifier keys. For example, the Asus S-Presso remote control sends Ctrl-B for Replay, Ctrl-Shift-B for Rewind and Ctrl-Alt-Shift-B for Repeat buttons. This plug-in enables you to control MediaPortal using such a remote control.
   
• The standard MediaPortal key mapping mechanism doesn’t allow mapping keystrokes to windows. Using this plug-in, you can create keyboard shortcuts to specific MediaPortal screens - both built-in MediaPortal windows and plug-in windows.
   
• You may want to bind different actions to the same key depending on the context. For example in the Home screen you may want the number keys to act like a shortcut to various windows or actions, but have them act as regular number keys in all other screens. This is possible using the standard remote-like key mapping provided by this plug-in.
   
• You may want to bind different, possibly somewhat related actions to the same key depending on which modifier key is pressed. Using this plug-in, you can for example define ‘B’ as Back, Ctrl-B as Replay, Ctrl-Shift-B as Rewind, etcetera.

To solve this rsenden (*Ruud Senden)* and SilentException have made the Generic Keyboard/Remote Input Plugin to enable all this.

Other information

A message from the authors

"A MediaPortal forum thread about this plug-in is available at https://forum.team-mediaportal.com/generic_keyboard_remote_input_plugin-t25755.html. Please let me know there how this plug-in works for you, and whether you have any suggestions. Please also post your own Keyboard.xml file (from the MediaPortal application data directory) for specific remotes such that we can add it to the installation package."

Installation

The current version of the plug-in is 2.4.2.0. This version has been compiled for MediaPortal 1.1.0 but may work with other versions. For historical information, see history.html.

Installation via MediaPortal Extension Installer

The plug-in is available in the list of Known Extensions in the MediaPortal Extension Installer.

A quick explanation

1. Start the MediaPortal Extension Installer (MPEI).
2. Find the KeyboardInputPlugin extension in the list of known extensions. If you want to include (possibly newer) beta versions in your list, on the MPEI Options tab, do not check "Show only stable extensions".
3. Install the plug-in as usual, following the on-screen instructions.
4. After installation, the KeyboardInputPlugin configuration screen will be shown. Refer to the Overview and Usage section below for more information.

A more detailed explanation

1. Start MediaPortal Extension Installer. You can do that in two ways:
   • Find the icon, often in Start -> All Programs -> Team MediaPortal -> MediaPortal, the icon looks something like this:
   • Run MediaPortal Configuration -> Click on 'Plugins' -> and then click where it say 'Browse and install new plugins...'.
      
2. Click on the 'Known extensions' tab, find 'KeyboardInputPlugin *- Ruud Senden, SilentException'* and click on it.
    
3. To the left you click where you now see 'Install' and then you click where it say 'Version - 2.4.2.0 [Stable]' (or if this guide is old, you may see a newer version that you should choose).
   
   .
   • To see the latest version of KeyboardInputPlugin, you may first need to go to the Options tab and click on 'Download online update info' (see no 1 in the picture under this text) in MPEI (MediaPortal Extension Installer).
   • If you have previously installed KeyboardInputPlugin via MPEI, you may first need to go to the Options tab and click 'Clean installation cache' in MPEI (see no 2 in the picture under this text). The latest MPEI package can also be downloaded here.
      
4. Now MPEI tells you that the operation will install extension KeyboardInputPlugin and asks if you want to continue. If you do (and you should if you are following this guide), answer yes.
   
   .
5. Follow the Extension Installer for KeyboardInputPlugin. More or less you click a 'Next' button one time and then another 'Next' button again and after that you end the installer with a click on the 'Finish' button.
   • Now, wait a little for the Keyboard Mappings dialog to open.
   • If it does not open up, you can open it from MediaPortal Configuration >- Click on 'Plugins' -> Process Plugins -> click on 'Keyboard Input Plugin' -> click on 'Config' button.
      
6. Now the Generic Keyboard Remote Input Plugin is installed. Next step is to use it, please scroll down to Overview and Usage for more info about that part

Manual installation

 For manual installation, you can choose one of the following packages:

• KeyboardInputPlugin version 2.4.2.0 from SVN repo
• KeyboardInputPlugin version 2.4.0.0 from SVN repo
• KeyboardInputPlugin latest SVN version

1. Copy the Release\plugins\process\KeyboardInputPlugin.dll file to the <MediaPortal install dir>\plugins\process directory.
2. Several predefined Keyboard.xml files are available in the Release\InputDeviceMappings\examples
   * folders. Copy one of these files, corresponding to your intended use, to the <MediaPortal install dir>\InputDeviceMappings\default directory.
3. Depending on the Keyboard.xml file you chose in the previous step, additional configuration may be required. You can add button definitions and configure the button mappings by using the MediaPortal Configuration program. Refer to the ‘Plug-in Configuration’ section below for more information.

Information for Windows 7 users

Windows 7 sometimes automatically disables the keyboard hook if it doesn’t respond in time (for example due to high CPU load). Usually the plug-in will automatically recover from this situation and restart the hook. However, the plug-in may miss one or more keystrokes before being able to recover. If this is a problem for you (for example because the hook is disabled quite frequently), you can try the following registry change:

1. Open regedit and go to: HKEY_CURRENT_USER\Control Panel\Desktop\
2. Change/create: "LowLevelHooksTimeout" as DWORD and set the value to "5000", then reboot. Remember to backup the old key value, if any.
3. You can also experiment with the key value from 500 to 10000.

If you suffer from this problem a lot, please let us know on the forum thread (see below) so we can try to implement additional workarounds.

Overview

An explanation of the Plug-In configuration

Button definitions and mappings can be updated via the plug-in configuration screen. This screen is available via MediaPortal Configuration >- Click on 'Plugins' -> Process Plugins -> click on 'Keyboard Input Plugin' -> click on 'Config' button. Configuration is quite similar to the standard remote control configuration screens included in MediaPortal. By selecting a button node, you can add, remove or re-arrange actions for that specific button. Please refer to the regular MediaPortal Remote Control Configuration documentation for more information.

The main difference compared to the standard remote control configuration screens is that you can add new button definitions and modify existing ones. Buttons are defined by a button name and a button code. The button name can be any name you like. The button code is a special code that corresponds to a specific keystroke combination. However, usually the button code is generated (learned) automatically.

In order to modify the button name or button code for a newly created or existing button, you can use the ‘Key/Button Definition’ section near the upper right corner of the configuration window.

1. By selecting the root node and pressing the 'New' button, you can add a new mapping definition. The mapping name for the currently selected mapping can be changed in the 'Mapping Definition' section on the right.
   By selecting a mapping node and pressing the 'New' button, you can add a new button definition to the mapping. For each button definition, you can enter the details in the 'Key/Button Definition' section on the right.
   Once you've defined a button that you would like this plug-in to handle, you can add, remove or modify its mappings to MediaPortal windows, actions and so on.
    
2. Here you can enter a name that describes your mapping definition, for example the name of the remote control that this mapping applies to.
    
3. Using this section, you can define a key or a button definition. A definition contains a name that identifies the button or key combination, and the actual key or button.
    
4. Here you can enter a name that describes your button or key combination.
    
5. Click in this field and press the remote control button or key combination that you would like to assign to this key/button definition.
    
6. Using this section, you can select a layer.
    
7. Using this section, you can provide a condition for the action to be active.
    
8. Using the Action section you can define the action to perform when the user presses the given key combination or button, if the given condition is true.  See References > Actions for a list of the actions supported in MediaPortal.
    
9. Use the Up and Down buttons to re-order items
    
10. Depending on selection in the tree list above, the  'New' button allows you to create a new Mapping definition, a new Key/Button definition, a new layer, or a new condition.
     
11. Remove the currently selected item from the tree.
     
12. Import mapping definitions from a mappings XML file into your current mapping. You can use this to load predefined mappings.
     
13. Reset the mappings to defaults; this will remove all mappings and if <ProgramDir>\CustomInputDevices\defaults\Keyboard.xml exists, reload the mappings from that file.
     
14. Save any changes, keep the configuration window open.
     
15. Save any changes & close the configuration window.
     
16. Cancel - close the window without saving any changes you may have made.

Usage

Here is the official thread for this plugin: https://forum.team-mediaportal.com/mediaportal-plugins-47/generic-keyboard-remote-input-plugin-25755/

Here is a thread where this has been tried out: https://forum.team-mediaportal.com/remotes-116/solved-yet-another-mpc-remote-back-green-button-problem-94973/

Example - Import mapping definitions

You can Import mapping definitions from mappings XML file into your current mapping. You can use this to load predefined mappings.

1. Open the 'Keyboard Input Plugin' configuration dialog, go to MediaPortal Configuration >- Click on 'Plugins' -> Process Plugins -> click on 'Keyboard Input Plugin' -> click on 'Config' button.
2. Click on the 'Import' button
3. Now it opens a dialog that as standard it goes to a folder similar to C:\Program\Team MediaPortal\MediaPortal\InputDeviceMappings\defaults\KeyboardInputPlugin\. It looks something like this:
   
    
4. In the Keyboard folder you have something like this you can choose from:
   
    
5. In the Remote folder you have something like this you can choose from:
   
    
6. Say you go to the Remote\MCE-Remote based mappings folder, then you will see something like this:
   
    
7. If you click on Keyboard.xml and then on 'Open' button, you will see something like this on your screen:
   
    
8. If you click on a + you will open that mapping node. As an example, if you click on the + in front of Generic Button, you will see something like this:
   

Example - Edit and make your own mappings

Say you have gone to Remote\MCE-Remote based mappings and imported the Keyboard.xml and now want to remap the Back button on your remote.

1. Open the 'Keyboard Input Plugin' configuration dialog, go to MediaPortal Configuration >- Click on 'Plugins' -> Process Plugins -> click on 'Keyboard Input Plugin' -> click on 'Config' button.
2. Open Mappings -> Generic Buttons -> Back and click on Back (see no 1 in the picture under this ordered list).
3. Click in the "Key:" text box (see no 2 in the picture under this ordered list) and then push the "Back" button on the remote. The text box should now change from None to 'something' your remote sends, maybe Back (in "Key:" text box, see no 2 in the picture under this ordered list).
4. Click on the Save & Close button.
5. Try if the button works.

Other Tools

AutoHotKey

In some cases, such as to use the Windows button to start MediaPortal, you can't use the Generic Keyboard/Remote Input Plugin because the plugin starts after MediaPortal has started. Then you can try to use a open source tool called AutoHotkey, see http://en.wikipedia.org/wiki/AutoHotkey for more info.

*** Check what the Windows button sends to the PC

1. Start MediaPortal Configuration ("C:\Program\Team MediaPortal\MediaPortal\Configuration.exe") and enter 'Keyboard Input Plugin' configuration dialog, go to MediaPortal Configuration >- Click on 'Plugins' -> Process Plugins -> click on 'Keyboard Input Plugin' -> click on 'Config' button.
    
2. Open any mapping to test Windows button (maybe Mappings - Generic Buttons - Back and click on Back, see no 1 in the picture above)
    
3. Click in the "Key:" text box (see no 2 in the picture above) and then push the "Windows" button on the remote. On my PC it now say Alt+Win+Enter (in "Key:" text box). Write this down!
    
4. ****NOTE, read this!!!* Now you click on the *Cancel* button!
   Above was just a test, we do not want to save it! Generic Keyboard/Remote Input Plugin starts up AFTER MediaPortal has started, so it will not work when MediaPortal is not running.

*** Set up AutoHotkey to use the Windows button input to start MediaPortal

1. Go to AutoHotkey Download and then install it (I used "Installer for AutoHotkey Basic").
    
2. Now you have to map the keys you remote sends to the action you want. As an example, in the AutoHotkey.ahk script file I added this line (!#Enter = Alt+Win+Enter, you find info about key codes in AutoHotkey Tutorial: Macro and Hotkey Creation and List of Keys and Mouse/Joystick Buttons for Hotkeys and Macros):
   !#Enter::Run C:\Program\Team MediaPortal\MediaPortal\MediaPortal.exe
    
3. Save and then start AutoHotkey.
    
4. Now the Windows button on the remote should work (it starts MediaPortal).

License & Disclaimer

Copyright (C) 2007-2010 Ruud Senden | SilentException

This Program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This Program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Use this program at your own risk, I can not be held responsible for any damage.

You should have received a copy of the GNU General Public License along with this program; see the file COPYING.  If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. http://www.gnu.org/copyleft/gpl.html