The Linux Wacom Project
|Main | News | FAQ | Downloads | Help | Development | TOC | All||May 30, 2015|
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.
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:
which means device cursor was not set to TwinView display.[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.