1WACOM(4)                   Kernel Interfaces Manual                   WACOM(4)
2
3
4

NAME

6       wacom - Wacom input driver
7

SYNOPSIS

9       Section "InputDevice"
10         Identifier "idevname"
11         Driver "wacom"
12         Option "Device"   "devpath"
13         ...
14       EndSection
15

DESCRIPTION

17       wacom is an X input driver for Wacom devices.
18
19       The wacom driver functions as a pointer input device.
20

SUPPORTED HARDWARE

22       This driver supports the Wacom IV and Wacom V protocols. Serial tablets
23       only need this driver.  USB tablet support is available on  some  Linux
24       platforms and requires the wacom kernel driver being loaded before this
25       driver starts.
26
27       Please check https://github.com/linuxwacom for latest updates of  Wacom
28       X and kernel drivers.
29

DRIVER-INTERNAL DEVICE HOTPLUGGING

31       When  input device hotplugging in the X server is enabled and no Input‐
32       Device section exists for a compatible tablet device and an  InputClass
33       section  (see  xorg.conf.d(5x)) assigns this driver for the device, the
34       wacom driver creates multiple X devices for each a physical device, one
35       X  device for each available tool. The list of tools is hardware-depen‐
36       dent. See Option Type as outlined in the CONFIGURATION DETAILS section.
37
38       These tool-specific devices are referred to as parent device and depen‐
39       dent  device.  The parent device is the one presented by the system and
40       the one that causes the X server to load the wacom driver. This  parent
41       device then causes the automatic addition of several dependent devices.
42       If the parent device is unplugged or otherwise removed,  the  dependent
43       devices will be automatically removed as well.
44
45       Dependent  devices  may be assigned tool-specific options through addi‐
46       tional InputClass sections. We recommend that a MatchDriver wacom  line
47       is used in these sections in addition to the user-specific pattern.
48
49       Match  directives  are applied by the X server before the driver is se‐
50       lected.  The type name of the parent device is appended by the  driver.
51       It  is  not  possible  to use a MatchProduct directive to match against
52       this appended type name.
53

CONFIGURATION DETAILS

55       Please refer to xorg.conf(5x) or xorg.conf.d(5x) for general configura‐
56       tion  details  and for options that can be used with all input drivers.
57       This section only covers configuration details specific to this driver.
58
59       Multiple instances of the Wacom devices can cohabit. Each  device  sup‐
60       ports the following entries:
61
62               Option "Type" "stylus"|"eraser"|"cursor"|"pad"|"touch"
63                   sets the type of tool the device represents. This option is
64                   mandatory.  The core options, such as  "SendCoreEvents"  or
65                   "AlwaysCore",  are unnecessary in Gimp if you don't need to
66                   move system cursor outside of Gimp drawing area.  "pad"  is
67                   for Intuos 3 or Cintiq 21UX tablet ExpressKeys/menu strips,
68                   and Graphire 4 or  Bamboo  tablet  buttons,  wheel,  and/or
69                   ring.   It is required  for Intuos3,  CintiqV5, Graphire 4,
70                   and Bamboo if you want to use keystroke features.  "pad" is
71                   reported as a second tool in the driver. "touch" is for the
72                   tablet with touch support.  Right now only a few Tablet PCs
73                   have this feature.
74
75               Option "Device" "path"
76                   sets  the  path to the special file which represents serial
77                   line where the tablet is plugged.  You have to  specify  it
78                   for each subsection with the same value if you want to have
79                   multiple devices with the  same  tablet.   This  option  is
80                   mandatory.
81
82               Option "Suppress" "number"
83                   sets the position increment under which not to transmit co‐
84                   ordinates.  This entry must be specified only in the  first
85                   Wacom  subsection  if  you  have  multiple  devices for one
86                   tablet. If you don't specify this entry, the default value,
87                   which is 2, will be used. To disable suppression, the entry
88                   should be specified as 0.  When suppress  is  defined,   an
89                   event  will be sent only when at least one of the following
90                   conditions is met:
91
92                           the change between the current X coordinate and the
93                   previous one is greater than suppress;
94
95                           the change between the current Y coordinate and the
96                   previous one is greater than suppress;
97
98                           the change between the  current  pressure  and  the
99                   previous one is greater than suppress;
100
101                           the  change between the  current degree of rotation
102                   and the previous one of the transducer is greater than sup‐
103                   press;
104
105                           the change between the current absolute wheel value
106                   and the previous one is equal to or greater than suppress;
107
108                           the change between the current tilt value  and  the
109                   previous  one is equal to or greater than suppress (if tilt
110                   is supported);
111
112                           relative wheel value has changed;
113
114                           button value has changed;
115
116                           proximity has changed.
117
118               Option "Mode" "Relative"|"Absolute"
119                   sets the mode of the device.  The default value for stylus,
120                   pad  and  eraser is Absolute; cursor is Relative; touch de‐
121                   faults to Relative for tablets with touch pads and Absolute
122                   for touch screens.
123
124               Option "TopX" "number"
125                   X coordinate of the top corner of the active zone.  Default
126                   to 0.
127
128               Option "TopY" "number"
129                   Y coordinate of the top corner of the active zone.  Default
130                   to 0.
131
132               Option "BottomX" "number"
133                   X  coordinate of the bottom corner of the active zone.  De‐
134                   fault to width of the tablet.
135
136               Option "BottomY" "number"
137                   Y coordinate of the bottom corner of the active zone.   De‐
138                   fault to height of the tablet.
139
140               Option "ButtonsOnly" "on"|"off"
141                   disables the device's motion events.  Default to off.
142
143               Option "ButtonM" "AC"
144                   reports  an action AC when button M is pressed,  where M is
145                   one of the device supported  button numbers,  it can  be  1
146                   to  32.  Wacom uses a driver-internal button mapping, where
147                   any physical button appears to the X server as  the  button
148                   specified  by  the  ButtonM mapping. Hence, if two physical
149                   buttons have the same  ButtonM  mapping,  the  server  will
150                   think  they  are the same physical button.  The default ac‐
151                   tion reported to the X server is mouse button M click.  Be‐
152                   cause  X  uses buttons 4, 5, 6, and 7 as the four scrolling
153                   directions, physical buttons 4 and higher are mapped  to  8
154                   and  higher  by default.  Only simple button presses can be
155                   configured here; for  more  complex  actions,  use  xsetwa‐
156                   com(1).   To  ignore  the button click, i.e., to not report
157                   any button click event to the X server,  use "0" or "button
158                   0".
159
160               Option "TPCButton" "on"|"off"
161                   enables  the  stylus  buttons  as Tablet PC buttons. If en‐
162                   abled, the stylus reports button events only when  its  tip
163                   is pressed. If any button is down, pressing the tip reports
164                   a button event for the button. Otherwise if  no  button  is
165                   down, the tip reports as usual.  Default to "on" for Tablet
166                   PCs; "off" for all other models. Only available on the sty‐
167                   lus tool.
168
169               Option "Touch" "on"|"off"
170                   enables  touch events for touch devices,  i.e., system cur‐
171                   sor moves when user touches the tablet.   Default  to  "on"
172                   for devices that support touch; "off" for all other models.
173
174               Option "Rotate" "CW"|"CCW"|"HALF"|"NONE"
175                   rotates  the  tablet  orientation counterclockwise (CCW) or
176                   clockwise (CW) or 180 degrees (HALF).  If you have specific
177                   tablet  mappings,  i.e.  TopX/Y  or BottomX/Y were set, the
178                   mapping will be applied before rotation. Rotation  must  be
179                   applied to the parent device (usually the stylus), rotation
180                   settings on in-driver hotplugged devices (see DRIVER-INTER‐
181                   NAL  DEVICE  HOTPLUGGING  ) will be ignored. The default is
182                   "NONE".
183
184               Option "PressCurve" "x1,y1,x2,y2"
185                   sets pressure curve by control points x1, y1, x2,  and  y2.
186                   Their  values  are in range from 0..100. The pressure curve
187                   is interpreted as Bezier curve with 4 control  points,  the
188                   first and the last control point being fixed on the coordi‐
189                   nates 0/0 and 100/100,  respectively.  The  middle  control
190                   points  are  adjustible by this setting and thus define the
191                   shape of the curve.  The input for linear  curve  (default)
192                   is  "0,0,100,100";  slightly depressed curve (firmer) might
193                   be "5,0,100,95"; slightly raised curve  (softer)  might  be
194                   "0,5,95,100".  The pressure curve is only applicable to de‐
195                   vices of type stylus or eraser, other devices do not  honor
196                   this setting.
197
198               Option "Pressure2K" "bool"
199                   reduces  the  pressure  range to the range of 0 to 2048 for
200                   backwards compatibility with applications  that  have  this
201                   range hardcoded.  See section BUGS.  This option should not
202                   be used unless the user runs one or more applications  that
203                   rely on a hardcoded pressure range.
204
205               Option "DebugLevel" "number"
206                   sets  the  level  of  debugging info for tool-specific mes‐
207                   sages.  There are 12 levels, specified by the integers  be‐
208                   tween  1 and 12.  All debug messages with a level less than
209                   or equal to the "number" will be logged into the  Xorg  log
210                   file. This option is only available if the driver was built
211                   with debugging support.
212
213               Option "CommonDBG" "number"
214                   sets the level of debugging info for common (i.e. not tool-
215                   specific)  code  paths  on the tablet. There are 12 levels,
216                   specified by the integers between 1 and 12. All debug  mes‐
217                   sages  with a level less than or equal to the "number" will
218                   be logged into the Xorg  log  file.  This  option  is  only
219                   available if the driver was built with debugging support.
220
221               Option "GrabDevice" "bool"
222                   sets whether the underlying event device will be grabbed by
223                   the driver to prevent the data  from  leaking  to  /dev/in‐
224                   put/mice.  When  enabled, while the X server is running, no
225                   other programs will be able to read the event stream.   De‐
226                   fault: "false".
227
228               Option "CursorProx" "number"
229                   sets  the  distance  at which a relative tool is treated as
230                   being out of proximity.  Beyond this  distance  the  cursor
231                   will  stop responding to tool motion. The default value for
232                   pucks is 10 (Intuos Pro) or 42 (Intuos/Bamboo). The default
233                   value for pens is 30.
234
235               Option "RawSample" "number"
236                   Set   the  sample  window  size (a sliding average sampling
237                   window) for incoming input tool raw data points.   Default:
238                   4, range of 1 to 20.
239
240               Option "Serial" "number"
241                   sets the serial number associated with the physical device.
242                   This allows to have multiple devices of the same type (i.e.
243                   multiple  pens).  This  option is only available on wacom V
244                   devices (Intuos series and Cintiq 21U).  To see  which  se‐
245                   rial  number belongs to a device, you need to run the util‐
246                   ity program, xsetwacom, which comes with  linuxwacom  pack‐
247                   age.
248
249               Option "ToolSerials" "number[,type[,label]][;...]"
250                   sets  the  list  of serial numbered devices that need to be
251                   hotplugged for a physical device. The 'type' option may  be
252                   any  of "pen", "airbrush", "artpen", or "cursor".  This op‐
253                   tion is only available on wacom V devices which are capable
254                   of  reporting a serial number. To see if a connected device
255                   is supported, or to identify which serial number belongs to
256                   a  device,  you need to run the utility program, xsetwacom,
257                   that comes with this driver. In layman's terms, this option
258                   will  add additional X devices for this specific tool's tip
259                   (and eraser, if applicable).  This is useful  for  programs
260                   like  gimp (which remembers tools based on the X device) to
261                   recall additional  drawing  tool  selections  for  an  air‐
262                   brush+eraser, art pen, extra pen, etc.
263
264               Option "Threshold" "number"
265                   sets  the  pressure  threshold  used to generate a button 1
266                   events of stylus.  The threshold applies to the  normalised
267                   pressure range of [0..2048].  The default is 27.
268
269               Option "Gesture" "bool"
270                   Enable or disable multi-finger in-driver gesture support on
271                   the device. Default: off unless the tablet supports  multi-
272                   touch.  Note that disabling this option may allow the desk‐
273                   top environment to detect multi-finger gestures instead.
274
275               Option "ZoomDistance" "number"
276                   If Option "Gesture" is enabled, this option  specifies  the
277                   minimum  movement  distance before a zoom gesture is recog‐
278                   nized.
279
280               Option "ScrollDistance" "number"
281                   If Option "Gesture" is enabled, this option  specifies  the
282                   minimum movement distance before a scroll gesture is recog‐
283                   nized.
284
285               Option "TapTime" "number"
286                   If Option "Gesture" is enabled, this option determines  the
287                   maximum  time  of  a touch event to be recognized as tap. A
288                   press and release event shorter than TapTime generates but‐
289                   ton  press  and release events. Presses longer than TapTime
290                   do not generate button events, only motion events.
291
292               Option "PressureRecalibration" "bool"
293                   Allows to disable pressure  recalibration.  Default:  true.
294                   If  the initial pressure of a device is != 0 the driver re‐
295                   calibrates the pressure range. This is to account for  worn
296                   out  devices.   The downside is that when the user hits the
297                   tablet very hard the initial pressure reading  may  be  un‐
298                   equal to zero even for a perfectly good pen. If the consec‐
299                   utive pressure readings are not  higher  than  the  initial
300                   pressure  by a threshold no button event will be generated.
301                   This option allows to disable the recalibration.
302
303               Option "PanScrollThreshold" "number"
304                   Specifies the distance the pen must move (in tablet  units)
305                   before a scroll event is generated when using the "pan" ac‐
306                   tion. Smaller values will require less distance and be more
307                   sensitive.  Larger values will require more distance and be
308                   less sensitive.  Default: 1300 or 2600 depending on  tablet
309                   resolution (corresponds to 13 mm of distance).
310

TOUCH GESTURES

312   Single finger (1FG)
313       Left click: tap, actual click happens after TapTime period elapses.
314
315       Left  click  drag: tap to select, quickly (within TapTime period) touch
316       selection again.  Then drag.  Available on  touchpads,  e.g.  BambooPT,
317       not touchscreens.
318
319   Two finger (2FG)
320       Right click: one finger down + tap second finger
321
322       Vertical  scroll:  two fingers side by side (in any orientation) moving
323       vertically with constant separation initiates a  vertical  scroll.   By
324       driver  default  a gesture up results in a scroll down event (the docu‐
325       ment moves up) and a gesture down results in a scroll up event  (moving
326       the document down).
327
328       Horizontal scroll: two fingers side by side held at a constant distance
329       moving horizontally initiates a horizontal scroll.  A  gesture  to  the
330       left  results  in  a scroll right event (the document moves left) and a
331       gesture right results in a  scroll  left  event  (moving  the  document
332       right).
333
334       Zoom in: two separated fingers side by side, bring together i.e. pinch.
335
336       Zoom  out: two fingers side by side, spread.  Not all applications sup‐
337       port zoom.
338

BUGS

340   Pressure range increase leads to unexpected behavior
341       In version 0.34, the driver's pressure range increased from 2048  steps
342       to 65536 steps. The pressure axis range is advertised through the X In‐
343       put Protocol but some applications have  the  previous  pressure  range
344       hardcoded  and cannot handle pressure values above 2048. This is an ap‐
345       plication bug but for backwards-compatibility with  such  applications,
346       this  driver provides the Pressure2K option to reduce the range to 2048
347       steps. Note that this setting applies to the device. Once applied,  all
348       applications will see the reduced pressure range. It is not possible to
349       provide this setting on a per-application basis.
350

SEE ALSO

352       Xorg(1), xorg.conf(5), xorg.conf.d(5), X(7)
353
354       More information is available at https://github.com/linuxwacom/xf86-in
355       put-wacom
356

AUTHORS

358       Peter   Hutterer   <peter.hutterer@who-t.net>,  Ping  Cheng  <pingc@wa‐
359       com.com>, Frederic Lepied <lepied@xfree86.org>, John E. Joganic <jej@j-
360       arkadia.com>, Magnus Vigerlöf <Magnus.Vigerlof@ipbo.se>
361
362
363
364X Version 11                xf86-input-wacom 1.0.0                    WACOM(4)
Impressum