9.0 - Using xsetwacom

The xsetwacom is a command-line Wacom driver configuration tool. It changes the pressure sensitivity, click threshold, button functions, cursor mode and speed, and much more without having to manually modify XF86Config or xorg.conf file.

The basic usage and options can be viewed by issuing xsetwacom

[jej@ayukawa linuxwacom]$xsetwacom
Usage: xsetwacom [options] [command [arguments...]]
Options:
  -h, --help                 - usage
  -v, --verbose              - verbose output
  -V, --version              - version info
  -d, --display disp_name    - override default display
  -s, --shell                - generate shell commands for 'get'
  -x, --xconf                - generate X.conf lines for 'get'

Commands:
  list [dev|param]       - display known devices, parameters
  list mod                   - display supported modifier and specific keys for keystokes
  set dev_name param [values...]   - set device parameter by name
  get dev_name param [param...] - get current device parameter(s) value by name
  getdefault dev_name param [param...] - get device parameter(s) default value by name

xsetwacom supports 3 forms of get/getdefault commands: xsetwacom get returns the parameter's raw value; xsetwacom -x get returns the value in Xorg.conf form; and xsetwacom -s get returns the value in shell command form.

The most used xsetwacom command is xsetwacom set dev_name param [values...], where param is an option which will be set to values in wacom_drv.o after excuting xsetwacom. To better understand the use of this command, let's see some examples. Assume that you use Stylus as your Wacom tool's Identifier, which is considered as dev_name in xsetwacom command.

If you want to change Stylus's mode from absolute (default) to relative, then:

[jej@ayukawa linuxwacom]$xsetwacom set Stylus mode relative

If you want to change button 2 to left-double-click, then:

[jej@ayukawa linuxwacom]$xsetwacom set Stylus button2 "dblclick 1"

If you want to change button 2 to button 5, then:

[jej@ayukawa linuxwacom]$xsetwacom set Stylus Button2 "button 5"
or 
[jej@ayukawa linuxwacom]$xsetwacom set Stylus Button2 5

If you want to change button 3 to ModeToggle, then:

[jej@ayukawa linuxwacom]$xsetwacom set Stylus button3 modetoggle

If you want to know what the current (or default) pressure sensitivity setting is, then:

[jej@ayukawa linuxwacom]$xsetwacom -s get Stylus PressCurve (output in xsetwacom format)
xsetwacom set stylus PressCurve "0 15 85 100"
or
[jej@ayukawa linuxwacom]$xsetwacom -x get Stylus PressCurve (output in xorg.conf Option format)
        Option  "PressCurve"    "0,15,85,100"

[jej@ayukawa linuxwacom]$xsetwacom -x getdefault Stylus PressCurve 
        Option  "PressCurve"    "0,0,100,100"

If you want to set the pressure sensitivity a bit softer, then:

[jej@ayukawa linuxwacom]$xsetwacom set Stylus PressCurve 0 15 85 100

If you want the buttons behave the Tablet PC way, i.e., sending button event only when button1 (the tip) is pressed, then:

[jej@ayukawa linuxwacom]$xsetwacom set Stylus TPCButton on

If you want to change pad's button 1 to ctrl alt F2, then:

[jej@ayukawa linuxwacom]$xsetwacom set pad Button1 "core key ctrl alt F2"

If you want to change pad's button 2 to ctrl alt backspace, then:

[jej@ayukawa linuxwacom]$xsetwacom set pad Button2 "core key ctrl alt backspace"

xsetwacom supported parameters

Below is a list of the parameters and their values used by xsetwacom command (a similar output can be viewed by xsetwacom list param. All functions apply to the associated tool unless explicitly stated otherwise):

   param         [values...]              results
------------------------------------------------------------------
   Mode          Relative|Absolute        sets the mode of the device
   TopX          integer                  sets the X coordinate of the top corner of the active zone
   TopY          integer                  sets the Y coordinate of the top corner of the active zone
   BottomX       integer                  sets the X coordinate of the bottom corner of the active zone
   BottomY       integer                  sets the Y coordinate of the bottom corner of the active zone
   STopXi        integer                  returns screen i left coordinate in pixels
   STopYi        integer                  returns screen i top coordinate in pixels
   SBottomXi     integer                  returns screen i right coordinate in pixels
   SBottomYi     integer                  returns screen i bottom coordinate in pixels
   ButtonM       integer|keystroke        sets button M to button integer click or keystroke
   ButtonM       0                        ignores button M click
   RelWUp        integer|keystroke        sets relative wheel up to button click or keystroke
   RelWDn        integer|keystroke        sets relative wheel down to button click or keystroke
   AbsWUp        integer|keystroke        sets absolute wheel up to button click or keystroke
   AbsWDn        integer|keystroke        sets absolute wheel down to button click
   StripLUp      integer|keystroke        sets left strip up to button click or keystroke
   StripLDn      integer|keystroke        sets left strip down to button click or keystroke
   StripRUp      integer|keystroke        sets right strip up to button click or keystroke
   StripRDn      integer|keystroke        sets right strip down to button click or keystroke
   PressCurve    i1 i2 i3 i4              sets the pressure bezier curve, where i1+i4=100; i2+i3=100
   DebugLevel    integer (0 - 12)         sets the level of debugging trace for the specified tool
   CommonDBG     integer (0 - 12)         sets the level of debugging trace for all tools 
				          associated with the same tablet.
   Suppress      integer (0 - 100)        number of data trimmed for the tools associated 
					  with the same tablet.
   Screen_No     integer (-1 - 5)         sets screen number the tablet is mapped to.
   TwinView      none|vertical|horizontal sets the mapping to TwinView.
   TVResolution0 width x height           sets MetaModes option for TwinView Screen 0.
   TVResolution1 width x height           sets MetaModes option for TwinView Screen 1.
   SpeedLevel    integer (1 - 11)         sets relative cursor movement speed
   ClickForce    integer (1 - 21)         sets tip/eraser pressure threshold
   xyDefault                              resets the bounding coordinates to default in tablet units
   mmonitor      on|off                   turns on/off across monitor movement on (non-TwinView) 
				          multi-monitor desktop
   TPCButton     on|off                   turns on/off the buttons as Tablet PC buttons
   CursorProx    integer (distance)       sets cursor distance margin for proximity-out 
				          in distance from the tablet surface
   Rotate        none|cw|ccw|half         sets the rotation of the tablet. 
   ToolID           	                  returns the ID of the associated device.
   ToolSerial       	                  returns the serial number of the associated device.
   GetTabletID/TabletID     	          returns the tablet ID of the associated device.
   NumScreen             	          returns number of screens configured for the desktop.
------------------------------------------------------------------

Event description format:
[CORE] [EVENT TYPE] [MODIFIERS] [CODE]
  CORE: Emit core events irrespective of the SendCoreEvents setting
  EVENT TYPE: the type of event to emit:
        KEY: Emit a key event
        BUTTON: Emit a button event
        DBLCLICK: Emit a double-click button event
        MODETOGGLE: Toggle absolute/relative tablet mode
	DISPLAYTOGGLE: Toggle cursor movement among screens
		for the selected tool except pad which
		applies to all tools asssociated with the tablet
  MODIFIERS: use "xsetwacom list mod"
        to see a list of modifiers and specific keys
  CODE: Button number if emit a button event
        or specific keys and any other keys not listed as mod

Associating parameters to physical devices

Following is a list of the parameters that are associated with the elements of devcies.

   param		tools
--------------------------------------------------------------------------
Button#			All Wacom styli/pucks buttons 
			Tablet ExpressKeys
RelWUp/RelWDn		Graphire4 tablet wheel 
			Wacom puck Fingerwheel
AbsWUp/AbsWDn		Intuos puck Thumbwheel
			Intuos Airbrush Fingerwheel
			Bamboo tabelt Touch Ring
StripLUp/StripLUp	Left Touch Strip on Intuos3 and V5 Cintiq (Cintiq 21UX/12WX/20WSX) tablets
StripRUp/StripRUp	Right Touch Strip on Intuos3 and V5 Cintiq (Cintiq 21UX/12WX/20WSX) tablets
--------------------------------------------------------------------------

Automatically excuting predefined xsetwacom commands at logging in

The xsetwacom commands can be added to the .xinitrc under your home directory so next time when you login as yourself, the driver will be set to the options you choose.

Below is an example of my .xinitrc:

[jej@ayukawa jej]$ more .xinitrc
xsetwacom set Stylus0 TopX 10
xsetwacom set Stylus0 TopY 67
xsetwacom set Stylus0 BottomX 7170
xsetwacom set Stylus0 BottomY 5778
xsetwacom set Stylus0 TPCButton 1
# run the primary system script
. /etc/X11/xinit/xinitrc

More examples

If you are confused with the usages above, let's see some more confusing examples.

1. Usage of keystroke and modifiers

keystroke and modifiers can be used through buttons, ExpressKeys, wheels, Touch Strips, and Touch Ring. A list of supported modifiers and special keys can be viewed through xsetwacom list mod. Special keys are symbols that go together to represent one XInput key event.

In the following example, Up represents the up arrow key:

[jej@ayukawa jej]$ xsetwacom set cursor button4 "key core Up"   

When you press button4 on your Wacom puck, Xinput will receive an up arrow event.

If you want to send the Up keystroke, the universal escape character \ has to be used:

[jej@ayukawa jej]$ xsetwacom set cursor button4 "key core \Up"   

If you press button4 on your Wacom puck, Xinput will receive an U and a p events, i.e., Up would be displayed on your active console or application.

Sending down arrow event when button5 is pressed:

[jej@ayukawa jej]$ xsetwacom set cursor button5 "key core Down"  

Sending PageUp event when tablet wheel scrolls up:

[jej@ayukawa jej]$ xsetwacom set pad RelWUp "key core pgup"   

Sending PageDown event when tablet wheel scrolls down:

[jej@ayukawa jej]$ xsetwacom set pad RelWDn "key core pgdn"   

The same functions work for parameters AbsWUp, AbsWDn, StripLUp, StripLDn, StripRUp, and StripRDn.

2. Changing debug level while driver is running

xsetwacom supports 2 ways of enabling/disabling debugging information, for individual device and/or for all tools associated with the same tablet, through parameters DebugLevel and CommonDBG. For example,

[jej@ayukawa jej]$ xsetwacom set cursor DebugLevel 10

Turns debugger on to level 10 for device "cursor" only. Other devices will not report information to Xorg.0.log file.

[jej@ayukawa jej]$ xsetwacom set cursor CommonDBG 3

Turns debugger on to level 3 for all devices associated with the same tablet as "cursor" does. But only common debug information will be reported.

3. Configuring TwinView setup while system running

TwinView parameter sets the mapping of TwinView to horizontal/vertical/none. The current TwinView setup can be retrieved by the corresponding get command. For example:

[jej@ayukawa jej]$ xsetwacom -x get cursor TwinView
        Option  "TwinView"      "none"
[jej@ayukawa jej]$ 

Two other parameters, TVResolution0 and TVResolution1, made the change of MetaModes option in TwinView setup possible when system is running. TVResolution0 sets MetaModes option for TwinView Screen 0, while TVResolution1 sets MetaModes option for TwinView Screen 1. However, you need to make sure that the MetaModes you are going to set is the same as the TwinView setup in your xorg.conf for Nvidia Graphic card driver.

4. Changing Suppress and RawSample to filter the raw data

Use of Suppress will reduce the number of raw data we process in the driver. So, unless you know what you are doing, changing Suppress is not recommended. Valid values for Suppress is 0 to 100, where 0 means raw data is used as is. Suppress less than 101 means data will be used only when its change compared to the last processed event is larger than Suppress in points. Default is 2.

RawSample was originally introduced to smooth x/y coordinates to a certain degree. A four-points averaging was tested and convinced to be effective. In 0.7.8, we made RawSample changeable through xsetwacom. However, same as with Suppress, changing RawSample is not recommended. The maximum value can be as large as 20. But the default stays at 4.

Both Suppress and RawSample apply to the devices on the same tablet, that is, it is global to all devices associated with the same tablet.