Originally Published: Friday, 23 February 2001 Author: Josh Boudreau
Published to: enhance_articles_desktops/General Page: 1/1 - [Printable]

Mapping Extras Function Keys with XFree 4.0

Linux.com writer Josh Boudreau shares an educational hack working with function keys on the iTouch keyboard with XFree 4.0.

   Page 1 of 1  


This article will explain the process of getting your keyboard's extra function keys to work in XFree86 4.0.X. This article uses the Logitech iTouch keyboard with XFree86 4.0.2 as an example. This method has not been tested with other keyboard models and XFree86 versions other than the ones used by myself. Your results may vary depending if your keyboard is supported by XFree86 4.0 or not. As far as I know, this is an undocumented feature that has been incorporated in XFree86 4.0.

The way this works is that you have to get the scancode of your extra function keys with the xev program, and assign names and keysyms to the keys to be able to use them with X11. I suggest you backup the files we are going to edit in case something goes wrong and you need to restore the original configuration.

Getting your Keys Scancodes

Use the xev program that omes with every XFree86 distribution to get your key's scancodes. The default install location of this program is in /usr/X11R6/bin/xev. When you run this program you'll be looking at a white window with a black square in the middle. This program is used to record X11 Events such as mouse clicks, keyboard keys, etc.

Now that you have the program running, try pressing one of your keyboard's extra function keys. In the terminal from which you launched xev, the output should be similar to this:

xev output:
KeyPress event, serial 29, synthetic NO, window 0xe00001,
root 0x4d, subw 0x0, time 3608986670, (524,-135), root:(589,304),
state 0x0, keycode 223 (keysym 0x0, NoSymbol), same_screen YES,
XLookupString gives 0 characters: ""

KeyRelease event, serial 29, synthetic NO, window 0xe00001,
root 0x4d, subw 0x0, time 3608986842, (524,-135), root:(589,304),
state 0x0, keycode 223 (keysym 0x0, NoSymbol), same_screen YES,
XLookupString gives 0 characters: ""
Notice that we get 2 events, one KeyPress and one KeyRelease.

The Important part of this event output is the "keycode 223 (keysym 0x0, NoSymbol)" line. By looking at this we can tell a few things. First, the key's scancode is 223. Second, there is no keysym or symbol assigned to that key.

What you need to do now is get the scancode for every extra function key on your keyboard. I suggest you pull out a pen and paper for this process because if you move the mouse or do anything else while trying to get the scancode xev will register a bunch of events that we have no interest in. So make sure to only press the key you want to get the scancode for. Also, make sure you note which button the scancode was associated with. As an example, I've included the scancodes I've gathered for my keyboard/

Key Keycode
Standby 223
Mute 160
Volume Down 174
Volume Up 176
Play/Pause 162
Stop 164
Prev Track 144
Next Track 153
Email 236
Web Search 229
Run 230
Web Home 178
Once Again, this is just an example! Don't use these values because your keyboard will probably be different than mine.

If you get no output from xev while trying to get your keycodes that probably means you can't use your keyboard with XFree86 4.0. Some keyboards might produce weird keycodes that X can't understand.

Giving a Name to your New Keys

Now that you've gathered all your keycodes, we have to give each one a name in order to assign keysums. This is done in the ~/.Xmodmap file. That's /home/username/.Xmodmap. If this file does not exist just create it with your favorite text editor.

You have to put a line for each key in the format "keycode XXX = keyname". I will list the content of of my .Xmodap file as an example.

~/.Xmodmap Content:
keycode 223 = LStandby
keycode 160 = LMute
keycode 174 = LVoldown
keycode 176 = LVolup
keycode 162 = LPlaypause
keycode 164 = LStop
keycode 144 = LRew
keycode 153 = LFwd
keycode 236 = LMail
keycode 229 = LFind
keycode 230 = LRun
keycode 178 = LWeb
The name you give your keys can be whatever you wish, I suggest giving then a descriptive name in order to avoid confusion. The L prefix in my example stands for "Logitech" and is just there for my reference. Name your keys whatever name makes you happy.

Finally Assign Keysysms to the Keys

For the final configuration, we need to assign keysyms to the keys in order to use them with X. This is done in the XKeysymDB file, located in /usr/X11R6/lib/X11/XKeysymDB on a default installation of XFree86 4.0. You must be root to edit this file.

Once again, you must have a line for each key in the format: "Key Name :keysym". The key name is the name you've given your keys in the previous step, and the keysym is a unique number we will assign your keys. If you look at previous keys defined in the file you will notice a hexadecimal numbers assigned to the keys. These numbers must be unique to each key so make sure that no other key previously defined in the XKeysymDB matches the keysyms you assign. On my system I've chosen to assign keysyms in the range 10090000 to 1009000B since they were unique to my configuration.

Here's my additional entries in the XKeysymDB file for my keyboard:

! (comments start with a "!")
! Logitech iTouch Keyboard
LStandby :10090000
LWeb :10090001
LMail :10090002
LFind :10090003
LRun :10090004
LMute :10090005
LVoldown :10090006
LVolup :10090007
LPlaypause :10090008
LStop :10090009
LRew :1009000A
LFwd :1009000B
Once done, save that file and restart X. Start xev once again to verify your setup. Now if you follow the instructions in the first step again to get the scancodes of your keys, you'll notice that there is now a keysym and Symbol assigned to your key. If that was successful, you can now assign those keys to shortcuts or to launch programs. This is done differently with every window manager, so I won't go trough the process; check your window manager's documentation on how to assign shortcut keys.

I hope this was helpful to a few people, this was yet another weekend hack I did when I bought my Logitech keyboard, so success may vary on other keyboards. Please feel free to comment about the article, or send information if this procedure did not work for your keyboard model or XFree86 version.

Josh is your average UNIX hacker. Hobbyist Programmer in C, Perl and PHP. He likes to play with things to learn how they work and share his experience with others. bjosh@softhome.net

   Page 1 of 1