usbhotkey - Remap USB keyboards under X11 ######################################### License ======= - The program itself is licensed under the GPL, version 2. - The scripts are "a mere aggregation" (Section 2 of the GPL) as they will work independently of usbhotkey if the relevant functions are provided otherwise. Thus the scripts are not covered by the GPL, unless explicitely stated in the respective script. - The scripts currently included in this distribution are licensed under the GPL, version 2. - If you want your script to be included in the official distribution of usbhotkey, license it under an open source license. Requirements ============ - the gcc package of your distribution - the X11 development package of your distribution (headers and libraries) - the Xtst extension (should be included in most distributions) - libhid (http://libhid.alioth.debian.org) - configure using ./configure --disable-swig if compilation errors in hid_wrap.c appear - Imlib (http://www.enlightenment.org/Libraries/Imlib.html) - This library is optional. If you don't have it or disable it in the configuration, image display will be disabled. Scripts will continue to work, but won't display images. - Please install the development package of your distribution. - ruby (www.ruby-lang.org), version 1.8 or later. Earlier versions not tested, might work too. Installation ============ - Build the program using the usual GNU tool build commands: # ./configure --prefix=/where/should/i/install # make # make install Make sure you have sufficient permissions for installation. Installing to $HOME directory is possible. - If a configure script is not available, use the following sequence # aclocal # autoheader # autoconf # automake -a You need a recent automake/autoconf. automake-1.10 and autoconf-2.61 are currently used for development. Execution ========= - Call the program with a suitable ruby script (see below). # usbhotkey /where/should/i/install/share/usbhotkey-0.1/ag5.rb - You need sufficient rights on the USB device to open. See the libhid homepage for examples. If you see an error message like: # USB error: could not claim interface 0: Operation not permitted # usbhotkey: Can't connect HID. then you don't have sufficient permissions on the device. If you see the message: # usbhotkey: Starting event loop then everything works fine. Don't be alarmed about any other messages from libhid. - If you want to allow each user to run usbhotkey using sudo, the following procedure is recommended: - Assuming all relevant users are in group users, add the following line to your sudoers file using visudo (without the #): # Defaults>root env_keep=XAUTHORITY,env_keep=DISPLAY # %users localhost=NOPASSWD:/where/should/i/install/bin/usbhotkey - All users that logged in locally should now be able to run usbhotkey as root: # sudo /where/should/i/install/bin/usbhotkey script.rb - Another approach is to use ssh. BEWARE: this is nearly identical to give users the root password. It may be handy if this is a one-user computer anyway. - Generate an ssh key using ssh-keygen - Have the ssh daemon running. Put in your init script. - Put your public key in root's keyring: # ssh-copy-id ~/.ssh/id_dsa.pub root@localhost - Start usbhotkey # xhost +loalhost ; ssh -X root@localhost DISPLAY=$DISPLAY \; . /etc/profile \; /where/should/i/install/bin/usbhotkey script.rb - Implementing the example from the libhid homepage does not work on Gentoo. The permissions are changed, but I can't open the device anyway. Any help on that issue is highly appreciated. Ruby script implementation / Principle of operation =================================================== - The usbhotkey program itself reads USB events from an opened device and calls a ruby function for press and release events. The ruby script given on the command line provides these functions along with some initialisation code to open device. - A single USB keyboard can be opened by one instance of usbhotkey. It should be possible to run multiple instances, although this was not tested. - The ruby command # UHK_connect( 0x510, 0x100b, 0x81) seaches a USB device with vendor ID 0x510 and product ID 0x100b. If found, it reads events from end-point 0x81. Use lsusb -vvv to find the data for your keyboard. - On keypress the ruby function # UHK_USB_keydn( code) is called. All keycodes start with 'USB_'. See constants.c for a complete list of names. Shift keys are always sent before regular keys. - On keyprelease the ruby function # UHK_USB_keyup( code) is called. See above for . Shift keys are always sent after regular keys. - Since several keys may be pressed at once, the start and the end of a sequence of events is reported by: # UHK_USB_mark( code, millisecs) where millisecs indicates the in milliseconds since the last event and code indicates the following events: code event MARK_START_RELEASE Start of the key release sequence MARK_END_RELEASE_START_PUSH End of release, start of key press sequence MARK_END_PUSH End of key press sequence MARK_IDLE Idle event Since this function is called every 200 ms when waiting for a key, make it fast. - The order of calls to UHK_USB_keyup and UHK_USB_keydn depends on the order of the keycodes in the USB data packet and might be highly keyboard specific. - In order to send keycode to X11, call # UHK_keydn( x11code) # UHK_keyup( x11code) The respective X11 keycodes are provided internally. They start with WIN_. - Keep in mind that keycodes are sent. These are subject to translation by the current keymap. This calling # USK_keydn( WIN_bracketleft) produces a [ on US and UK keyboards, but an u-umlaut (u with 2 dots above) on a German keymap. You may use this feature to generate letters that are not part of the regular keymap by generating unused keycodes and mapping them in ~/.Xmodmap. - See the provided ag5-replicate-colours.rb script for an example on how this all fits together. - Floating image display is disabled. We have the full power of ruby to display these images anywhere: the root window, using libXOSD. Related literature ================== - USB HID specs (http://www.usb.org/developers/hidpage/) - Device Class Definition for HID 1.11 (HID1_11.pdf) - HID Usage Tables 1.12 (Hut1_12.pdf) - Ruby manual - X11 manual Known bugs / open issues ======================== - Can only be run as root/setuid on Gentoo? Contact ======= lars_e_krueger@gmx.de # vim: tw=78