The Linux Wacom Project
SourceForge.net Logo

Linux Wacom Project HOWTO

9.0 - Command Line Configuration Interface (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 man xsetwacom.

Note: The device identifiers (dev_name) are case sensitive. You should use the dev_name exactly the same as xsetwacom list shows. The examples below assume that Stylus, cursor, and pad are used.

[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"
Note: keystrokes and modifiers are only supported for Xorg 6.8 or later.

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|xinerama|vertical 
                                    |horizontal|leftof
		                    |aboveof                       sets the mapping to TwinView. Tablet mappings applied after this command will be based on the new tablet orientation.
   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 with clickforce scale
   Threshold               integer                        sets tip/eraser pressure threshold directly to the pressure default is (2048 / 75)
   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
   Touch                       on|off                         turns on/off Touch events (default is enable/on for tablets with touch)
   Gesture                   on|off                          turns on/off Touch Gesture (default is enable/on for tablets with two finger support).
   ZoomDistance         integer                        minimum distance required before starting a zoom gesture (default is 50)
   ScrollDistance     integer                        minimum finger motion distance required for starting a scroll gesture (default is 30 for Tablet PC and 20 for the others)
   TapTime                  integer (1 - 500)     maximum time between taps required for a right click gesture (default is 250 ms)
   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 all displays which include individual screens plus the whole desktop for the selected tool if it is not a pad. When the tool is a pad, the function applies to all tools that are asssociated with the tablet
	          SCREENTOGGLE: Toggle cursor movement among all screens for the selected tool if it is not a pad. When the tool is a pad, the function applies to all tools that are 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 Stylus TopX 10
xsetwacom set Stylus TopY 67
xsetwacom set Stylus BottomX 7170
xsetwacom set Stylus BottomY 5778
xsetwacom set Stylus TPCButton 1
# run the primary system script
. /etc/X11/xinit/xinitrc

To see what's under your home directory, use ls -al ~.

If your system doesn't execute .xinitrc at login, you can add those xsetwacom commands into the startup script (.bashrc, .cshrc, .profile, etc.) that your system launches, for example, you should use .Xsession instead of .xinitrc on Debian.

It has been reported that xsetwacom can not run on some older systems due to a XFree86 interface error. A generic solution to this issue is directly adding your configuration options to the /etc/X11/XF86Config file. Please refer to Configuring X11 for details.

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]$ 
which means device cursor was not set to TwinView display.

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.






Copyright (C) 2002-2011 - LinuxWacom -Last updated July 23, 2012
This website and its contents are licensed under the GNU GENERAL PUBLIC LICENSE.