6.0 - Viewing XInput Events (xidump)

The xidump program is similar to wacdump, but it parses and displays event data from the XFree86 XInput extension rather than from the tablet itself. This is useful for seeing what programs like gimp and gsumi are receiving from X.

Presently, xidump will display proximity and motion events for the stylus, cursor, eraser, and pad input devices. xidump supports different display modes with "curses" and "raw" modes already implemented and a GTK-based graphical mode in the works. The curses mode is probably the most useful in terms of verifying that the tablet is functioning correctly in the XFree environment; however, the raw mode has the additional benefit of being able to verify the order, timing, and history of events.

Since xidump uses the same XInput interface that gimp and gsumi use to get tablet data, the values displayed in xidump should be identical to what they are receiving. If you are having trouble with pressure in gimp, chances are that xidump will demonstrate the same problem. xidump does not require root access to use.

Running xidump

xidump takes one argument, the input device specified in your XF86Config/xorg.conf file. It is the Identifier entry in the InputDevice section. Normally they are either stylus, cursor, eraser, touch, or pad. You can get a complete list by running xidump with the list option '-l'. xidump has the additional feature of dumping all the device capabilities by specifying the verbose option '-v'. Both are demonstrated below.

Note: The device identifiers (input_device) are case sensitive.

[jej@ayukawa src]$ ./xidump -l
eraser                         extension
stylus                         extension
cursor                         extension
Mouse0                         disabled
keyboard                       keyboard

[jej@ayukawa src]$ ./xidump -l -v eraser
eraser                         extension
    key: min=8, max=39, num=32
    btn: num=1
    val: axes=6 mode=abs buf=0
    axis[0]: res=2540, min=0, max=30480
    axis[1]: res=2540, min=0, max=30480
    axis[2]: res=1, min=0, max=1023
    axis[3]: res=1, min=-64, max=63
    axis[4]: res=1, min=-64, max=63
    axis[5]: res=1, min=0, max=1023

In the first dump, we see the eraser, stylus, and cursor with the additional Mouse0 pointer and keyboard. Only the first three are "extension" devices. Using xidump on the keyboard or mouse pointer will generate an error since neither are XInput devices.

The second dump shows the capabilities of the eraser device including the number of keys (32), buttons (1), and axes (6). It also shows the mode to be absolute. In order, the axes are: x, y, pressure, tilt-x, tilt-y, and wheel. When the cursor is used, axis 3 becomes z-rotation instead of tilt-x.

You should be aware that xidump and gimp must take ownership of the device in order to get real-time data. This creates a conflict if you are running both of them simultaneously. gimp is the more clever of the two programs in that it only "grabs" the input device if you are hovering over the gimp drawing window. xidump is less friendly. In order to display the absolute position across the entire screen, it creates a small "listening window," grabs the device immediately, and does not release it until you quit the program. Neither program should fail, but you will not be able to draw in gimp and run xidump at the same time if they are both using the same input device.

We will run xidump in raw mode for the first time to see the stylus events directly. A small window will appear on the desktop while xidump runs; you can safely ignore it. Closing it will kill the application.

[jej@ayukawa src]$ ./xidump -u raw stylus
14.56291895: Proximity In
14.56305595: Motion: x= +5978 y=+28728 p=   0 tx= +64 ty= +64 w=   +0 ID: 2323 Serial:         -60
...
16.87158095: Motion: x= +4941 y=+27842 p= 225 tx= +41 ty= +67 w=   +0 ID: 2323 Serial:         -60
16.87164395: Button: 1 DOWN
16.87169595: Motion: x= +4964 y=+27844 p= 398 tx= +42 ty= +66 w=   +0 ID: 2323 Serial:         -60
...
17.27328395: Motion: x= +5261 y=+27543 p=   3 tx= +48 ty= +64 w=   +0 ID: 2323 Serial:         -60
17.27334395: Button: 1 UP
17.27515995: Motion: x= +5348 y=+27451 p=   4 tx= +48 ty= +63 w=   +0 ID: 2323 Serial:         -60
...
17.35933795: Motion: x= +7089 y=+27061 p=   4 tx= +48 ty= +63 w=   +0 ID: 2323 Serial:         -60
17.37444395: Proximity Out
<Ctrl-C>

The timestamp on the left is seconds elapsed; the next field is the event type. Mostly, you will encounter motion events although I've trimmed many of them out of this listing. As you can see from the above, the first line is a "proximity in" event which indicates the stylus came in range of the tablet. The last event was a "proximity out." At 16.87 seconds, I tapped the stylus to the tablet surface as recorded by the "Button: 1 DOWN" and subsequent "UP" message. Raw mode is useful for verifying the order and timing of messages, but is not particularly clean. The ncurses mode works much better.

[jej@ayukawa src]$ ./xidump stylus
InputDevice: stylus
Valuators: Absolute   ID:      2323  Serial Number:          -60

             x-axis    y-axis   pressure   x-tilt    y-tilt     wheel
     data:  +10826    +09919    +00084    +00058    +00065    +00000
      min:  +00000    +00000    +00000    -00064    -00064    +00000
      max:  +30480    +30480    +01023    +00063    +00063    +01023
      res:  +00000    +00000    +00039    +00001    +00001    +00001

********
Proximity:  IN
    Focus:
  Buttons:  1-DOWN
     Keys:

All of the ranges are displayed above, include their resolutions which as far as I know are not normally used. Only the proximity, focus, valuator, and button events are currently implemented.

For completeness sake, here are the command line options:

Usage: xidump [options] input_device
  -h, --help          - usage
  -v, --verbose       - verbose
  -V, --version       - version
  -l, --list          - list available input devices
  -u, --ui ui_type    - use specified ui, see below

Use --list option for input_device choices
UI types: curses, raw

There are not many options, but the --list option is helpful for identifying devices, and the --ui option allows you to switch between curses and raw modes. Adding the --verbose option increases the amount of output, and when used in conjunction with --list, displays the device capabilities.