<runkel@runkeledv.de>
Copyright (c) 1999,2000 by Stefan Runkel Runkel@runkeledv.de
This document describes the installation of Wacom tablets under linux.
It may be distributed, at your choice, under either the terms
of the GNU Public License version 2 or later or the standard Linux
Documentation Project terms. These licenses should be available from where you
got this document. Please note that since the LDP terms don't allow
modification (other than translation), modified versions can be assumed to be
distributed under the GPL.
Graphic tablets are now quite inexpensive and can help allot with the work of image manipulation. In addition to that what a mouse can do for you they have the following features:
This document addresses mainly the products from Wacom, because I own 3 different products of them and because their products are highly available in the region of Europe.
Nevertheless I think it should be easy to adapt the shown concepts to other products.
I have written this document because I have not found a document about this subject which contained completely what I wanted to know. So I got small parts of information from various people in the net and assembled them to this HOWTO. Regarding the questions of my readers, I must realize that this document also is not complete and never will be. But from the same questions I can tell that it helped many people on the way, and each new question lets this HOWTO grow.
The latest version of this document will be available at http://www.runkeledv.de/linux.htm .
Comments, corrections, and additions are greatly be appreciated. I can be contacted at:
Runkel@runkeledv.de or at RunkelEDV@t-online.de
I would like to thank all authors listed in the Further Information / used documents Section as well as everyone who answered my questions by email. This HOWTO reflects much of their work.
This chapter is about what is needed to get your tablet working.
First of all, you should have a tablet, of course. This should be a product that connects to the serial port (RS232) of your computer, because USB support for linux is still under development. At the time of writing (Mar 2000) kernel support starts for the newer usb products graphire and intuos, and it is worked on the XFree driver. Gpm is unmaintained for now, so we can not expect an usb driver for it in the near future.
The following Wacom tablets are supported:
The older SD and HD series are not supported by the standard XFree86 driver, however, a modified driver that supports these devices as well some OEM products with embedded screens including the IBM Thinkpad 360 PE and Toshiba T200 is available from: http://hwr.nici.kun.nl/pen-computing/pen-computing-formats.html
There is a big number of programs based on the gtk library. The gtk has XInput
support and makes it very easy to use.
At least the following applications support XInput:
xink is available from: ftp://kiwi.cs.berkeley.edu/pub/raph/xink.tar.gz
The gpm daemon supports allot of input devices, including tablets. If you want a list of the supported devices of your gpm, do a
gpm -t help
The Wacom driver of gpm 1.18.0 and below seems to be for the very old artpad models, the documentation does not say anything about this. I tested it with ultrapad, penpartner, graphire and intuos models but it did not work. I have rewritten the wacom driver for gpm, to use it you need at least gpm version 1.18.2 . Since 1.18.2, the old wacom driver has been replaced with my driver for wacom graphire, penpartner and ultrapad products.
However, if you own an old artpad, use gpm < 1.18.1 and try:
killall gpm ; gpm -t wacom -m /dev/ttyS0
If you own a graphire, use gpm > 1.18.1 instead and use
for the relative (mouse-like) mode:
killall gpm ; gpm -t wacom -o relative -m /dev/ttyS0
killall gpm ; gpm -t wacom -o absolute -m /dev/ttyS0
Of course, you get only the buttons and the movement
function, pressure and tilt are not supported because they are not too useful
in text-based applications.
There is no support for ultrapad macro buttons or graphire mouse wheel.
If you use gpm and XFree86, you may or may not run in problems, because normally a device can be opened only by one program at a time. There are two solutions for that:
If you want to omit the translation and only get the data byte for byte, just call gpm -t ps2 -R raw . You can then make XFree use that second device by putting the line Device "/dev/gpmdata" in your XF86Config in the pointer section or the XInput section.
Minimum XFree version should be 3.3.3.1 because this version has extended XInput support, the second side switch works now and the blocking mouse effect has been fixed.
If you must use any prior version, XInput support should be available since 3.1.2.d.
XInput support in XFree is configured basically in a file called XF86Config. In most cases the XF86Config file is located in /etc or in /etc/x11. I will show now a very short configuration section and explain then what can be changed and why this is needed.
Section "Module"
# Wacom Device Driver
Load "xf86Wacom.so"
EndSection
Section "XInput"
# Settings for Wacom pen
SubSection "WacomStylus" # type of input device
Port "/dev/ttyS0" # Serial Port
DeviceName "Pen1" # Name, choose it free
Baudrate 9600 # Usable only for intuos
Mode Absolute # Map Tablet Area to Screen
AlwaysCore # See text
HistorySize 200 # Buffer size for motion events
EndSubSection
EndSection
XInput support in XFree is reached due to the use of modules. The device driver module for Wacom is called xf86Wacom.so . This goes to the "Module" section and has to be appear only once per XF86Config file.
The penpartner and graphire products simply recognize the type of a device, but they can not distinguish them. For example, you can not use two different pens, say, one configured red and one configured blue - all what these products say is: "I found a pen tip on my surface", or "I found an Eraser on my surface", or "I found a mouse on my surface".
XInput maps the device types to devices, these device types are later specified in the XF86Config as a subsection in the Section XInput:
WacomStylus
Tip of a pen or airbrushWacomEraser
Eraser of a pen or airbrushWacomCursor
Mice, like graphire mouse, lens cursor, 4d-mouse
You must give every configured device a unique name. This name will be used later in your program to talk to that device. You can choose this name free.
XInput wants to know at which serial port this device can be found. This allows me to use two different tablets at the same time, for example a graphire connected to /dev/ttyS0 and a penpartner connected to /dev/ttyS1.
This statement controls how verbose the Wacom driver is. The Level goes from 0 to 10. If this statement is not given, DebugLevel 0 is used, which logs the very less.
Example:
SubSection "WacomStylus" # Pen
DeviceName "PenRed" # Name, choose it free
...
DebugLevel 10 # be very verbose
...
EndSubSection
The intuos product is more efficient than penpartner and graphire because it can distinguish many devices of the same type. This means that it is now possible to use two pens, one configured red and one configured blue. As you see, the use of device types is not enough information to handle different pens. Therefore, each intuos device, be it a pen, ink pen, mouse, or whatever has a serial number, which you can specify to aid XInput in resolving the right device. This would look like:
Section "XInput"
SubSection "WacomStylus" # Pen
DeviceName "PenRed" # Name, choose it free
...
Serial 2609917443 # Serial Number of that device
...
EndSubSection
SubSection "WacomStylus" # another Pen
DeviceName "PenBlue" # Name, choose it free
...
Serial 2609918664 # Serial Number of that device
...
EndSubSection
EndSection
It should be said that combined input devices like pens have only one serial number. The driver uses the serial number it gets to recognize one specific pen and the device type to distinguish the tip of that specific pen from its eraser.
You should get a list of your different numbers.
BEGIN xf86WcmProc dev=0x8354d60 priv=0x833e3f0 type=stylus flags=9 what=1
xf86WcmProc pWcm=0x8354d60 what=ON
END xf86WcmProc Success what=1 dev=0x8354d60 priv=0x833e3f0
device_id=0x96 serial_num=2595227137 type=cursor
[cursor] abs prox=false x=0 y=0 z=0 button=false buttons=0
If you set a device in mode absolute, this means, that the active area of the tablet will be mapped to the screen. Every time you go down to the tablet at the same point with an absolute device the pointer will appear at the same point of the screen.
If you set a device in mode relative, you will get the well known behavior of a mouse. This means, that if you take the mouse off from the surface, move it and go down again, the pointer does (ideally) not move.
Example:
Mode Absolute
XFree knows two pointers: one with only the standard features (buttons, moving-capabilities), which is used for selecting menus, text, clicking buttons and doing other controlling stuff. This is the Core Device.
The other pointer is used by applications which want more information, like
pressure and tilt.
This is the extension device.
Starting with version 3.3.3.1, the Statement AlwaysCore tells the driver that it should send both types of events.
If you do not specify Alwayscore in your XF86Config, then this device is initially used as extension device, this means it is usable only in applications but you can not control the menus of your window manager with it.
If Alwayscore is given, then your device acts as core pointer (in addition to the mouse) as well as it sends tilt and pressure information to applications which opened the device in extension mode.
You can configure two different logical devices, one in Core-Mode and one in
Extension-Mode, to the same physical device.
To do so, simply type two identical sections, only the DeviceName statement must differ. Then specify AlwaysCore
only for the last section.
Example:
AlwaysCore
This statement sets the buffer size that is used to cache motion events.
This statement specifies how many units the device must move before the driver moves the pointer. This can be necessary if very large resolutions are used.
Example:
Suppress 6
TiltMode enables sending of tilt information for intuos devices. If this statement is missing, only pressure information is transferred.
These four statements allow to reduce the active area of the tablet. My intuos
A4 oversize, for example, is so big that you can not do painting work with it
because the ways of the pen are too long. I use these four Statements to tell
the driver that it should map only the lower left quarter of the tablet to the
screen.
It is possible to define more than one active area on the same tablet:
Define as many subsections as you need with the same Port Statement but with
different Top... statements and Devicenames. This results in multiple logical
devices all of them restricted to their individual bounds. You may use
one device in absolute mode and one in relative mode as well.
Example:
TopX 0 #coord of top left point
TopY 5000
BottomX 5000 #coord of bottom right point
BottomY 10000
If you use the above four statements, you sometimes want to make some calculations on the size and position of the rectangle to be defined. Often the maximal tablet coordinates and the resolution are needed for this. To get these values, start your server: X 2>t. Kill the X-Server (usually Ctrl+Alt+Backspace) and do a grep "X=" t .You should get back the values in question.
(--) Wacom IV tablet maximum X=5103 maximum Y=3711 X
resolution=1000 Y resolution=1000 suppress=6
(--) Wacom tablet top X=0 top Y=0 bottom X=5103 bottom Y=3711
(--) Wacom tablet top X=0 top Y=0 bottom X=5103 bottom Y=3711
(--) Wacom tablet top X=0 top Y=0 bottom X=5103 bottom Y=3711
This option uses the TopX, TopY statements (or their built in defaults, if omitted) and adjusts the BottomX, BottomY statements so that
Any given BottomX, BottomY statement is ignored, because these values will be calculated.
This is available since alpha 16 and is used to control the minimum pressure that is needed to detect that a tool is pressed on the surface. It works with intuos and graphire. Please note that the integer value has to be coded as String, unlike all other integer values.
Example:
Threshold "5"
Gimp has built-in XInput support since Version 1.1.x.
Gimp must know which devices it should use and in what mode. You have to open the File/Dialogs/Input Devices - dialog for setting this up. You will find two listbox-controls at the top of that window labeled Device and Mode . Choose the device to set up from the Device control and choose a mode from the Mode -control.
The modes are:
If you see two cursors linked to your device, you have two solutions:
Below the two listbox-controls there is a tab-control with the two register tabs Axes and Keys . Axes assigns an axis a function, it is mostly not necessary to change this. But think about a touch-screen device which is built in a table rotated by 90 degrees, then you might want to swap the x and y axis.
Some tablets have so called macro keys at the top which may hold some often used functions. The
Keys
tab lets you assign a character to a macro key. For example, you can put Ctrl+Shift+R, to a macro key. If you
activate this key, then the rulers are toggled.
The current Wacom driver supports only the macro keys of the ultrapad series,
the macro area of the intuos products is not yet usable for that.
Now we should talk about how the devices can be used. Open the File/Dialogs/Device Status -dialog. Open an image.
You set up each device independently from each other in gimp.
If you move the cursor with different devices in the image window you can see the devices change in the Device Status dialog. If you pick a tool, brush, pattern or color with a device, again the changes are reflected in the dialog. You can save the settings in the Status Dialog, so that they will be restored before your next session.
This is a special device that is always present. It generates an event every time a new device becomes the core pointer. It has a pseudo "axis". The "value" of this axis is the id of the core pointer device. I do not know what a user can do with it - this is mainly helpful for internal use.
The buttons of the devices are as different as the devices are:
A pen has at least a tip, but it may have one or two side switches and an
eraser. A mouse may have up to 32 buttons (but usually 3). Buttons are numbered
from 1 to the number of buttons. With the next two utilities you can change, to
what number a button is mapped.
xmodmap will only modify the Core Pointer. As there is only one Core pointer at a time, it makes no difference between the physical devices which may become the Core Pointer. For the moment, let us forget the whole XInput stuff and think of a left-hander who just wants to swap the left and right mouse buttons. You would execute xmodmap -pp to look what the current assignment is. You should get the following table back:
Physical Button
Button Code
1 1 # ( Left Button )
2 2 # ( Right Button )
3 3 # ( Middle Button )
To swap the buttons, you do a xmodmap -e "pointer = 2 1 3" , and to get back, xmodmap -e "pointer = default" . This should work with every device with at least two buttons. Note that the term "pointer = x x x" has to be quoted to prevent it from being changed by the shell.
Back to XInput now. If you use the gimp, you may want to change the button mapping for each device separately (may be you are happy with the mouse but want to swap the two side-switches of the pen). Frederic Lepied has written a utility called xinput for that.
To swap the side-switches, you would do a xinput list to get a list of the devices and their current settings. Swapping is done with xinput set-button-map Pen1 1 3 2 where Pen1 is the Device to change.
Starting with XFree 3.3.2 this works also with devices that are configured AlwaysCore in XF86Config.
With xsetmode you can change the mode of a device between absolute and relative.
Example:
xsetmode GraphireMouse ABSOLUTE
.
If you have none of your devices configured AlwaysCore and you want a device to become the core-pointer, then xsetpointer must be used.
Do a xsetpointer Devicename . The old core-device (usually the mouse) is not usable anymore and the one you specified should be active. For example I can make the graphire mouse the standard core device from within a running XFree.
xsetpointer -l lists all devices and the modes they are in.
Some devices have macro keys or pads on them, to which a scancode or string may be assigned. This works only for devices in extension mode and is therefore done in the application you want use the keys with.
xinput -l gives information about the number of keys and things like the first scancode.
I own myself 3 tablets of Wacom and use them on my notebook. Whenever no tablets are connected and I start X, I have to wait very long until the driver gives up. If xdm is used, this increases to multiple of that timeouts.
I have written two utilities which should make live easier with that:
The concept behind this is that a XF86Config file is split in at least a XF86Config.bare file, which holds the information common to all configurations, and various snippets, each of them holding the special information for a particular configuration.
The two utilities will then concat the parts back to a working configuration.
You can get this packet from http://www.runkeledv.de/download , it is named xinput_chooser_sr.
It seems that you have not compiled your gtk with XInput-support. Please rebuild gtk and use ./configure --with-xinput=xfree for building the Makefile. Then do a make && make install. Then rebuild your gimp so that it uses this extendet gtk.
Yes, it generates button 4 and button 5 events.
read the section about Serial_Num
Read the section about buttons.
You can not use the intuos macro area, sorry.
Only Artpad / Ultrapad Macro stripes work.
Read the section about
Gimp Keys.
Yes, read the section about the Top... Statements
Yes, read the section about the Port Statement
You probably mixed a new gpm with an old gpm library. Or You use an old client which searches the socket gpmctl in /var/run instead in /dev. In the later case you have two options: get new clients and recompile them or change gpm.h so that it uses /var/run instead of /dev and recompile gpm and libgpm.
gpm:
gpm man page, gpm FAQ, source code file mice.c
XInput:
XInput HOWTO by Owen Taylor
XFree and Wacom:
XF86Config man page
Frederic Lepied's site
much, much, e-mails...