This is the firs version of the Multimedia-X-Keyboard-HOWTO

This HOWTO was written by Lord Darth Moultak <moultak@gothicfuneral.zzn.com>

The latest version of this HOWTO can be found at http://www.sourceforge.net/projects/osdsh

# How to configure the internet keys on your multimedia keyboard, without using extra daemons, just X and the window manager you already run.

Introduction:

Some time ago, manufacturers of computers started shipping their hardware with keyboards that had "extra" keys on them, these keys were meant to control internet and multimedia features of the system, like playing/stoping/pausing cds and MP3's, connecting to the internet, starting mail and chat programs, and sleeping or suspending the computer, and were marked as such. This is nice, these keyboards look nice and they are comfortable to work with, those keys always come in handy, but they are a pain to configure in X. This is how I did it.

The theory:

When a key is pressed, the keyboard generates a code that the kernel detects, this code is known as "keycode". When X detects a keycode, it looks in a table of symbols to see if that keycode means something. The symbols are the way the software understands the keys, like TAB, UP, DOWN, CTRL, etc...

If the keycode does mean something, (that is, a symbol is asigned to it) the symbol goes to the application that has the keyboard control, like a text editor or a game.

X comes with a series of "keymaps", (files that contain the keycode-keysym pairs ) that work for a lot of keyboards, and even with some "Internet keys", but at least for me, the internet keys were dead. So I needed a new keymap.

Since the normal keys already worked fine, I just needed to add the keycode-keysym pairs that would make my keys work. To do this there is a utility (also part of X) called xmodmap.

xmodmap reads a file or std input for "commands". The commands are in the form of

keycode $keycode = $keysym

where $keycode is the actual keycode (the first "keycode" needs to be there).

This tells xmodmap to assign the specified keysym to that keycode. Since when you log out you lose the asignments, you need to load them when you start X. (X automatically loads a keymap from its configuration file) This is done adding a line like:

xmodmap yourkeymap

to your .xinitrc or .Xsession file

Now they get recognized, but they dont do anything!!! you say.

That is true, any software can now recognize the keys, but they are not doing anything useful, like starting programs, changing the volume or connecting to the internet. We will leave this to the window manager.

Most window managers can be configured to do something when a key or a combination of keys is pressed, like Alt-Tab to switch or cicle the windows, and we are going to use this feature to start the programs that will actually do something useful.

In WindowMaker, the configuration utility has a section for this. For blackbox there is a program called bbkeys that handles the "keyboard shortcuts".

I can give no advice in this part, since each window manager works different, but in the documentation of yours, you can get the info you need. Look for "keyboard shortcuts" or something like that.

The practice:

Well, lets get our hands on this...

First, pick up a key (the leftmost, the rightmost, the bigger one) of your internet keys.

In an xterm write

$ xev

you will get a window with a square on it. Now press the key you chose.

It will read something like:

KeyPress event, serial 19, synthetic NO, window 0x2200001,

root 0x27, subw 0x0, time 2565600158, (136,110), root:(350,340),

state 0x10, keycode 149 (keysym 0x1000410e, IA14), same_screen YES,

XLookupString gives 0 characters: ""

KeyRelease event, serial 24, synthetic NO, window 0x2200001,

root 0x27, subw 0x0, time 2565600304, (136,110), root:(350,340),

state 0x10, keycode 149 (keysym 0x1000410e, IA14), same_screen YES,

XLookupString gives 0 characters: ""

now press Ctrl-c in the xterm and look at the third line of each block, there is a keycode in decimal (in this case, 149) and a keysym (in this case IA14). Ok, if you had not assigned any keysym to your inet keys, instead of IA14 you will get something like NoKeysym.

The X guys have set aside some special keysyms for the inet keys, they go from IA1 to IA15 and IB1 to IB15. This gives us a total of 30 keysyms. This has to be enough for any keyboard.

write a file "yourkeymap" that reads

keysym 149 = IA14

(change the values acording with what you got, if you got a NoKeysym, choose a keysym from the ones mentioned above, IA1 looks nice for a start)

now from the xterm do:

$ xmodmap yourkeymap

and repeat the thing with xev. Start it and press the key you pressed before. You will get a similar output, but instead of the NoKeysym you will get the keysym you wrote in your file.

Add a line for each key you want to configure. Don't repeat keysyms (unless you want several keys to do the exact same thing). Reload your keymap with:

$ xmodmap yourkeymap

Now copy the yourkeymap file to ~/.yourkeymap.

Edit your ~/.xinitrc or ~/.Xsession file to add a line that says:

xmodmap ~/.yourkeymap

This is done to load the keys when you start X.

Instead of doing all this, you may want to check my program "keymapconfig" that asks you to press a key and then asks you for the keysym to asign to it. You can save this pairs to a file and load them later with xmodmap... It requieres Tcl/Tk. Try to use only the keysyms specified above (IA1 to IA15 and IB1 to IB15) to avoid conflicts and problems. Anyway 30 keys are more than enough for internet and multimedia stuff.

(You have already downloaded this program, with this howto, look in the directory where you untarred the tarball)

You still have to add that line in your .xinitrc or .Xsession to load your keymap when you start X.

Now you have to configure the applications that do the work. This is configuration of your window manager, and each window manager will have different instructions, but most of them will work.

Basically, when asked for the key to watch (or “keyboard shortcut”), just write the keysym you asigned to the key you want to do something (or press that key, the “Key” is in fact the keysym, not actually the key) and then write the command you want to run when you press that key.

You can also use these keys in combination with modifiers like Ctrl, Shift and Alt. For example, I use the "Play" key to start xmms, but if I want to play a CD, I use Ctrl-Play to start gcd; for me Play is IB3 so I configured Ctrl-IB3 to start gcd. I also use the "Suspend" key to suspend the computer by running "apm -s", but if I want to see the battery status, I use Ctrl-Sleep to run "osdctl -A 3", that displays the battery status using osdsh (Read below). Again, for me "Suspend" is IA5, so to run "apm -s" I asigned the key IA5 and to run "osdctl -A 3" I asigned Ctrl-IA5.

For volume control, I recommend using umix, for terminals aterm is nice and for the "Connect" key, put the command you use to connect. Its that simple.

As an adition, you may want to check osdsh (by me of course), its a daemon that monitors the sound card volume, battery and connection status, displays a clock and displays it all using the XOSD library, so you get a nice TV-like On-Screen-Display for your sound, batt, connection and a sexy clock floating unmanaged on your display.

http://www.sourceforge.net/projects/osdsh