Kodi Keymap Files

Kodi control with the Harmony 1100

I have a Harmony 1100 Remote Control which I bought when I had nearly a dozen different devices that I wanted to control (cable boxes and several tivos, as well as tv, receiver, dvd player, vcr, etc). I don’t have most of this stuff anymore, since I dumped the cable and started using Kodi. So I could probably live without the Harmony Remote, but I paid a lot of money for it, so I want it to work correctly. A big part of this project, therefore, was figuring out how to get that remote to control Kodi properly. I also wanted to improve the handling of keyboards, and understand better how I could use the configuration capabilities in Kodi to get better control.

The Harmony remote software for the Harmony 1100 permits assigning to each hard button or touchscreen button, a “command”, and a “device” to which the command applies.

When a “device” is set up for control by the Harmony remote, one selects what type of device it is from the Harmony database. The database has various device types (tv, dvd player etc), including one called Media Center PC. Within each device type there are a number of specific “devices” with manufacturer (Sony, Samsung) and model number. For the device type Media Center PC, there is a manufacturer “Plex” and model “Plex Player”. There are other “manufacturers” in the database that look promising (like “kodi”), but they turn out not to have anything useful in them. The only one that has been useful for me is the one called “Plex”.

The database for a device, in this case “Plex”, has a set of what it calls “commands”, which to the user look like “Play”, “Pause”, “F3”, “Channel Up”, etc. When configuring the buttons on the remote, one can choose from that offered set of commands, and no others. For other devices with manufacturer supplied remote controls, one can create ones own “commands” by having the harmony app learn from the remote, but since there is no manufacturer supplied physical remote control for Kodi, the commands in the database are the only ones which can be assigned. One has to make do with the set of commands which are provided.

For example there is a button on the Harmony Remote called “mute”. One can associate that with any command for any device. So, reasonably, one could associate that button with the Plex device’s “Mute” command. Alternatively, one could associate that same button with the mute command to the receiver, or to the television. For the plex device there is no further information from Harmony about what the so called “commands” actually send; i.e what is actually received by the ir receiver on the computer running Kodi, and what ultimately shows up in Kodi. This is ok for most of the “commands”, like play, stop, “one”, etc, because the mapping seems correct and they simply work as expected. But there are commands in the database for which the mapping isn’t so clear. For example, the database has commands called “Large Up” and “Skip Forward” but it isn’t clear what either is supposed to do, if anything, or whether they are different. It sends something to Kodi, but what?

The Kodi “keymap” files are xml files that associate incoming “key presses” or infrared commands with actions to be taken by Kodi. A keymap file is xml, with each section describing a context (like a particular kodi page, or kodi activity, e.g., the home page, or the login screen, or a music playlist, or playing full screen video). This enables a keypress or ir-code to mean different things in different Kodi contexts. One context called “global” is the “default”, which is used whenever a key definition is not defined in the current context. So, for example, if the “direction up” key or button is pressed it will, by default, do navigation through the menus, but if pressed while a movie is playing (on the FullScreenVideo page) it means to skip forward in the movie.

Within each page/context, one can describe key mappings for different devices. For example, within the fullscreenvideo page, the “x” key on the keyboard should stop the movie; but on the remote the “stop” key should stop the movie. So a single keymap file can describe the mapping for all pages and multiple devices.

Within the kodi system files, there are keymap files for each different device: one for the keyboard, one for “the remote”, and several which are titled “joystick-something”. Some of the joystick files are for game console controllers, and some are actually remotes, like the Harmony remote. The keymap file called “Joystick.Harmony.xml” is the one which actually describes the Harmony remote, and which will be used when the Kodi system->settings value for system->input device is set to Harmony Remote instead of something else. Having separate files for different devices is helpful for maintenance, but isn’t really necessary since a single keymap file can describe all the devices.

Kodi comes with a set of standard keymap files, but the user can create custom keymap files and put them in the individual user’s userdata/keymap directory with entries which will override the standard files. The custom files are overrides, so they only need to contain changes to the standard files, and whatever is not in the local keymap file is obtained from the standard system files. Furthermore, since one keymap file can describe the controls for all the devices, one need only have a single “personal” keymap file.

The attached spreadsheet (Key Mapping in Kodi, below) contains the mapping of the Harmony database commands associated with the plex device, and what is actually received in Kodi, as well as the default actions taken by Kodi. The file also contains the keypress mappings for a general keyboard. Not every keyboard has all the keynames defined, for example, the file has key names like “launch browser” or “email” which are on some fancy keyboards.

The keymap I am using is below (My keymap file), but note that if downloaded it will download as a file “mykeymap.reallyxml.txt” and the name must be changed on your system to “mykeymap.xml”. WordPress won’t let me have a file with a suffix of xml.

Key Mapping in Kodi

My Keymap file