HOWTO Saitek Slimline Multimedia Keyboard

From Gentoo Linux Wiki

1 Introduction
2 Kernel Configuration
3 Determining Device Interfaces
4 Keycodes
5 Console Configration
6 X.org Configuration
- 6.1 Binding "Keyboard Mouse Buttons" to keysyms
- 6.2 Configuring xmodmap
7 Links

[edit] Introduction

This HOWTO explains how to enable multimedia keys on Saitek Slimline Multimedia Keyboard. Although the keys will work under X.org, the solution provided here is more of a workaround due to limitations of X.org itself/somewhat poor choice of kernel rawcode<->keycode mapping (at the time of this writing).

[edit] Kernel Configuration

In order to use the keyboard, you will need to enable the following options in kernel:

Linux Kernel Configuration: Configuring the kernel

Device Drivers  --->
  Input Device Support  --->
    <*> Event interface

  HID Devices  --->
    <*> USB Human Interface Device (full HID) support

Note: If you built the above drivers as modules, make sure they are loaded upon plugging-in the keyboard.

[edit] Determining Device Interfaces

Once you plugin your keyboard, check dmesg output to see if the keyboard was recognised. It will be recognised as a generic USB-compliant keyboard. What is unusal about it is that it will result in creation of two /dev/input/event* interfaces. In dmesg output you should have something similar to this:

Code: dmesg output

input: USB-compliant keyboard as /class/input/input3
input: USB HID v1.10 Keyboard [USB-compliant keyboard] on usb-0000:00:02.0-9
input: USB-compliant keyboard as /class/input/input4
input,hiddev96: USB HID v1.10 Mouse [USB-compliant keyboard] on usb-0000:00:02.0-9

The interface marked with "USB HID v1.10 Keyboard" is responsible for the standard keys, and some of the multimedia keys. The interface marked with "USB HID v1.10 Mouse" is responsible for the rest of the multimedia keys. In order to double-check which interfaces are used, see the output of cat /proc/bus/input/devices.

File: cat /proc/bus/input/devices

 I: Bus=0003 Vendor=062a Product=0201 Version=0110
 N: Name="USB-compliant keyboard"
 P: Phys=usb-0000:00:02.0-9/input0
 S: Sysfs=/class/input/input3
 U: Uniq=
 H: Handlers=kbd event3
 B: EV=120003
 B: KEY=1000000000007 ff87207ac14057ff febeffdfffefffff fffffffffffffffe
 B: LED=7
 
 I: Bus=0003 Vendor=062a Product=0201 Version=0110
 N: Name="USB-compliant keyboard"
 P: Phys=usb-0000:00:02.0-9/input1
 S: Sysfs=/class/input/input4
 U: Uniq=
 H: Handlers=kbd mouse0 event4
 B: EV=f
 B: KEY=7fff002c3027 bf00444000000000 1fe3 c000837c000 267bfad941dfed 9e000000000000 0
 B: REL=143
 B: ABS=100000000

[edit] Keycodes

Kernel maps each rawcode that the keyboard sends to a keycode that is usable by applications in user-space. In order to see which key produces which keycode, you can use showkey -k command from the sys-apps/kbd package. In order to see the rawcodes of the keys, use showkey -s.

All the multimedia keys are recognised and are assigned proper keycodes, except for the wheel located to the left of the keyboard, which will act exactly like a mouse wheel without special configuration.

[edit] Console Configration

TODO

[edit] X.org Configuration

In order to make both interfaces usable under X.org, you will need to have the following sections in your xorg.conf (don't forget to specify event interfaces appropriate for your system, and select the keyboard layout you prefer):

File: xorg.conf

...

Section "InputDevice"
    Identifier  "Keyboard1"
    Driver      "kbd"
    Option "AutoRepeat" "500 30"
    Option "XkbRules"   "xorg"
    Option "XkbModel"   "pc105"
    Option "XkbLayout"  "us"

EndSection

Section "InputDevice"
    Identifier  "Keyboard2"
    Driver      "evdev"
    Option      "Protocol"  "evdev"
    Option      "Device"    "/dev/input/event4"
    Option      "XkbModel"  "evdev"
EndSection

...

Section "ServerLayout"

...

    InputDevice "Keyboard1" "CoreKeyboard"
    InputDevice "Keyboard2" "SendCoreEvents"

...

EndSection

After you've changed xorg.conf appropriately, and restarted X, you can use xev from x11-apps/xev|x11-apps/xev package to verify that all key presses are now captured by X.

Note: Except for the "mouse wheel", which will generate the same output as a real mouse wheel.

While kernel assigns keycodes from 1 and upwards, X can only work with single-byte keycodes, and even then only in range of 9-255. X translates the kernel keycodes into its own keycodes using the following formula:

X keycode = ((kernel keycode + 8) mod 256)

Luckily, in case of this keyboard, none of the X keycodes of the keyboard will overlap, but there is one issue - some of the keys will be recognised as mouse buttons instead of keyboard keys, and making them work will require two additional packages - x11-misc/xbindkeys|x11-misc/xbindkeys and x11-misc/xautomation|x11-misc/xautomation.

Note: In the rest of this section the 'X keycodes' will simply be referred to as 'keycodes'.

[edit] Binding "Keyboard Mouse Buttons" to keysyms

In order to use a key under X, you must assign that key's keycode to a keysym. Whenever that key gets pressed, X will translate it into a keysym that can be recognised by applications. As mentioned above, some keys will be recognised as mouse buttons, but mouse buttons cannot be bound to a keysym using xmodmap (explained in the next section), since they do not generate keycodes.

A workaround for this is to use xbindkeys from x11-misc/xbindkeys|x11-misc/xbindkeys and xte from x11-misc/xautomation|x11-misc/xautomation packages in order to generate the keysyms whenever a 'mouse button' gets pressed.

After you've emerged xbindkeys, you will need to run xbindkeys --defaults > ~/.xbindkeysrc, which will generate a default configuration file for it. After that add the following lines to the file:

File: ~/.xbindkeysrc

"xte 'key XF86Copy'"
  b:27

"xte 'key XF86Cut'"
  b:28

"xte 'key XF86ScrollUp'"
  b:22

"xte 'key XF86ScrollDown'"
  b:30

"xte 'key XF86Word'"
  b:32

"xte 'key XF86Close'"
  b:33

"xte 'key XF86ApplicationRight'"
  b:31

"xte 'key XF86ModeLock'"
  b:26

"xte 'key XF86Favorites'"
  b:29

In order for xte to work properly, you must have some keycodes assigned to keysyms mentioned above, even if no key press will generate those keycodes, since xte can only generate keysyms that have been "registered" to X server. This is what we'll do in the following section.

You should either start xbindkeys manually, or make sure it starts automatically with the X. It acts as a resident daemon for the session.

[edit] Configuring xmodmap

Since there is no predefined keyboard layout for Saitek keyboard, you will have to use x11-apps/xmodmap|x11-apps/xmodmap to bind keys to X symkeys.

Note: Symkeys under X are used for identifying which keycode is attached to which key action.

Fill the ~/.Xmodmap file with the following contents:

File: ~/.Xmodmap

 !Use ! for comments
 keycode 172 = XF86AudioPlay
 keycode 174 = XF86AudioStop
 keycode 171 = XF86AudioNext
 keycode 173 = XF86AudioPrev
 keycode 121 = XF86AudioMute
 keycode 123 = XF86AudioRaiseVolume
 keycode 122 = XF86AudioLowerVolume

 keycode 180 = XF86HomePage

 keycode 164 = XF86Book
 keycode 166 = XF86Back
 keycode 167 = XF86Forward
 keycode 181 = XF86Refresh
 keycode 144 = XF86Search
 keycode 136 = XF86Stop

 !Mark button. Assign it to one of the keysyms mentioned in /usr/share/X11/XKeysymDB
 !to your liking.
 keycode 209 =
 keycode 133 = XF86Paste

 keycode 124 = XF86PowerOff
 keycode 150 = XF86Sleep
 keycode 152 = XF86MyComputer
 keycode 131 = XF86Calendar
 keycode 148 = XF86Calculator
 keycode 208 = XF86Excel

 !PowerPoint button. Assign it to one of the keysyms mentioned in /usr/share/X11/XKeysymDB
 !to your liking.
 keycode 129 =

 keycode 179 = XF86Eject

 !The following keycode mappings are used for 'mouse button' presses of the keyboard.
 !Add 30 to get actual keycode reported by showkey -k.
 keycode 232 = XF86Copy
 keycode 233 = XF86Cut

 keycode 235 = XF86ScrollUp
 keycode 227 = XF86ScrollDown

 keycode 237 = XF86Word
 keycode 238 = XF86Close
 keycode 236 = XF86ApplicationRight
 keycode 231 = XF86ModeLock
 !This is the 'F' key located right of the lock key.
 keycode 234 = XF86Favorites

In order to apply these settings, you will need to execute xmodmap ~/.Xmodmap by hand, or make it start automatically when your window manager comes up.