-
Notifications
You must be signed in to change notification settings - Fork 208
Tablet Definition Files
A .tablet file is an ini-style text file that describes a single tablet
model. These files live in the data/ directory of the libwacom source tree
and get installed to /usr/share/libwacom/. Each file contains metadata
like the device name, how to identify it, what features it has, and which
styli it supports.
The best reference is always the existing files in the
data/ directory.
The file data/wacom.example documents every possible key. What follows
here is a practical overview.
A .tablet file has up to four sections: [Device], [Features],
[Buttons], and [Keys]. The [Device] and [Features] sections are
always required. [Buttons] is only needed for tablets with pad buttons.
[Keys] is rare -- it's for devices with special hardware keys.
The file should start with a comment block that identifies the device and links to the sysinfo issue:
# Vendor
# Model Name
# Model Number (if applicable)
#
# sysinfo.abcdef1234.tar.gz
# https://github.com/linuxwacom/wacom-hid-descriptors/issues/NNN
For tablets with buttons, a comment showing the button layout is helpful:
# Button Map:
# (A=1, B=2, C=3, ...)
#
# *-----------------------*
# | |
# B | |
# C | |
# D | TABLET |
# E | |
# A | |
# *-----------------------*
[Device]
Name=Wacom Intuos Pro M
ModelName=PTH-660
DeviceMatch=usb|056a|0357;bluetooth|056a|0360;
Width=9
Height=6
IntegratedIn=
Layout=wacom-intuos-pro-2-m.svg
Styli=@intuos4;@intuos5;@mobilestudio;@propengen2;Name is the device name as announced by the kernel. You can find it by
running libinput record, evtest, evemu-record, or looking through
/proc/bus/input/devices.
ModelName is the manufacturer's model number (e.g. PTH-660, CTL-4100).
Not all manufacturers use model names, leave it blank if the Name already
uniquely identifies the device.
DeviceMatch is how libwacom identifies the device. The format is
bus|vid|pid where bus is one of usb, bluetooth, serial, or i2c,
and vid/pid are 4-digit lowercase hex numbers without the 0x prefix.
Multiple matches are separated by semicolons. A device that works over both
USB and Bluetooth would have two entries:
DeviceMatch=usb|056a|0357;bluetooth|056a|0360;
Some vendors (particularly Huion and Gaomon) reuse the same product ID across different tablet models. For those devices, the kernel device name can be appended as a fourth field to disambiguate:
DeviceMatch=usb|256c|006d|HUION Huion Tablet_H640P Pen;usb|256c|006d|HUION Huion Tablet_H640P Pad
If even the name is shared between models, a UNIQ field (firmware identifier) can be used as a fifth field. See Support for Huion devices for details.
Width and Height are the dimensions of the active drawing area in
inches, as advertised by the manufacturer. These are optional.
IntegratedIn describes how the tablet is physically integrated. Leave it
empty for standalone external tablets. Set it to Display for pen displays
like a Cintiq (external monitors with a digitizer). Set it to
Display;System for tablets built into a laptop screen. Set it to Remote
for accessories like the Wacom ExpressKey Remote. If this key is omitted
entirely (as opposed to set to empty), libwacom will try to determine
integration from kernel properties at runtime.
Layout is the filename of an SVG file in the layouts/ subdirectory that
visually describes the tablet. This is only needed for tablets that have pad
buttons, rings, or strips.
Styli lists which styli are compatible with this tablet. For non-Wacom
devices, this is almost always @generic-with-eraser (if the stylus has an
eraser end) or @generic-no-eraser (if it doesn't). Wacom professional
devices use groups like @intuos4, @propengen2, @propen3, etc.
Individual stylus tool IDs can also be listed by hex value (e.g. 0x802).
See the section on styli below.
PairedIDs is used when the same physical device presents as multiple
independent USB devices with different product IDs, for example when a
Cintiq has separate pen and touch devices. This is a single match string
(same format as DeviceMatch) pointing to the paired device.
Class is deprecated. For new non-Wacom devices, set it to Bamboo for
external tablets or ISDV4 for built-in ones. For Wacom devices, copy the
class from a similar existing device.
[Features]
Stylus=true
Reversible=true
Touch=false
TouchSwitch=false
NumRings=1
NumStrips=0
NumDials=0Stylus is true if the device supports pen input (virtually all tablets
do).
Reversible is true if the tablet is asymmetric and can be turned 180
degrees for left-handed use. This applies to standalone tablets with buttons
on one side. It does not apply to pen displays.
Touch is true if the device has a touch sensor.
TouchSwitch is true if the device has a physical switch to toggle touch on
and off.
NumRings is the number of touch rings (circular touch-sensitive controls),
typically 0, 1, or 2.
NumStrips is the number of touch strips (linear touch-sensitive controls).
NumDials is the number of rotary dials that send relative events (like a
mouse wheel).
Keys not specified in the file default to false or 0.
This section describes the pad buttons on the tablet. Buttons are identified by uppercase letters starting from A.
[Buttons]
Left=A;B;C;D;E;F;G;H;I
Ring=I
RingNumModes=4Left, Right, Top, Bottom list which buttons are on each side of the
tablet.
EvdevCodes specifies the evdev key codes for each button in order A, B, C,
etc. For non-Wacom devices these are typically BTN_0 through BTN_9. If
not specified, libwacom assigns codes based on heuristics.
Ring, Ring2, Strip, Strip2, Dial, Dial2 specify which button is
associated with a touch ring, strip, or dial.
RingNumModes, Ring2NumModes, StripsNumModes, DialNumModes,
Dial2NumModes specify how many modes can be cycled through on each
control.
OLEDs lists buttons that have small OLED displays (only on Intuos4
devices).
Stylus definitions live in .stylus files in the data directory (mainly
wacom.stylus and lenovo.stylus). Each stylus has a tool ID, a name, and
properties like how many buttons it has, what axes it supports (tilt,
pressure, rotation), and whether it has an eraser.
Styli are organized into groups. A group is just a label (like intuos4 or
generic-no-eraser) assigned to each stylus via its Group= field. When a
.tablet file references @generic-no-eraser, libwacom collects every
stylus that belongs to that group.
For most non-Wacom tablets, the device doesn't report a specific stylus tool ID, so you should use one of the generic groups:
-
@generic-with-eraser-- the pen has a separate eraser end -
@generic-no-eraser-- the pen has no eraser
Wacom professional tablets can distinguish between different physical pens
and need specific stylus groups. Look at existing .tablet files for the
same product line to find the right groups.
SVG layouts provide a visual representation of the tablet that GUI applications can use. They also encode the position and size of each button, ring, and strip so applications can overlay configuration UI on the right spots.
SVG elements use a specific naming convention: buttons are named ButtonA,
ButtonB, etc., touch rings are named Ring and Ring2, and so on. The
SVG also contains label positions and leader lines connecting each button to
its label. See the data/layouts/README.md file for the full specification.
If you're creating a new SVG, design it in Inkscape, then run
tools/clean_svg.py to normalize the element IDs and classes:
./tools/clean_svg.py /path/to/tablet.svg "Tablet Model Name"
SVG layout files are only necessary for tablets that have pad buttons.
Here is what a typical non-Wacom tablet file looks like:
# SomeVendor
# TabletPro 10
#
# sysinfo.abcdef1234.tar.gz
# https://github.com/linuxwacom/wacom-hid-descriptors/issues/NNN
#
# *-------------------------------*
# A | |
# B | |
# C | |
# | TABLET |
# D | |
# E | |
# F | |
# *-------------------------------*
[Device]
Name=SomeVendor TabletPro 10
ModelName=
DeviceMatch=usb|1234|5678
Width=10
Height=6
IntegratedIn=
Layout=somevendor-tabletpro-10.svg
Styli=@generic-no-eraser;
[Features]
Stylus=true
Reversible=true
Touch=false
[Buttons]
Left=A;B;C;D;E;F
EvdevCodes=BTN_0;BTN_1;BTN_2;BTN_3;BTN_4;BTN_5