Adding a new device to libwacom involves two things: gathering the hardware information (the "sysinfo") and creating a .tablet definition file. The .tablet file is what libwacom actually reads to learn about your device. The sysinfo is filed separately so that developers can debug the device without having the physical hardware.

Before you start, check if your device is already supported.

Note that adding a .tablet file to libwacom does not make your tablet work. If pen input or buttons don't function at all, see Troubleshooting. The .tablet file only provides metadata so that desktop environments can properly configure an already working device. That said, since the data is static, you can add a .tablet file before the device is even supported by the kernel -- it just won't have any effect until the driver side is sorted out.

The wacom-hid-descriptors repository has a script that collects hardware information about your tablet. Run it with the tablet plugged in:

$ bash <(curl -s https://raw.githubusercontent.com/linuxwacom/wacom-hid-descriptors/master/scripts/sysinfo.sh)

This produces a tarball in /tmp/ containing device descriptors and other diagnostic data. The script also attempts to auto-generate a .tablet file for your device -- if it succeeds, that file will be inside the tarball.

File the resulting tarball as a new issue in the wacom-hid-descriptors repository. Having this on file lets developers examine your device even if they don't own one, which is important for debugging and review.

If the sysinfo script auto-generated a .tablet file, start with that. Otherwise, find an existing .tablet file for a similar device in the data/ directory and copy it as a starting point. For example, if you have a Huion tablet with 6 buttons, look at huion-h640p.tablet as a template.

The file naming convention is vendor-modelname.tablet in lowercase, e.g. huion-inspiroy-2-m.tablet or xp-pen-deco01-v2.tablet. For Wacom devices the vendor prefix is usually just wacom-.

Every .tablet file must include a comment at the top referencing the sysinfo tarball and the corresponding issue:

# Vendor
# Model Name
#
# sysinfo.abcdef1234.tar.gz
# https://github.com/linuxwacom/wacom-hid-descriptors/issues/NNN

See Tablet Definition Files for a full description of the file format.

Copy the .tablet file into /etc/libwacom/. If this directory doesn't exist yet, create it. Files in /etc/libwacom/ take precedence over the ones shipped by your distribution in /usr/share/libwacom/, so you can test without interfering with the installed files. If your tablet has buttons and you've created an SVG layout file, copy that to /etc/libwacom/layouts/.

$ sudo mkdir -p /etc/libwacom/layouts
$ sudo cp my-tablet.tablet /etc/libwacom/
$ sudo cp my-tablet-layout.svg /etc/libwacom/layouts/     # if applicable

Then run libwacom-update-db to regenerate the udev hardware database so the device gets properly tagged:

$ libwacom-update-db /etc/libwacom

This will use sudo internally to copy the generated hwdb file and update the udev database. After it finishes, unplug and replug your tablet, then check if your device shows up:

$ libwacom-list-local-devices

If the device appears with the correct information, the .tablet file is working.

You can also use ~/.config/libwacom/ instead of /etc/libwacom/ for per-user testing -- this takes even higher precedence.

Once your .tablet file is tested and working, submit it upstream:

# Fork the repository on GitHub, then:
$ git clone git@github.com:<your-username>/libwacom.git
$ cd libwacom/
$ git switch --create add-my-tablet

# Copy your tablet file and layout into the source tree
$ cp /etc/libwacom/my-tablet.tablet data/
$ cp /etc/libwacom/layouts/my-layout.svg data/layouts/   # if applicable
$ git add data/

# Build and run the tests to catch any errors
$ meson setup builddir
$ meson compile -C builddir
$ meson test -C builddir

# Commit and push
$ git commit -m "Add support for My Tablet Name"
$ git push origin add-my-tablet

Then open a pull request on GitHub. The CI will run the test suite against your changes and flag any issues with the .tablet file format.

Sometimes the same tablet model ships with a different USB product ID (a hardware revision, for instance). If a .tablet file already exists for your device but libwacom-list-local-devices doesn't find it, you probably just need to add your device's match string to the existing file's DeviceMatch line. Find your device's bus, vendor ID, and product ID using lsusb or /proc/bus/input/devices, then append a new semicolon-separated entry to the DeviceMatch line.