Logitech Cordless Desktop LX700

I was getting tired of my old keyboard and decided to buy a new on. The choice fell on a “Logitech Cordless Desktop LX700”, with a “Logitech Cordless Click! Plus” mouse included.
The keyboard has a gazillion extra keys, including a roller on the left side, doubling for the arrow keys on the right, and some mouse buttons on the keyboard. It also has a bunch of keys for controlling a media player, and for other applications.
Basic functionality is there and the keyboard works out of the box with Linux. The problem lies with all the extra keys.
Some of the extra keys are known to the Linux keyboard driver and to to XFree86, and they can be configured in Gnome or your window manager without any problems. In my case this happened for several of the media player keys and the Email key. All I had to do was select “Logitech Desktop Pro” as the keyboard type in the Gnome preferences.
Many of the extra keys did not work, however.
It took quite an effort to get everything to work, but in the end each and every key on the keyboard is usable under Linux.

Scancodes, keycodes x 2 and keysyms

There are several layers of interpretation involved in a keypress. First the keyboard generates a scancode which is mapped to a Linux keycode by the kernel. When running under XFree86 the scancode or the linux keycode is mapped by the X keyboard driver to an X11 keycode (which still indicates a physical key on the keyboard), and later again to an X keysym (which is a more symbolic representation of a logical key).
So to make everything work we need to make sure all scancodes have Linux keycodes (i.e., that the keys are known to the kernel), and then find the corresponding X11 keycodes and map those to X11 keysyms which applications can use.

Keyboard scancodes

Keyboard scancodes are either a seven bit number (0x00-0x7f) or an extended scancode made up of the number 0xe0 followed by a seven bit number. This allows for at most 256 scancodes.
When an unknown key is pressed, the kernel prints a message giving the scancode:

atkbd.c: Unknown key pressed (translated set 2, code 0x6e on isa0060/serio0).
Use 'setkeycodes 6e ' to make it known.

This is the basic tool for discovering scancodes for the extra keys on this keyboard.

The Linux keycode table

The Linux kernel maintains a table mapping keyboard scancodes to linux keycodes. The table can be printed with the program getkeycodes:

# getkeycodes
Plain scancodes xx (hex) versus keycodes (dec)
for 1-83 (0x01-0x53) scancode equals keycode
 0x50:   80  81  82  83  84   0  86  87
 0x58:   88 117   0   0  95 183 184 185
 0x60:    0   0   0   0   0   0   0   0
 0x68:    0   0   0   0   0   0   0   0
 0x70:   93   0   0  89   0   0  85  91
 0x78:   90  92   0  94   0 124 121   0
Escaped scancodes e0 xx (hex)
e0 00:    0   0   0   0   0   0   0   0
e0 08:    0   0   0   0   0   0   0   0
e0 10:  165   0   0   0   0   0   0   0
e0 18:    0 163   0   0  96  97   0   0
e0 20:  113 140 164   0 166   0   0   0
e0 28:    0   0 255   0   0   0 114   0
e0 30:  115   0 150   0   0  98 255  99
e0 38:  100   0   0   0   0   0   0   0
e0 40:    0   0   0   0   0 119 119 102
e0 48:  103 104   0 105 112 106 118 107
e0 50:  108 109 110 111   0   0   0   0
e0 58:    0   0   0 125 126 127 116 142
e0 60:    0   0   0 143   0 217 156 173
e0 68:  128 159 158 157 155 226   0 112
e0 70:    0   0   0   0   0   0   0   0
e0 78:    0   0   0   0   0   0   0   0

The zeroes indicates keys with no mapping.
To set a mapping for an unknown scancode, use the program setkeycodes:

setkeycodes e03b 227

Linux keycodes have symbolic names in the file /usr/include/linux/input.h, but any unused number between 1-255 can be used.
All keys must have a linux keycode, otherwise they will be dead and unusable.
Having tested all the keys, I ended up with this command to initialise the linux keycode table:

setkeycodes e011 216 e075 148 e074 212 6c 105
6e 106 e001 154 6d 206 e004 202 6a 203 6b 219
e014 181 e013 182 e015 188 e055 187 e031 152
e078 167 e02d 168 e02f 162 e02c 192 e025 195
e026 194 e03b 227 e03c 228 e03d 229 e03e 230
e03f 231 e040 232 e041 233 e042 234 e043 235
e044 236 e057 237 e058 238

After initialisation the keycode table looks like this:

# getkeycodes
Plain scancodes xx (hex) versus keycodes (dec)
for 1-83 (0x01-0x53) scancode equals keycode
 0x50:   80  81  82  83  84   0  86  87
 0x58:   88 117   0   0  95 183 184 185
 0x60:    0   0   0   0   0   0   0   0
 0x68:    0   0 203 219 105 206 106   0
 0x70:   93   0   0  89   0   0  85  91
 0x78:   90  92   0  94   0 124 121   0
Escaped scancodes e0 xx (hex)
e0 00:    0 154   0   0 202   0   0   0
e0 08:    0   0   0   0   0   0   0   0
e0 10:  165 216   0 182 181 188   0   0
e0 18:    0 163   0   0  96  97   0   0
e0 20:  113 140 164   0 166 195 194   0
e0 28:    0   0 255   0 192 168 114 162
e0 30:  115 152 150   0   0  98 255  99
e0 38:  100   0   0 227 228 229 230 231
e0 40: 232 233 234 235 236 119 119 102
e0 48:  103 104   0 105 112 106 118 107
e0 50:  108 109 110 111   0 187   0 237
e0 58:  238   0   0 125 126 127 116 142
e0 60:    0   0   0 143   0 217 156 173
e0 68:  128 159 158 157 155 226   0 112
e0 70:    0   0   0   0 212 148   0   0
e0 78:  167   0   0   0   0   0   0   0

X11 keycodes and keysyms

Once the keys are known to the linux kernel, X11 should report on the keys. There is no need to restart anything. All changes are made immediately. Run the command xev in a terminal window and press some of the keys. In the copious output there should be entries like:

KeyPress event, serial 22, synthetic NO, window 0x1a00001,
    root 0x3f, subw 0x0, time 182843678, (117,117), root:(188,165),
    state 0x0, keycode 9 (keysym 0xff1b, Escape), same_screen YES,
    XLookupString gives 1 bytes: ""

We’re looking for KeyPress events. The interesting parts are in the third line. The X11 keycode is there (“9” in the example, it is normally different from the linux keycode) and the assigned X11 keysym is there (0xff1b in the example). The name of the keysym is there too (“Escape”).
All keys should give a X11 keycode in the output of xev, but some keys will probably give a keysym of 0 with the name NoSymbol. These keys are known to Linux but no configured in XFree86.
The mapping of X11 keycodes to keysyms is set with the xmodmap program, e.g.,:

xmodmap -e "keycode 121 = XF86Messenger"

The names of X11 keysyms for special keys are listed in the file /usr/X11R6/lib/X11/XKeysymDB.
Many keys on the Logitech Cordless Desktop LX700 keyboard were known and defined by XFree86, but several were missing. These xmodmap commands will define the missing keys:

keycode 121 = XF86Messenger
keycode 159 = XF86Calendar
keycode 187 = XF86WebCam
keycode 166 = XF86RotateWindows
keycode 175 = XF86Close
keycode 171 = XF86ZoomOut
keycode 172 = XF86ZoomIn
keycode 195 = XF86Finance
keycode 137 = XF86Video
keycode 138 = XF86Music
keycode 247 = XF86Pictures
keycode 131 = XF86Documents
keycode 146 = XF86CD
keycode 177 = XF86AudioRecord
keycode 152 = XF86AudioRewind
keycode 253 = XF86Eject
keycode 249 = XF86Launch0
keycode 149 = XF86Launch1
keycode 119 = XF86Launch2
keycode 214 = XF86Support
keycode 215 = XF86Word
keycode 216 = XF86Excel
keycode 217 = XF86Calculater
keycode 218 = Undo
keycode 228 = Redo
keycode 142 = Print
keycode 213 = XF86Save
keycode 240 = XF86Copy
keycode 241 = XF86Cut
keycode 242 = XF86Paste
keycode 243 = XF86Clear

With this in place the keys should be functional. You will have to bind something to these keys, in your window manager or in your applications.
In sawfish you can middle-click on the desktop, and select “Customise | Bindings” where you can setup some of the special keys to do window manager functions. For example, I have bound XF86RotateWindows to the Sawfish function “Next workspace window”. I can now cycle through the open windows in the current workspace with just one key press.
In Gnome you can go to the menu entry “Applications | Desktop Preferences | Keyboard Shortcuts” where you can setup various media player shortcuts and other keys. Not all of these settings work in my setup, maybe because I’m not using the default Gnome window manager metacity.

Automatic setup

The setkeycodes command has to be run once at system start. How it is done depends on you choice of distribution. On Debian Linux you must create an init.d file, e.g., /etc/init.d/logitechkbd which has to be linked to the system startup directories. This is done with the command

update-rc.d -n logitechkbd start 75 S .

The file /etc/init.d/logitechkbd can be downloaded below.
Next, you need to run the above xmodmap commands whenever you start X-windows. The easiest is to have the commands in a file, say ~/.Xmodmap_logitech which is then run from whatever scripts starts your X-session. The command is:

xmodmap ~/.Xmodmap_logitech

Files for download

/etc/init.d/logitechkbd
~/.Xmodmap_logitech

Problems with scancodes

I have received several mails about problems using scancodes above 127. I have myself had no such problems, using Debian Testing, but apparently there’s a bug in some versions of setkeycodes.