Adding a new device

There are a number of steps involved in adding a new device and it all comes down to two things:

• an issue with the sysinfo must be filed in the wacom-hid-descriptors repository
• a .tablet file must be added to libwacom (via a pull request)

Note that libwacom does not affect whether the device works and .tablet files contain static information about the device. Thus you can add a .tablet file to libwacom before the device is even supported. However, doing so won't make your tablet work, see Troubleshooting.

But before you do anything: check if your device is supported.

What is a .tablet file?

The tablet definition file helps applications configure your device because the application can access metadata about your device in libwacom. Note that the libwacom data files do not make the stylus work, this is merely about adding extra information for better configuration. See the wacom.example file for explanations of the requested data and its format and see the existing files.

If your device does not show up, the first step is gathering sysinfo:

Gathering sysinfo

It will be helpful to have your device in the wacom-hid-descriptors repository before adding data files for it to libwacom. This is so we are able to debug the tablet even without having the device itself.

The first step to a new tablet data file is to gather information about the device with the sysinfo.sh script.

$ bash <(curl -s https://raw.githubusercontent.com/linuxwacom/wacom-hid-descriptors/master/scripts/sysinfo.sh)
Gathering system and tablet information. This may take a few seconds.
  * General host information...
  * Kernel driver information...
  * Kernel device information...
     - /sys/devices/LNXSYSTM:00/LNXSYBUS:00/MSFT0101:00...
     - /sys/devices/pci0000:00/0000:00:14.0/usb1/1-4/1-4:1.0/0003:045E:07A5.0001...
     - /sys/devices/pci0000:00/0000:00:14.0/usb1/1-4/1-4:1.1/0003:045E:07A5.0002...
     - /sys/devices/pci0000:00/0000:00:14.0/usb1/1-4/1-4:1.2/0003:045E:07A5.0003...
     - /sys/devices/platform/MSFT0101:00...
     - udev...
  * Unbinding devices...
  * Rebinding devices...
  * Userspace driver information...
  * Userspace device information...
  * Device display information...
  * System logs...
  * System config files...
  * Desktop configuration data...
  * Removing identifying information...
  * Tarball generation...
Finished. Data available in '/tmp/sysinfo.nFg5aWRPW1.tar.gz'

As shown above, the script collects data about the tablet and attempts to generate a .tablet file. The resulting tarball should be attached to a new issue in the wacom-hid-descriptors repository. Please see the README in that repository for more details.

Modifying and testing the .tablet file

The .tablet file must contain the name of and a link to the sysinfo tarball uploaded to that repository in the form

# SomeCorp
# PadPad1234-Pro
#
# sysinfo.nFg5aWRPW1.tar.gz
# https://github.com/linuxwacom/wacom-hid-descriptors/issues/1234

If the script fails to auto-generate a .tablet file, please check the existing data files for existing files that may be similar to your device. In many cases, it's possible to take a .tablet file from a previous version of the device and copy+modify it for your device. See the example below for guidance on the various supported keys.

Copy the .tablet file into /etc/libwacom and run the libwacom-update-db tool. (If this directory does not exist yet, you can create it.) It's recommended to use this directory over /usr/share/libwacom to prevent messing with the existing .tablet files installed by your distribution. Make sure to copy the tablet's .svg layout file to /etc/libwacom/layouts.

$ cp my-tablet-file-from-upstream.tablet /etc/libwacom/
$ cp my-tablet-file-layout.svg /etc/libwacom/layouts/
$ libwacom-update-db /etc/libwacom

The tool will take care of updating udev, the hwdb, etc. Then check if your device is supported. If the tablet file is correct your device should now show up both in the device list and (if plugged in and supported by the kernel) as locally supported device.

Submitting the new .tablet file to libwacom

Copy the file to into libwacom's data/ folder with the correct name (see the existing data files). Then git add and file a pull request. This is usually a sequence of:

• fork the libwacom repository by clicking on the Fork button on the main page
• perform the required git commands to submit a pull request (this is not a tutorial, merely an outline of the steps required)

# fill in your username accordingly
$ git clone git@github.com:<username>/libwacom.git
$ cd libwacom/

# Create a new branch 
$ git switch --create <modelname>-support
$ cp /path/to/foo.tablet data/<vendor>-<modelname>.tablet
$ git add data/<vendor>-<modelname>.tablet

# Now compile and test to make sure the file is correct
$ meson setup builddir/
$ meson compile -C builddir
$ meson test -C builddir

# Push and file the pull request
$ git push origin 
# Now click on the link printed to create a new merge request

This files a new pull request which we can review and merge.