Linux Problems:Wacom Pen Buttons

Forward

The majority of this document is for documenting changes to the Wacom Pen Driver, end users that are more interested in the driver itself should proceed to The Driver.

Visit the TICC Bugzilla to report bugs in this application.

Kernel Approach

The kernel approach to using the Wacom "Pen Buttons" would be to integrate the commands generated by clicking the buttons into "proc" devices. This integration would allow a script to monitor each button and perform an operation when when of the buttons is pressed, while this solution is better in the long run I do not have sufficient experience to implement it quickly (Hoover). Until this solution can be implemented the X.Org driver should do, and over-riding the driver from the kernel level (ie: not passing on the button presses to the serial device) will effecitvely prevent conflicts from double implementation in the future.

X.Org Approach

Since ther kernel provides a serial interface to the Wacom Pen Buttons, X.Org receives all of the serial information available to the kernel. Since I have experience with X.Org input drivers I will be using this information to generate X11 events when a button is pressed, this means that a script must be running (or a hotkey configured) to capture the X11 event and perform an operation.

Compiling Ubuntu X.Org

1. Why? Unfortunately, in order to compile an X.Org driver (input or otherwise) you need a complete copy of the X.Org sources that you have compiled in place at least once. If you update your version of X.Org you will need to compile against the new sources, if you know a better way to do this then I'm all ears.
2. Compiling Xorg requires (that I didn't have):
   • bison
   • lots of time
3. Download Xorg Sources:

   apt-get source xorg
   

4. I copied the Linux config file to the appropriate location (this may not be necessary):

   cp ./xc/config/cf/linux.cf ./xc/config/cf/host.cf
   

5. The version I was compiling from Ubuntu requried me to download some files for "rman" (http://cvs.freedesktop.org/xorg/xc/extras/rman/) and copy them to the appropriate folder:

   ls ../xorg-6.8.2/xc/extras/rman/ && cp * ../xorg-6.8.2/xc/extras/rman/
   

6. Setup fontconfig:
   Unfortunately, Ubuntu X.Org requires some fontconfig files that are missing - I was unable to obtain these files from installing any of the fontconfig packages from apt so I was forced to go out and get them myself.
   • Setup with your system's info and some crutial directories:

     mkdir xorg-6.8.2/xc/lib/fc-glyphname/
     mkdir xorg-6.8.2/xc/extras/fontconfig/
     mkdir xorg-6.8.2/xc/extras/fontconfig/src/
     mkdir xorg-6.8.2/xc/extras/fontconfig/fc-cache/
     mkdir xorg-6.8.2/xc/extras/fontconfig/fc-case/
     mkdir xorg-6.8.2/xc/extras/fontconfig/fc-lang/
     mkdir xorg-6.8.2/xc/extras/fontconfig/fc-list/
     cp -R /usr/include/fontconfig/ xorg-6.8.2/xc/extras/fontconfig/
     

     (yes, you want it to be fontconfig/fontconfig/)

   • Download updated font config
     You need the information for fontconfig, so place the files fontconfig.pc.in, fonts.conf.in, and fonts.dtd in the same folder you just copied your local config to (xc/extras/fontconfig/). You can get these files here: http://cvs.freedesktop.org/xorg/xc/extras/fontconfig/
   • Download updated font config sources
     You need all of the files that belong in xc/extras/src/, you can download them from freedesktop.org: http://cvs.freedesktop.org/xorg/xc/extras/fontconfig/src/
   • Download updated font config cache
     You need all of the files that belong in xc/programs/fc-cache/ and xc/extras/fontconfig/fc-cache/, you can download them from freedesktop.org: http://cvs.freedesktop.org/xorg/xc/extras/fontconfig/fc-cache/. You should also download fc-cache.man from http://cvs.freedesktop.org/xorg/xc/programs/fc-cache/ and place that file in both directories.
   • Download updated font config list
     You need all of the files that belong in xc/programs/fc-list/ and xc/extras/fontconfig/fc-list/, you can download them from freedesktop.org: http://cvs.freedesktop.org/xorg/xc/extras/fontconfig/fc-list/. You should also download fc-list.man from http://cvs.freedesktop.org/xorg/xc/programs/fc-list/ and place it in both directories.
   • Download updated font config language files
     You need to place the files fclang.h and fc-lang.c in the folder xc/extras/fontconfig/fc-lang/, these files can be found at freedesktop.org: http://cvs.freedesktop.org/xorg/xc/extras/fontconfig/fc-lang/.
   • Download updated font config "case" information
     You need to download all the files at http://cvs.freedesktop.org/xorg/xc/extras/fontconfig/fc-case/ and place them in the folder /xc/extras/fontconfig/fc-case/.
   • Download updated font config glyphs
     You need to download all the files at http://cvs.freedesktop.org/xorg/xc/extras/fontconfig/fc-glyphname/ and place them in the folder xc/lib/fc-glyphname/.
   • Fix a syntax error in fcfreetype.c
     X.Org compiles without support for "//" style comments embedded in normal code (header files it doesn't care), in the file xorg-6.8.2/xc/lib/fontconfig/fcfreetype.c you should correct the syntax error on line 2780:

          // sort the tag list before returning it
     

     should become

          /* sort the tag list before returning it */
     

7. X.Org includes a deprecated Linux header file (/usr/include/linux/config.h) that is no-longer needed, the easiest thing to do to fix this problem is to comment out the first two lines of the file (by adding //).
8. Ubuntu compiles against GCC 3.4.5, in order for our driver to be compatible with the default installation we must do the same. The easiest way to accomplish this is to temporarily change the default gcc:

   cd /usr/bin
   mv gcc gcc.bak
   ln -s gcc-3.4 gcc
   

NOTE: I am actively working on this, these instructions are incomplete

Once these configuration steps are complete you should run "make World" from the folder xorg-6.8.2/xc/. Full compliation will fail, but enough of X.Org will be compiled to make use of the Wacom driver.

Modifying the Wacom Pen Driver

Once you have compiled X.Org for your current configuration you can make changes to the Wacom Pen Driver and recompile only that driver by typing "make" in its directory. The driver is located in the folder xorg-6.8.2/xc/programs/Xserver/hw/xfree86/input/wacom/, the file we are most interested in is "xf86Wacom.c" and the function "isdv4Parse".

Pen Button Command Structure

The Wacom Pen Driver uses 18 byte packets that give it all the information it needs for performing a given operation, for the "Button" operations a good example packet is when you click the left-most button (keyboard on the tc4200):

C1 01 00 00 00 00 00 00 00

This packet indicates that it is of the type "C1" (button press) and that button "1" was clicked. Known button values are "01" for the keyboard, "02" for rotate, and "04" for the Compaq button. Once the button has been depressed a very specific packet is issued (that is identical for all buttons):

08 06 17 1B 26 00 28 00 00

Code Changes

This section needs some fleshing out.

The current implementation of the driver provides the keys:

Pen Key Differences

Item	tc1100	tc4200
keyboard	0xd4	0xd1
rotate	0xd1	0xd2
Compaq	0xd2	0xd4

Unfortunately, this implementation does not have as good of a default calibration of absolute coordinates (my guess is that there are some patches I was missing). In order to get the best performance out of the tablet's pen feature we should probably just interface with the xsetwacom tool to provide a calibration feature anyway since the old calibration wasn't really that great anyway (check the user-space section).

On the topic of rotating the cursor, I believe I have a "superior method" for rotating the tablet cursor that will automagically use the information from the XRandR extension. If I get a little bit of time I will try out my theory and make the additional calls to xsetwacom unnecessary.

The Driver

And now, the magic you've all been waiting for...

Download Wacom Pen Driver w/ "Shortcut Button" Handling (Alpha Release)

The above package contains the modified source code and the binary, you should install "wacom_drv.o" into the folder "/usr/X11R6/lib/modules/input/". It is recommended that you backup your existing wacom_drv.o before attempting this experimental one, especially since it has only been tested on the tc4200.

User-Space Handling

In order for X.Org to handle the new software in user space you must modify your X.Org configuration file by adding in a new section:

Section "InputDevice"
        Identifier      "Wacom Pen Buttons"
        Driver          "wacom"
        Option          "Device"        "/dev/ttyS15"
        Option          "Type"          "buttons"
        Option          "ForceDevice"   "ISDV4"
EndSection

and link that new section into the system by adding a new line to the "ServerLayout" section:

        InputDevice     "Wacom Pen Buttons"      "SendCoreEvents"

The system should execute a script in order to process the key events, this requires a software package, xbindkeys, that we did not pre-install on the tablets. You can obtain xbindkeys from the Ubuntu repository:

sudo apt-get install xbindkeys

Once you have downloaded and installed xbindkeys you may configure it with an example file:

xbindkeys --defaults > ~/.xbindkeysrc

and add the necessary commands or you can make a new ~/.xbindkeysrc containing:

#######################
# Start Custom Config #
#######################

# Open the on-screen keyboard
"sh -c "pidof xvkbd && killall xvkbd || xvkbd""
  m:0x0 + c:209

# Rotate the display
"/usr/custom/bin/rotate.sh"
  m:0x0 + c:210

# Open Jarnal for Journal Editing
"/usr/custom/bin/jarnal"
  m:0x0 + c:212

#######################
# End Custom Config #
#######################

In order to use screen rotation, please see the FAQ on the topic. You can also download an example xbindkeysrc.conf that should work fine (provided you have the necessary applications installed). Once you have configured xbindkeys you can launch it by running:

xbindkeys -f xbindkeys.conf

or just "xbindkeys" if you have saved your config file in the default location (~/.xbindkeysrc). If you need to change your config you should first close the existing copy of xbindkeys and then you may reload it, you can kill xbindkeys by running:

kill `ps -A | grep xbindkeys`

at the command line. I recommend adding xbindkeys to your session startup commands, to do this you should add the following lines to the end of your /etc/kde3/kdm/Xsetup file:

# Ensure xbindkeys is run so the Wacom Pen Buttons are enabled
xbindkeys