Linux Wacom Project HOWTO
9.0 - Command Line Configuration Interface (xsetwacom)
Navigation:
MAIN UP PREV NEXT INDEX ALL
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.
Navigation:
MAIN UP PREV NEXT INDEX ALL
