Receiving USB events

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.

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 key press the ruby function

UHK_USB_keydn( code)

is called. code is the USB scan code.

On key release the ruby function

UHK_USB_keyup( code)

is called.

An alternative interface is:

USK_USB_keyev( code, isUp)

Here, isUp is 0 on key press and 1 on key release. You only need to implement one of these interfaces (UHK_USB_keyup/UHK_USB_keydn or UHK_USB_keyev).

Symbolic names for the USB keycodes are provided under the names that start with USB_. See constants.c for the actual names.

The function

UHK_USB_mark( cycle, time)

is called on various occasion with different values for cycle:

MARK_START_RELEASE

Begin of the cycle, before the first call to UHK_USB_keyup.

MARK_END_RELEASE_START_PUSH

After all calls to UHK_USB_keyup, before the first call to UHK_USB_keydn.

MARK_END_PUSH

After all calls to UHK_USB_keydn.

MARK_IDLE

When there was no event for 100 ms.

Generating X11 events

The following functions are provided to generate X11 events.

Function signature	Description
UHK_keydn( x11key)	Simulate an X11 key press.
UHK_keyup( x11key)	Simulate an X11 key release.
UHK_btndn( x11btn)	Simulate an X11 mouse button press.
UHK_btnup( x11btn)	Simulate an X11 mouse button release.
UHK_keyev( x11key, isUp)	Simulate an X11 key event.
UHK_btnev( x11btn, isUp)	Simulate an X11 mouse button event.
UHK_get_keysym( code)	Convert a USB key code into an X11 keycode like the keyboard would do.
UHK_is_key_pressed( code)	Return 1 if the last USB event indicated the key as pressed.

The values for x11key are those constants that begin with WIN_. See constants.c or the X11 headers/documentation for the respective names and meanings.

The values for x11btn are logical mouse button numbers (i.e. those that are specified in the X11 config file). The left mouse button is usually 0.

isUp and code have the same meanings as before.

Keep in mind that X11 keycodes are subject to translation by the current keymap. Thus calling

UHK_keydn( X11::XK_bracketleft)

produces a [ on US and UK keyboards, but an u-umlaut (ü) 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.

• USB HID specs
  • Device Class Definition for HID 1.11 (HID1_11.pdf)
  • HID Usage Tables 1.12 (Hut1_12.pdf)
• Ruby documentation
• X11 manual