Command Line – xsetwacom

At first glance, Linux support for graphics tablets looks like a throwback to 15 years ago, when hardware support meant adding kernel modules and manual file configuration. However, a little digging shows that support for graphics tablets is actually strong in modern Linux, although unorthodox compared with support on Windows or OS X. A major part of that support is the command-line application xsetwacom – although it has a quirk or two of its own to overcome [1].

Graphics tablets generally consist of a tablet and a stylus, which commonly has an eraser on one end. The tablet is a representation of the computer screen, and the stylus – or in some models, fingers – are a replacement for a mouse. This arrangement allows graphic artists to work online with more precision than a mouse permits. Additionally, the stylus places far less stress on the hand, which makes it an ergonomic alternative to a mouse. (Figure 1).

Figure 1: Much like all graphics tablets, the Intuos Draw, an entry-level graphics tablet, is useful for both onscreen drawing and as an ergonomic mouse replacement. Copyright © 2017-2018 Wacom

Part of the trouble with using a graphics tablet under Linux is that manufacturers, including Wacom [2], the most popular choice among users, do not directly support Linux. Instead, with Wacom's encouragement, support is provided by the Linux Wacom Project [3]. The Project has done heroic work over the years, but its site is geared to developers, making it easy for end users to overlook basic information such as the table of supported tablets [4]. Instead, search results are likely to lead users first to outdated instructions that describe how to download the necessary kernel modules [5], and, if required, add the necessary lines to xorg.conf [6] to enable the tablet, stylus, and mouse.

This information may still be needed in some cases, but its prominence in search engines obscures the fact that support for dozens of graphics tablets is compiled in the kernels of many major distributions, which means that, these days, installation is generally no more complicated than plugging in the tablet. Users do not even need to install drivers; yet, new users who follow the first search results that come up can spend hours doing unnecessary setup.

Compounding the problem are two other peculiarities of Linux. First, graphics applications like Gimp and Krita have tools that enhance working with tablets, but which to the uninitiated often appear to be required and somewhat arcane. Second, utilities that give a control dialog similar to the one that Wacom ships for Windows are not keeping pace with the Linux Wacom Project. Since new tablet models are added every few kernel releases, new users are often puzzled by the fact that the lsusb command clearly shows that their operating system supports their graphics tablets, yet the tools in Gnome and KDE fail to detect the tablet that they are using to test the tools.

Enter xsetwacom, a command for adjusting on-the-fly how a Wacom tablet or a compatible tablet interacts with the X Window System (so far, the command does not run on Wayland). With dozens of options, it offers a similar degree of configurability to that found in Wacom's desktop tools for Windows and OS X, but in a less well organized way.

Oh, and one more small detail to note: Options set with xsetwacom last only until you log out or unplug the tablet. The next time you log in or reconnect, xsetwacom options have to be entered again. This limitation is less of a problem than it first appears, but it is still a nuisance to unsuspecting users who simply want to get their work done.

Fine-Tuning a Tablet

To begin using xsetwacom, you should familiarize yourself with its list commands. To modify many settings, you will need the name of the tablet, stylus, and – if present – the eraser. Start with the command:

xsetwacom --list devices

If the command detects the devices, then you are ready to use the tablet. This will also give you the device's proper names, which are needed to set options. Notice, too, that the tablet and stylus are separate devices. If the stylus includes an eraser, it will also be listed (Figure 2).

Figure 2: Supported tablets will list at least a tablet and a stylus; some will also include an eraser.

To see which parameters you can set, enter:

xsetwacom --list parameters

Parameters can be entered either using xsetwacom's --list option or, at the cost of a loss of flexibility, by adding them to /etc/X11/xorg.conf. Depending on the device, some parameters may not be supported if entered in xorg.conf, but you can check how to input a command by adding the -s option for a list of parameters supported only from the shell or -x for a list of those that can be added to xorg.conf, as well as the proper format for them (Figure 3).

Figure 3: xsetwacom supports dozens of parameters.

Generally, you will want to know what parameters can be added to your tablet in particular, so you will want to enter

xsetwacom --get 'DEVICE-NAME' all

which can also take the -s or -x option. All of these options return dozens of lines of results, so pipe through less so you can read them easily. You will find more details about individual parameters in the command's man pages (Figure 4).

Figure 4: Note how some parameters supported by xsetwacom are not available for this device, and some cannot be used in xorg.conf.

Study the parameters available for your device. When you are ready to add them, use the following command structure:

xsetwacom set 'DEVICE-NAME' PARAMETER VALUE

Except for errors, no feedback is provided unless you add the -v option.

Detailing all available parameters for all devices would require a small book. However, the most basic ones are those that affect general behavior. Almost all graphics tablets support switching the Mode parameter, toggling between Absolute, in which clicking with the stylus on the tablet automatically moves the cursor on the screen to a different position, and Relative, in which it does not. Every tablet I have tried is set by default to Absolute, where a point on the tablet corresponds to a point on the screen, which is easier for beginners to learn. However, more experienced uses often prefer Relative.

Another frequently used parameter is Area, which maps the tablet to the screen, using the values x1, y1, x2, and y2 to define the active area of the tablet by its corners. Some users may choose to shrink the active area of the tablet so that the cursor moves further with the same movement. Those with a square monitor, or some other unusually shaped screen, might also want to redefine Area, especially for use in Absolute mode. If your monitor rotates, an alternative to Area may be Rotate. Values to complete Rotate are none, half, cw (clockwise), and ccw (counterclockwise).

You might also want to toggle other functionality. For example, Touch can turn support for using fingers as a stylus on and off, and Gestures can do the same for controlling the position of the cursor on the screen with a small array of movements, rather like those that were used over a decade ago on Palm devices.

Other parameters set finer details of how the tablet operates. ScrollDistance, for instance, sets how far the stylus moves up or down when dragging on a window's scrollbar. The pressure needed to activate both the stylus and any eraser can be set with Threshold. Similarly, TapTime sets the fastest speed for activating a link or hotspot and is usually set to 250 milliseconds. And, because a stylus can be used without actually touching the screen, its CursorProximity (which is presumably set in millimeters, although the man page does not specify) can also affect performance. The Intuos line of Wacom tablets, whose lower end includes entry-level models, can operate as high a 105mm above the tablet, whereas the slightly more expensive Graphire line has a default of 42mm. Presumably, there is an upper limit to the setting, although it is undocumented.

However, by far the most popular parameter is the settings for the tablet or stylus buttons. These are used to write macros, using a set of modifiers that include command keys such as Ctrl and Alt, function and navigation tools, and special characters (Figure 5).

Figure 5: A partial list of supported modifiers for buttons.

A list of the more common modifiers is given when you enter the command:

xsetwacom --list modifiers

You can also add modifiers not listed by --list modifiers using the key symbols in /usr/include/X11/keysymdef.h. The XK_ prefix to each key symbol listed in keysymdef.h should be removed when entering the symbol in xsetwacom (Figure 6).

Figure 6: Part of the complete list of key symbols that can be used for modifying tablet buttons is available in /usr/include/X11/keysymdef.h.

Some tablet and stylus buttons may be programmed by default to emulate left and right mouse clicks or a scroll wheel. All these functions can be remapped to other buttons. In particular, stylus buttons can be awkward to use, so their default functionality might be shifted to the tablet buttons. Using modifiers, you can also program buttons for basic macros in commonly used applications, such as Cut, Copy, Paste, Save, Save as, Undo, and Redo, especially on higher end tablets, which usually have more buttons. Another common use for the buttons is adding special characters such as the pound or euro symbol, or for setting up an AltGr key for typing a whole array of diacritical marks. Some of these same shortcuts can be added to a keyboard, especially a programmable one, so how the tablet and stylus buttons are used can require some planning. In my experience, determining what to do with the array of available options is something to decide over time, as you gain experience and confidence with the tablet.

In all events, the command structure for programming buttons is:

xsetwacom --set 'DEVICE' BUTTON-ID 'key MODIFIER+MODIFIER'

On an Intuos Draw tablet, for example, to assign the Undo function to the first button on the tablet, the modifier at the end of the command would be:

xsetwacom  --set 'Wacom Intuos S 2 Pad pad'Button 1 'key Undo'

Pursuing Permanence

The fact that xsetwacom settings are temporary is often less of a concern than they might seem. Most of its options are not needed to use a graphics tablet as a mouse, and settings that affect drawing capabilities are retained in graphics applications like Gimp, Inkscape, or Krita – although settings do have to be enabled separately in each application.

Moreover, an obvious solution exists. Users can create a script that contains all their commonly used xsetwacom settings and either run it after they plug in their tablet, or, better yet, set it to run as they log in to their desktop environments. Alternatively, an .xsessionrc file can be created, and the settings placed in it. If users have other groups of options that they only need occasionally, they can create separate scripts to start those as well.

If someone asks if Linux supports graphics tablets, you can answer that basic support is built-in. Advanced options, though, require some extra effort, although usually not the module compiling and installation that an Internet search might suggest. True, those efforts are more than a modern Linux user expects, but if you are tempted to complain, just remember: Not too many years ago, this amount of extra effort or worse was required for printers, scanners, and even the mouse. If the current state of support is often less than convenient, it is still considerably better than nothing.