Friday, September 3, 2010

Wacom support in Linux

This article should have been written a long long time ago. Anyway, here's the gist of Wacom tablet support under Linux and that hopefully clears up the confusion about the various packages.

The role of linuxwacom

linuxwacom is two things. It is the project name used for wacom-specific implementations and thus in the URL as well (in this post, I will always use "linuxwacom project" to refer to the project).

It is also the name of the tarball shipped by the linuxwacom project. Or at least the name of one tarball, anyway. Now, this tarball includes virtually everything linuxwacom as a project wants to provide, most notably a kernel driver, an X driver and several utilities. More on these later.

The main (and long-term) contributor to linuxwacom is still Ping Cheng, a Wacom employee. Wacom naturally has a strong focus on its customers and thus linuxwacom goes into some pains supporting systems all the way back to XFree86-4.

However, the X server has moved quite a bit.


In August 2009, I split out the X11 driver from the linuxwacom package and imported it into a git repository called xf86-input-wacom. This driver has seen quite a bit of rework, including dropping of some features (like XFree86-4 support but also old-style serial tablets) and gaining some features (like input device properties). The driver includes a simple tool called xsetwacom that provides some options to manipulate driver settings at runtime. xsetwacom used to be part of the linuxwacom tarball and I've tried to keep xsetwacom's interface as close to the original as possible.

As of a couple of weeks ago, the xf86-input-wacom driver also includes a simple isdv4-serial-debugger to print information about serial tablets. That's it though, xf86-input-wacom does not contain any other tools.

xf86-input-wacom supports serial devices directly and USB devices provided the kernel supports them. In that regard, it is quite similar to evdev or synaptics - both rely on the kernel for actual hardware support. If your kernel doesn't support a particular device, then xf86-input-wacom won't help.

Note that xf86-input-wacom is the replacement for the linuxwacom X driver, that driver will not compile on X servers 1.7 or later. And the name does not imply that it is for Wacom tablets only, we have code to handle some Waltop tablets and recently added a patch for Fujitsu serial devices. More devices will be added as needed.

kernel drivers

The linuxwacom tarball ships with several kernel drivers for various kernel versions. Note that these are out-of-tree drivers and thus if you compile them and then update your kernel, you must recompile and re-install the driver. This out-of-tree development is mostly due to Wacom's commitment to its customers.

Personally I would love to see kernel development happening on LKML only but this is not the case right now. Especially for newer models that support touch the upstream kernel requires the use of the MT protocol, something that the X drivers (neither xf86-input-wacom nor the old linuxwacom one) can handle right now. Especially Bamboos are affected by this. AFAIK, no distribution supports them out-of-the box and users must compile the kernel driver from the linuxwacom tarball. Once that driver is installed, xf86-input-wacom works fine with it.

This is a source of much confusion but while I intended to start working at the kernel drivers, I have enough things on my slate and I have yet to actually do so. Luckily, Henrik and others are working on it.

However, when I read "You may be tempted to download the 0.10.8 version if you have an X server >= 1.7. I tried this, but it did not work. Stick with the production driver, it will work." and (after compiling the kernel driver) "Now, plug in your tablet. It SHOULD be recognized and immediately function as a mouse. " on I cringed. What happens here is that after the kernel driver from the linuxwacom tarball was installed, xf86-input-wacom automatically picked it up. You need both parts, kernel and X driver.

wacdump, wacomcpl, and other tools

All these are still available in the linuxwacom tarball. wacdump provides similar functionality to evtest so I don't see the need for maintaining two tools that do the same thing. xidump does the same as xinput --test. Hence both tools are not available anymore on newer distributions.

wacomcpl is a major source of headache. It's a TCL wrapper around xsetwacom to provide a basic graphical configuration utility. It doesn't work anymore due to a number of subtle changes in the xsetwacom interface but also because it partially expects options that don't exist anymore (or in other forms) in the xf86-input-wacom driver. I thought about fixing it up but after looking at it I ran away screaming. I've traded some bugs with Bastien and he'll write a GNOME configuration utility. That's currently holding up on the need for an actual UI (and as engineers we both shouldn't do that one ourselves...) but it will hopefully see the light at some point in the near future. Meanwhile, no GUI configuration tool.

Future progress

The linuxwacom project is still largely controlled by Wacom, with the exception of xf86-input-wacom that's maintained by me but is heavily contributed to by Ping Cheng, both in patches and code review.

Wacom's internal processes are different to the ones we use in distributions and upstream and that can make life hard for us. (Likewise, our processes make life harder for Wacom so the finger-pointing goes both ways :) Ping and I have had plenty of discussions about this and we try to meet somewhere in the middle where possible, disrupting the project completely helps no-one.

xf86-input-wacom is in a reasonably good state now though the cleanup has taken much longer than expected and there are still several items to be removed or rewritten to fit into the new X server behaviours. I expect this work to take another couple of months but much of it is aimed ad making the driver easier to maintain and develop for. For the average user, it won't have as much impact.

As I said above, I'd like to see kernel development happen on LKML in upstream kernels, not in a separate tarball. This is - aside from the GUI tool - the most pressing issue right now.

How to help

As usual, the best way of helping out is to test the code that is available. I'm not a designer so if the tablet doesn't crash the server that's pretty close to 100% functional to me. I rely on others to tell me when behaviours change.

If you're a coder, get right in. If your device doesn't work, go for the upstream kernel and try to get it working there. Anything upstream will feed back into distros and thus improve the out-of-the-box experience. If you have feature-requests for xf86-input-wacom, dig in and write it. The developer's mailing list is useful in any case. Finally, there's the wiki that will eventually be a useful one, but I keep getting distracted with other stuff whenever I try to move info over. So any help there will be useful to others looking for documentation.

And as I pointed out above - we're in desparate need for a UI for the GNOME config utility. If you're interested in helping out here, please contact me.

Finally, I want to point out that Ping (and by inference Wacom Inc.) has been excellent and though we sometimes disagree on technical issues there is no question that Wacom is supportive of the project and their contributions are invaluable.


duffy said...

"And as I pointed out above - we're in desparate need for a UI for the GNOME config utility. If you're interested in helping out here, please contact me."

I would be very happy to help with UI mockups!!!!

Peter Hutterer said...

Yes please! I personally don't even know what options are useful for the average designer. e.g. is rotation needed? How about tablet area, screen-to-tablet mappings, button reconfigurations, etc.?

The wacom driver has a zillion options but I don't know which ones are commonly used or even needed.

It's literally holding on the lack of a UI, so anything that gets us closer to having one will get the tool finished sooner.

spb_nick said...

Thanks for writing this up :)!

I have checked out xf86-input-wacom yesterday and found the Waltop stuff.

I see you got something in from the manufacturer's driver, but what about the kernel side? Did you do anything in the kernel? If yes, where can I see it? If not, how do you plan to make the Waltop tablets work?

Is linuxwacom-devel suitable for xf86-input-wacom discussion?

Peter Hutterer said...

yes, linuxwacom-devel is for xf86-input-wacom as well and all the patches go on review there.

as for the waltop devices. Timo Aaltonen had kernel patches for it at some point but I don't know the current state of it. I don't have a device myself.

jimmac said...

Mairin: The UI design part is happening here --

hadess said...

Note that we're currently only interested in separate tablets, not tablet PCs, which are a different thing (though using a similar set of drivers), for the tablet configuration tool.

And the reason why I'm not designing the UI is because I don't have experience with tablets, not because I'm an engineer ;)

olejorgenb said...

There is an abandoned gui tool here

Now.. looking at the source it seems the interface for xsetwacom have changed quite a bit. Aside from the change to '--action' (*) instead of 'action', it seems like you now have to parse the output from '--list params' to get the default, whereas in the old version you could use 'getdefault'.

I'm sure there is good reasons for this, but saying "I've tried to keep xsetwacom's interface as close to the original as possible" seems a bit of an overstatement? ;)

When that is said, I do much prefer you spending your time with more important things. Thanks for the work, and for writing up this post.

I was just about to try old versions of the wacom_drw to see if they would work with the binary nvidia driver on my tablet pc. You've saved me from _lots_ of frustration.

(*) my thought here is that if the tool require an option, you might as well do as eg. git and make it a "sub command". typing the -- is a waste. I guess not all option parsing libraries support this properly though.

Peter Hutterer said...

xsetwacom will take both --list and list. it will also parse some values in multiple formats (e.g. rotation as "CW", "CCW", ... or as number) to provide both a useful commandline interface and the backwards compatibility with the old interface.

getdefault relied on bits implemented in the driver and support for that has been removed. to me getdefault is just one of the features mentioned that have been cleaned up. why that was removed is a long story, but the short version is that the driver should IMO not expose it's built-in defaults to the clients in that manner.

olejorgenb said...

Ups, I swear I tried the old format. Looking at the history it seems I forgot to specify the device name when testing 'get'.

alpha said...

I want share with you
I little software that
I have done thinking on
wacom pad

Ardesia 0.4 is out!

Ardesia allows to draw and sketchup everywhere

The binary package is released for Ubuntu Lucid and Windows 7
you can use Ardesia with all the linux flavours, the source code
is free and released under the GPL terms

You can use it with a wiimote whiteboard or a graphic tablet;
in this way the lines are writing lighter or darker depending on
the pen pressure

You can export your work in the pdf format to create simple presentation, tutorial or document

Ardesia allow to record and the stream on icecast streaming server
thanks to the vlc media player and streamer

…Ardesia is free and simple as you are; Try it now!

Ian said...

Absolutely, I'm very interested in testing and providing input for a wacom configuration front-end. At my company we have hundreds of wacom Cintiqs and Tablets using the Linuxwacom package and a number of different sorts of setup. I'd considered creating a functional front-end for our needs, but if someone else is already developing one, it would be better to pool efforts!

nh2 said...

I just found this:

It does not have a lot of options yet, but might be a starting point.

Peter said...

Peter, could you help me to understand how we should configure wacom attached trough serial port. Do I understand correctly, that static configuration is the only way to go?