Bengt Mårtensson > Private Site
Font size:      

The dBox IR-Keyboard

Revision history

2006-02-20 Initial version.
2006-03-29 Fixed some minor errors. Mention kb2rcd. Update and describe patch.
2009-08-09 Updated for seife's rcinput rework and the new version of the kadb patch. Updates are clearly marked as such.


Originally, the dBox was designed as a "multimedia terminal", with applications such as pay-per-view ordering, email, and home banking in mind. This design consideration amounts for the second (never officially used) card slot, the modem, and the optionally available infrared keyboard. This is all history, in particular, the keyboard was quite hard to get. Recently, they are available on German eBay for a quite reasonable price. (Search for "dbox tastatur").

Picture of the IR Keyboard

The keyboard events are intercepted by the front processor of the dBox, making it possible both to read the keyboard as a generic computer keyboard, and to interpret the keys as coming from a normal remote control.

Some plugins access the keyboard. This topic is not covered by the present article, but may be found on Tuxbox WiKipedia, on the IR Keyboard page or on the Tuxbox commander page.

The empirical statements in this article has been verified on a Nokia, as well as on a Sagem dBox. It is believed that the Philips acts similarly.

The picture has been shamelessly stolen from Tuxbox WiKipedia.

The hardware

The keyboard is in laptop design and size, and comes exclusively in German qwertz-layout with German labeling. See the picture. There is a "fire button" on the extreme left, and a "joystick like" thing to the right. Below the "joystick", there is another "fire button". On the front, there are four IR-Diodes, that appear to provide quite reliable communication. I tried with a distance of 7 meters with no problems, probably much larger distances are possible.

The unit is powered by 4 AA-type batteries. It is suitable both for desktop- and sofa-usage. The mechanical quality is quite acceptable, in particular considering the low price.

Low-level interface

All keys send different infrared signals. The driver in .../driver/fp/dbox2_fp_keyboard.c translates these in keycodes and events. The keycodes are listed in the source code file .../apps/tuxbox/neutrino/src/driver/rcinput.h. These keycodes are in general from the Linux include file include/linux/input.h. The "Fn"-key to the lower left is made into a shift-key: it sends no keycode, but makes some keys (the ones having blue lettering) sending other keycodes. These are: KP0 to KP9, KPASTERISK, KPMINUS, KPPLUS, KPDOT, KPENTER (on the return key), KPSLASH. Until recently, the two Windows keys, and the key marked "Druck S-Abf" were left out.

As opposed to the remote control, no keys on the keyboard makes the dBox wake up from deep standby.

The left "fire button" sends the BTN_LEFT keycode, and the right one the BTN_RIGHT keycode. Usage of the "joystick" can be identified by the event type.

The keyboard as a computer keyboard

A front processor driver (dbox2_fp_keyboard.o) makes it possible to use the keyboard as a normal computer keyboard. With the command loadkeys (normally executed from rcS) it is possible to load a proper keyboard translation table. Since the keyboard is labeled as a German qwertz-keyboard, the de-latin1-nodeadkeys keymap is recommended. (de-latin1, used in the HEAD branch of CVS, is an alternative, however, for a computerist in general unsuitable.)

The appropriate keymap is loaded with the command like loadkeys /share/keymaps/i386/qwertz/de-latin1-nodeadkeys.kmap.gz. The following files must be installed for this to work:


Around 100 kB space in the root partition is required. With this keyboard tables, everything (but the Windows keys) works, as far as I know, flawlessly.

Through /etc/inittab, there are more possibilities. With keys Alt-F2 thought Alt-F6 a virtual console is opened on the framebuffer. It is hidden (not closed) by the key Alt-F1. Finally, /etc/inittab instructs the system to reboot on the Cntrl-Alt-Del ("Strg-Alt-Enf" on German keyboards) key press.

The keyboard as a remote control for Neutrino

The first impression when trying the keyboard out of the box is that Neutrino recognizes very few of the keys. These are: The numerical keys 0 to 9, "Pos1" = Home, Bild ^ = Page Up, "Bild v" = Page Down (seldomly used, found only on very old remote controls), as well as the cursor keys. There is nothing wrong with this — the keyboard is a "keyboard", not a bulky replacement remote control!

In the menu dBox -> Settings -> Key Setup, it is possible to bind certain functionality (e.g. switching between TV- and radio-mode) to arbitrary keys. All keyboard keys (except for "Fn") can be used for this. With CVS from 2006-02-17 (2006-03-26 for the remaining three: KEY_SYSRQ, KEY_LEFTMETA, and KEX_RIGHTMETA), Neutrino also knows sensible names for those keys.

To be able to programmatically use the key, rcinput.h was extended. The keycodes have names taken from include/linux/input.h. From the keycodes, Neutrino key events are being named in an obvious manner.

Unfortunately, the event belonging to key on the German labeling denoted with ß, should logically be named RC_minus. However, this name was previously taken in a previous version of the file to denote the key for lowering the volume (RC_volumedown would have been better). For this reason, the name RC_hyphen was chosen.

Really turning the keyboard into a bulky remote control

Neutrino does not offer a clean way to, for example, add another "red button". So, instead the original version of this article presented a dirty way :-). (Just hard coding some translations into rcinput.cpp.)

The kb2rcd-daemon

Possibly as an answer, robspr1 in the Tuxbox forum wrote the daemon kb2rcd, see this posting (and following ones), as well as this thread in the Jack-the-Grabber forum. This is no doubt an interesting approach. It is a daemon that gets events (from /dev/input/event0), translates them, (not necessarily 1-1, but possibly 1-0 (Scripts), or 1-n (macros)) and pushes them back in the device. The advantage is the modularity, as it works with "everything", including plugins as well as Enigma. Also, it is easily added to an existing image, even cramfs/squashfs-Images. The drawback is that it works on the event-level; therefore everything like timing, up/down-Events etc. must be considered. As I tried it, at first it did not work at all, only for very long key presses. I found out that the initial delay (200ms) needed to be lowered. It can be configured using a configuration file kb2rcd.conf. It can execute commands, as well as plugins, directly. Recent versions can translate joystick actions to cursor keys, and can also interpret the Alt-key as a shift key, as well as assigning a binding to delayed keys. It is (partially) described in this Wiki-contribution (as well as the threads quoted). It has been checked in to CVS, in the directory .../apps/tuxbox/tools/kb2rcd.

A patch for rcinput

UPDATE 2009: In late 2008, seife of the Tuxbox forum made substantial improvement on the input handling in rcinput.c, making it possible to handle not only down-events, but also repeat-events and up-events (i.e. when a key on the remote or the keyboard are held down or released) in a uniform fashion. As a side effect, this unfortunately broke the patch. Here we now present a new version, which is also able to bind repeat- and up-events.

The patch for rcinput, available here, has been vastly improved. The translation is now governed by a configuration file, in spirit similar to the configuration file for kb2rcd. The patch works by translating keys, (not events), therefor no 1->n translation (macros) are possible. In particular, instead of key presses, several Neutrino-messages (see .../apps/tuxbox/neutrino/src/neutrinoMessages.h) can be generated, optionally with data. In this way, it is also possible to execute plugins directly .The configuration file should be located in /var/tuxbox/conf/rc.conf. A sample configuration file is shown in the Appendix.

To the file format of the configuration file: Every line is of the form keyword=action or keyword=action(data). All other lines are ignored. A hash sign ("#") is taken as a comment character. Here keyword in general is the name of a key (translated to lower case), but there are also additional keywords.

UPDATE 2009: The name of the keys are now no longer the Linux input names from the kernel sources (linux/input.h), but the Tuxbox-private rc-names, as can be seen in the Appendix. Also, the names can now optionally be followed by a brackets with a modifier (r for repeat, u for up), denoting that the binding is to be active for repeat- or up-events respectively. See the example in the appendix.

Keyword Allowed Values Description
keyname (lower case) action (lower case) Have action be executed at press of key keyname.
debug on and off Turns on and off tracing on the system console.
no_neutrinoevents_when_vc on and off If on, whenever a virtual console is visible (opened with F2F6), key presses will not be forwarded to neutrino.

Allowed actions are the key names, as well as some additional actions. These often, but not always, are the same as the corresponding Neutrino messages, translated to lower case.

Action Data Description
keynameHave Neutrino execute the action associated with keyname.
system command The data is taken as argument to a system command; in normal English, "is executed". Output is output to the system console. The return status is reported to the console.
mode_tvSwitches neutrino to TV mode
mode_radioSwitches neutrino to radio mode
vcr_onSwitches on SCART-mode.
vcr_offSwitches off SCART-mode.
standby_onSwitches on standby-mode.
standby_offSwitches off standby-mode.
show_epgShows the EPG.
show_infobarShows the infobar.
lock_rcLocks the remote control (and the keyboard). Press the red key followed by the dBox key to re-enable. See this Wiki-article.
show_volumeShows the volume bar.
evt_popupmessageShows message in a temporary popup.
evt_extmsgmessageShows message in an extmsg popup.
evt_pluginpluginname.cfgStarts the popup with the name pluginname.
reload_confReload the configuration file.
shutdownShutdown the system. Note that this is a way of implementing a bona-fide discrete power-off-key.

Appendix. A sample rc.conf

UPDATE 2009: Replaced.

# Do not turn on debugging yet, but at the end of the file

# Do not let Neutrino see the keys when a virtual console is open

# Assing keyboard keys to stuff that are useful for controlling the tuxbox
# Upper row

# second row
rc_equal=system(aformat -l)
rc_backspace=system(kill `cat /var/run/`)

# third row
rc_tab=reload_conf # special function: reload_conf reloads this file
rc_rightbrace=system(controldc setVideoFormat 1) # 16:9
rc_backslash=system(controldc setVideoFormat 0) # auto

#forth row

# fifth row

# sixth row
rc_leftctrl=system(controldc setVideoOutput 4) # YUV
rc_leftmeta=system(controldc setVideoOutput 1;controldc setVideoFormat 0) # RGB + auto

# other
rc_btn_left =rc_ok

# The remote control keys

# Not on keyboard, but on some well equipped remotes
#rc_top_left=system(controldc setVideoFormat 1) # 16:9
#rc_top_left[r]=system(controldc setVideoFormat 0) # auto
#rc_top_right[r]=evt_popup(Holding down...)
#rc_bottom_left=system(aformat -l)
#rc_bottom_left[r]=system(killall aformat)

rc_top_left=system(controldc setVideoFormat 0) # auto
rc_top_right=system(controldc setVideoFormat 1) # 16:9
rc_bottom_left=system(aformat -l)
rc_bottom_left[r]=system(kill `cat /var/run/`)

#rc_page_down=system(aformat -l)
#rc_page_up=system(killall aformat)

# List all keys for debugging or documentation purposes.

# From now on, list debugging info for each keypress

Appendix. Installing the keyboard mapping file with newmake.

Here is a file that will install the above mentioned files in a newmake run. It violates this "style recommendation" severely ;-). Note that the value of targetprefix has to be manually edited in the file.


make console_tools

install $targetprefix/bin/loadkeys $newroot/bin
install -d $newroot/share/keymaps/i386/qwertz
install -d $newroot/share/keymaps/i386/include
install -m 444 $targetprefix/share/keymaps/i386/qwertz/de-latin1-nodeadkeys.kmap.gz     $newroot/share/keymaps/i386/qwertz
install -m 444 $targetprefix/share/keymaps/i386/qwertz/de-latin1.kmap.gz       $newroot/share/keymaps/i386/qwertz
install -m 444 $targetprefix/share/keymaps/i386/include/ $newroot/share/keymaps/i386/include
install -m 444 $targetprefix/share/keymaps/i386/include/ $newroot/share/keymaps/i386/include
install -m 444 $targetprefix/share/keymaps/i386/include/   $newroot/share/keymaps/i386/include