Le Galérien: XBMC and your TV remote can be friends

Installing and deploying an XBMC distribution on a Raspberry Pi (Pi) is pretty easy. Once plugged to a TV, you may also be surprised by the ability to navigate the XBMC menus with your TV remote, out-of-the-box. Or may be not? Then you may want to read further.

How does it work?

All the magic happens thanks to the HDMI CEC feature. CEC stands for Consumer Electronic Control and is is charge of transmitting control signals between devices linked by HDMI wires.

For the records, it uses the pin #13 of the HDMI standard connector (more details on Wikipedia). Lucky number.

In our case, it makes possible for a TV and Raspberry Pi to send each others control signals, as soon as they are connected together via a HDMI cable and both implement the HDMI CEC features.

From the TV remote to the Pi

More details to understands what happens under the hood

Both the TV and the Pi are CEC enabled, it means they can send and receive CEC signals through the HDMI wire.

The schema above illustrate a very common use case:

One presses a button on the TV remote (e.g. the Play media button). Nothing to do with CEC so far, rather InfraRed in most TV remotes cases.
The TV receives the signal and may decide to forward it to the HDMI connected Pi. It triggers a CEC signal (e.g. a Play media signal) which is sent to the Pi.
The Pi receives the CEC signal and takes action according to the current context (e.g. starts to play the current selected movie)

This explains how you can control XBMC running on your Pi using your TV remote. Essentially, good guys have taken care of implementing the CEC feature in XBMC, while other good guys have done the same in your TV hardware.

However the communication goes both ways so the Pi can also send signals to the TV. This come handy when the Pi changes its state, like getting into energy saving mode or shutting down: it may send a CEC signal to the TV asking it to go stand-by or to shut down as well.

Obviously none of the devices on the HDMI chain can force another one to do anything, it's all up to the way each device constructor/programmer has implemented the CEC routine. It's more like each device can send and receive whatever CEC signals and will act according to their own CEC implementation upon reception of a CEC signal.

Practical case: TV + Remote + XBMC = ?

You can spare yourself the suspens by searching your TV manual for CEC information. Each constructor may have renamed/rebranded it though. Here is a list picked from CEPro:

Brand	CEC Branding
Hitachi	Plain old HDMI-CEC
LG Electronics	SimpLink
Panasonic	Viera Link (originally EZSync)
Philips	Easy Link
Samsung	Anynet+
Sharp	Aquos Link
Sony	Bravia Sync
Toshiba	Regza Link (formerly CE-Link)

If you're not keen on reading your TV manual, then you may give it a try and see straight away: plug your enabled XBMC Pi (e.g. using Raspbmc) to your TV and turn them on.

CEC TV side should activate automatically when an HDMI device source is selected.
XBMC's CEC drivers on the Pi will kick-in straight away, showing a toast notification.

Just grab your remote and try the buttons, e.g. play with the arrows and see if it switch the menus in XBMC. In case it doesn't work, please note that punching the buttons harder doesn't work better (I've been through that, once) and may damage the remote, possibly yourself too.

Going further with the TV remote

You should now be aware of what to expect from your TV remote with XBMC, either one of those 3 cases:

Your TV is CEC compliant and your remote works like a charm, you don't miss any functionality: lucky you, you don't even need to read those lines.
Your TV is CEC compliant and your remote has a few buttons recognised by XBMC out-of-the-box, however it misses a few functionalities: bare with me, the next section may be of some help.
Your TV is not CEC compliant: forget your TV remote and have a look to this Pi IR receiver. It's cheap and funny to put in place, but out of the scope of this article. You also have the option of WiFi XBMC remotes apps for smartphones. This one for Android rocks.

If you wish to customise your TV remote for XBMC you need to dig a bit further to achieve your goals. Fortunately this won't involve any coding neither compiling, the nice guys behind XBMC have built an easy-to-use XML mapping for all supported remote devices.

Know your buttons

The first step is to identify the buttons triggering CEC signals which are recognised by XBMC on the Pi. Assuming we are logged-in as root onto your Pi's Bash, there are two distinct approaches to this (note they're not exclusive):

The hardcore and straight-forward approach

A quick way to check what TV remote buttons are caught by XBMC looking at its raw logs.

Turn XBMC logs to DEBUG level. To do so, edit the XBMC advanced settings file:
```
vi /opt/xbmc-bcm/xbmc-bin/share/xbmc/system/advancedsettings.xml
```
If the file is empty (it may not exist already depending on your XBMC distribution), simply fill it with the following:
```
<advancedsettings>
  <loglevel hide="false">1</loglevel> 
</advancedsettings>
```
As it is more likely you've got some content already into the config file, simply add a new line with:
```
<loglevel hide="false">1</loglevel>
```
straight after the line matching
```
<advancedsettings>
```
Monitor XBMC logs live. Enter this command which will refresh and filter the XBMC debug log file live:
```
tail -f /home/pi/.xbmc/temp/xbmc.log | grep -iE "onkey" --color=always
```
Then leave your console as it is. tail -f is in charge of displaying new lines from the log file /home/pi/.xbmc/temp/xbmc.log, then we pipe this flow to grep to display only the lines containing the pattern "onkey". The option --color=always allows to highlight the characters grep has matched.
Play with your TV remote when XBMC is running so you can see the live log fed with entries showing which of the TV remote buttons you've pressed are actually recognised by XBMC. You should see something like this on each successful occurrence:
```
01:55:38 T:3040153600   DEBUG: OnKey: 168 (a8) pressed, action is Notification(Keypress, right, 1)
01:55:39 T:3040153600   DEBUG: OnKey: 166 (a6) pressed, action is Notification(Keypress, up, 1)
01:55:40 T:3040153600   DEBUG: OnKey: 169 (a9) pressed, action is Notification(Keypress, left, 1)
01:55:41 T:3040153600   DEBUG: OnKey: 167 (a7) pressed, action is Notification(Keypress, down, 1)
01:55:44 T:3040153600   DEBUG: OnKey: 11 (0b) pressed, action is Notification(Keypress, select, 1)
```
Where each end of line shows "Notification(Keypress, <button_name>, 1)", <button_name> being the name assigned by XBMC to the button you pressed on your TV remote.
E.g. at line #1, <button_name> = right, meaning the button you pressed on your TV remote to display that line of log is bound to XBMC remote as the right button.

The soft and visual approach

A user-friendly way to check what TV remote buttons are caught by XBMC looking at the on-screen toast notifications.

Edit the XBMC remote key mapping, remote.xml, so each action taken on one of the TV remote button recognised by XBMC triggers an on-screen toast notification instead of the initial action it was intended to. We first back the config file up:
```
cp /opt/xbmc-bcm/xbmc-bin/share/xbmc/system/keymaps/remote.xml /opt/xbmc-bcm/xbmc-bin/share/xbmc/system/keymaps/remote.xml.backup
```

Now we can edit the remote.xml file:

vi /opt/xbmc-bcm/xbmc-bin/share/xbmc/system/keymaps/remote.xml

Replace its whole content with the following:

<!-- Mapping all the supported remote buttons to a toast notification presenting the button name -->
<keymap>
  <global>
    <remote>
      <left>Notification(Keypress, left, 1)</left>
      <right>Notification(Keypress, right, 1)</right>
      <up>Notification(Keypress, up, 1)</up>
      <down>Notification(Keypress, down, 1)</down>
      <select>Notification(Keypress, select, 1)</select>
      <back>Notification(Keypress, back, 1)</back>
      <menu>Notification(Keypress, menu, 1)</menu>
      <info>Notification(Keypress, info, 1)</info>
      <display>Notification(Keypress, display, 1)</display>
      <title>Notification(Keypress, title, 1)</title>
      <play>Notification(Keypress, play, 1)</play>
      <pause>Notification(Keypress, pause, 1)</pause>
      <reverse>Notification(Keypress, reverse, 1)</reverse>
      <forward>Notification(Keypress, forward, 1)</forward>
      <skipplus>Notification(Keypress, skipplus, 1)</skipplus>
      <skipminus>Notification(Keypress, skipminus, 1)</skipminus>
      <stop>Notification(Keypress, stop, 1)</stop>
      <zero>Notification(Keypress, zero, 1)</zero>
      <one>Notification(Keypress, one, 1)</one>
      <two>Notification(Keypress, two, 1)</two>
      <three>Notification(Keypress, three, 1)</three>
      <four>Notification(Keypress, four, 1)</four>
      <five>Notification(Keypress, five, 1)</five>
      <six>Notification(Keypress, six, 1)</six>
      <seven>Notification(Keypress, seven, 1)</seven>
      <eight>Notification(Keypress, eight, 1)</eight>
      <nine>Notification(Keypress, nine, 1)</nine>
      <!-- additional keys from the media center extender for xbox remote -->
      <power>Notification(Keypress, power, 1)</power>
      <mytv>Notification(Keypress, mytv, 1)</mytv>
      <mymusic>Notification(Keypress, mymusic, 1)</mymusic>
      <mypictures>Notification(Keypress, mypictures, 1)</mypictures>
      <myvideo>Notification(Keypress, myvideo, 1)</myvideo>
      <record>Notification(Keypress, record, 1)</record>
      <start>Notification(Keypress, start, 1)</start>
      <volumeplus>Notification(Keypress, volumeplus, 1)</volumeplus>
      <volumeminus>Notification(Keypress, volumeminus, 1)</volumeminus>
      <channelplus>Notification(Keypress, channelplus, 1)</channelplus>
      <channelminus>Notification(Keypress, channelminus, 1)</channelminus>
      <pageplus>Notification(Keypress, pageplus, 1)</pageplus>
      <pageminus>Notification(Keypress, pageminus, 1)</pageminus>
      <mute>Notification(Keypress, mute, 1)</mute>
      <recordedtv>Notification(Keypress, recordedtv, 1)</recordedtv>
      <guide>Notification(Keypress, guide, 1)</guide>
      <livetv>Notification(Keypress, livetv, 1)</livetv>
      <liveradio>Notification(Keypress, liveradio, 1)</liveradio>
      <epgsearch>Notification(Keypress, epgsearch, 1)</epgsearch>
      <star>Notification(Keypress, star, 1)</star>
      <hash>Notification(Keypress, hash, 1)</hash>
      <clear>Notification(Keypress, clear, 1)</clear>
      <enter>Notification(Keypress, enter, 1)</enter>
      <xbox>Notification(Keypress, xbox, 1)</xbox>
      <playlist>Notification(Keypress, playlist, 1)</playlist>
      <guide>Notification(Keypress, guide, 1)</guide>
      <teletext>Notification(Keypress, teletext, 1)</teletext>
      <red>Notification(Keypress, red, 1)</red>
      <green>Notification(Keypress, green, 1)</green>
      <yellow>Notification(Keypress, yellow, 1)</yellow>
      <blue>Notification(Keypress, blue, 1)</blue>
      <subtitle>Notification(Keypress, subtitle, 1)</subtitle>
      <language>Notification(Keypress, language, 1)</language>
    </remote>
  </global>
</keymap>

I've made this file up using an exhaustive list of the buttons recognised by XBMC as per its code (see the TranslateRemoteString method)

Restart XBMC (or simply turn the Pi off and on again)
Play with your TV remote when XBMC is running so you can see the on-screen notifications showing the actual button name bound with your TV remote button.

Below is an example of how it should look like when the select button of the TV remote is pressed (corresponding to the line #9 of the XML listing above):

If a button doesn't give a notification, then it means your TV doesn't forward it as an XBMC supported CEC signal. There is no much to do in that case, unfortunately.

Customize your TV remote buttons with XBMC

Now you know how each of your TV remote button is recognised by XBMC, it's time to make your own mapping.

To take a practical example, I had only the basic buttons of my LG TV remote recognised by XBMC, and I was missing some features like switching the subtitles or the audio track during a video playback.

As the navigation arrows on my remote were already taking care of skipping scenes back and forward, I decided to map the subtitle and audio functions respectively to the skip back (

) and skip forward (

) buttons of my TV remote.

To achieve such a remapping, you need to map your TV remote buttons as recognised by XBMC to the available XBMC actions. Their wiki give an exhaustive list of the available actions.

The default remote.xml file comes with several sections. The full structure is explained here, however I'll stick with two things for this example: mapping the TV remote buttons to an action in a context. By context I mean a specific window under XBMC, e.g. the general menus windows or the fullscreen playback window. By action I mean, well, an action like move left in a menu or play a video.

If I go back to my example, I want to make the following changes:

When in the general menus, I want the and buttons to map respectively to the XBMC.ActivateWindow(Home) and ContextMenu XBMC actions.
The former takes XBMC back to the Home window, while the latter shows a contextual menu, when available (the one you get with a mouse secondary-click)
When on a fullscreen movie playback, I want the and buttons to map respectively to the NextSubtitle and AudioNextLanguage XBMC actions.
The former rolls through the available subtitles (if any) and no subtitles, while the latter rolls through the available audio tracks, if any other than the main one.

The points above translate into the following remote.xml file configuration:

<keymap>
  <global>
    <remote>
      ...
      <skipplus>ContextMenu</skipplus>
      <skipminus>XBMC.ActivateWindow(Home)</skipminus>
      ...
    </remote>
  </global>
  ...
  <FullscreenVideo>
    <remote>
      ...
      <skipplus>NextSubtitle</skipplus>
      <skipminus>AudioNextLanguage</skipminus>    
      ...
    </remote>
  </FullscreenVideo>    
  ...
</keymap>

Where the line #5, #6, #14 and #15 show the following structure:
<button_name>xbmc_action_name</button_name>
(Note the "..." must not be included, they're just here to figure the rest of the XML file content)

All the XBMC action are fully documented on their very good wiki.

You now have all your button names and action names to map together into the various contexts XBMC offers.

When done with your customisations, take care to save your changes in another location than /opt/xbmc-bcm/xbmc-bin/share/xbmc/system/keymaps/ (e.g. your home folder) as any automated update will revert all the XBMC config files.

Conclusion

Now you should be able to adapt your TV remote to your exact needs. The only issue is if you don't have enough recognised buttons to map all the actions you want.
In that case you may want to fall back on a generic TV remote which should be fully recognised and offer all the mappings capabilities you're dreaming about.

That's all folks!

Le Galérien

Sunday, 20 April 2014

XBMC and your TV remote can be friends