xke linux

XKE

xke-0.03.tar.bz2 relased 19-OKT-2005
XKE README
X - X windows system
K - Linux kernel
E - Events as well

INTRODUCTION
------------

xke is a userspace program which is capable of reading and recognizing Linux kernel generated events, coming from input devices. xke translates Linux kernel events and sends them to the X windows system. Main goal is multimedia key utilization.

As input, xke uses /dev/input/eventXX devices files. As an output device, xke uses the Xtst.so library alias the Xtest extension.

xke uses the unified Linux input event system. It doesn't care what input device is connected to the box. From xke's point of view, only device name and some parameters differ. So xke works with a keyboard, mouse and tablet.

When started, xke connects to the local X server. It doesn't have to be started at a specific time, thanks to the use of the Xtst library. It can be started and stopped without impact to the current X session.

Functionality for now:
generate key (key-press/release) series
launch programs
generate mouse motion
generate mouse button-press/release
Note: Button press and x y axis motion events will be sent to X "unchanged".

xke is a merge and rewrite from the programs:
evdev XFree86 driver by Zephaniah E. Hull
xkeymouse by Henrik Sandklef
tuntiko XFree86 driver by Daniel Skarda
...

STARTING
--------
Make and install the xke binary by typing "make" and "make install". xke uses the input device name instead of the device name. You can read these in /proc/bus/input/devices:
$ cat /proc/bus/input/devices
...
N: Name="CHESEN USB Keyboard"
...
In this case, the device name is "CHESEN USB Keyboard". If multiple devices with the same name exist, then the physical location of the device must be specified:
$ cat /proc/bus/input/devices
...
P: Phys=usb-0000:00:07.2-1/input1
...
Here, the physical location is usb-0000:00:07.2-1/input1
Both parameters my contain some * wildcard characters. Example:
xke --devname * --devphys usb-0000:00:07.2-1/input1
Remember to escape the wildcards from your shell!
If a config file exists, xke can be started without any option.

CONFIGURATION
-------------
Without a config file, xke only sends relative/absolute motion or button press/release events to X. xke searches for a config file in ~/.xke.conf and /etc/xke.conf.
Please take a look in the xke source dir for an example xke.conf. Copy this file to /etc/xke.conf or to ~/.xke.conf and adjust it to your needs.

-- Syntax:
* Verbose [0|1] : Verbose on or off
* DeviceName "STRING" : Device name. Can be a wildcard (*).
* Phys "STRING" : Physical location. Can be a wildcard (*).
* Key "KeyName" { : Key definition
command1 "KeyName" can be substituted by the keycode
command2
...
}

-- Commands availible:
* exec "program" : executes an external program
* button INTEGER : simulates a mouse button press
* keycode [250|<I28>] : simulates a key press. The key can be defined
in decimal or binary code.
* move X Y [0|1] : moves the mouse pointer on the X and Y axis
if 1: relative to the current pointer position
if 0: absolute X and Y coordinates

-- Figuring out the correct KeyName or keycode for input in xke:
To figure out the keynames or keycodes xke recieves, you can run xke in verbose mode without any key definitions. To find out which key maps to which keycode, you can use the evtest program.

-- Figuring out the correct keycode for outputting to X:
This is a little bit harder. There are several methods for finding the keycode.

1) run xev. Strike the real key you want to simulate in xke. The keycode should be displayed in the terminal you ran xev from.

2) If you want to find a specific keysym and do it the "standard" way, then run the following commands:
$ setxkbmap -v 'mykeymap' Substitute mykeymap with your keymap eg. us
$ setxkbmap -v 'mykeymap+inet'
This will load the extended keymap for multimedia keys. Needed if you want to use keysyms like XF86AudioMute.
Now see if keycodes, types, compat or geometry differ from the previous command. If so, use setxkbmap -v 'mykeymap+inet' -keycodes 'xfree86+aliases(azerty)' to correct setxkbmap. You get the picture.
$ setxkbmap -print > tmp This prints your current keymap settings
$ xkbcomp -xbs tmp This makes a complete keymap file
$ rm tmp
$ grep "KeyName" tmp.xkb You will find a decimal code eg. <I19>
$ grep "<I19>" tmp.xkb
This will output the keycode for the keysym you searched.

3) Define your own keycodes. Create the tmp.xkb file, as previously described, and search for a code that isn't yet used. Then, create a file ~/.Xmodmap (or system-wide: /etc/X11/Xmodmap, may be different in your distribution) containing:
keycode 450 = XF86AudioMute

Load the file using Xmodmap /etc/X11/Xmodmap and try sending this keycode using the xsendkey program (you can find it on the backstreet ruby homepage) or by defining it in the xke config file.

NOTE: You can use this as a temporary solution. If you input the key in xev, it will display the "proper" keycode. You can then remove the line from the Xmodmap file and use this keycode in xke.


You can now configure KDE, GNOME or another application to catch these keysyms and execute commands.

USAGE
-----
xke runs as a normal proces. You must restart it if you changed the configuration. If a device is unplugged and then reconnected, xke detects this and automatically reopens the device file.
xke can be used as a mouse driver.

TROUBLESHOOTING
---------------
* Please use the evtest program first to test if the event interface is set up correctly. It should be noted that evtest only needs read permissions, whereas xke needs write permissions too!
* If you experience weird mouse clicks when using xke, you may be using the combined mouse device file /dev/input/mice or a symlink to it. Please use the mouse device specific to your mouse (eg. /dev/input/mouse0). Else, some buttons on the keyboard may be mapped to mouse button events.
* The Xtst library is designed for testing, not for ordinary event recieving.
As such, xke may take more CPU than a normal XFree86 input driver.
Sometimes, xke events can be delayed until X syncs. However, you only
notice it if xke is used as a mouse or tablet driver.

HELPME
------
The foundation for this document has been layed by Aivils Stoss.
It has been rewritten by Ruben Faelens.