wacom-hid-descriptors

This is a repository of system and sensor data gathered from numerous tablet PCs. It is used by the linuxwacom driver developers to ensure continued device compatibility and as a ready source of basic information when support requests are received.

Contributing

We rely on the contributions of a wide cross-section of tablet PC users to keep this repository up-to-date as manufacturers release new models. If we don't have information for your specific model of tablet PC, we would welcome its addition. All you need to do is the following:

Run the sysinfo.sh script contained in the "scripts" directory.
File an issue and attach the tarball generated by the script.

Maintainers

Maintainers of this repository can use the scripts/git-update.sh tool to extract and auto-generate some descriptive information for each tarball they recieve. This ensures a somewhat-consistent directory structure and metadata representation. In particular, the script creates a README which contains some rough information based on the sysinfo contents and maintainer feedback. The script will also generate a libwacom tablet definition if possible (currently only tablet PCs with Wacom sensors are supported).

The following is an example of how the script is used. We provide the script with a sysinfo file and a link to the comment that it was uploaded in. The script then tries to guess the OEM and product of the tablet PC. As you can see, the guess in this case had a problem: the "HP HP" string is problematic. To correct this, we respond to the question with "n" and then re-run the script with the OEM and product manually specified. Afterwards, the script validates the URL, extracts the archive, and attempts to auto-generate a libwacom tablet definition.

$ cd scripts

$ ./git-update.sh sysinfo.h8eClGGagq.tar.gz \
  --url="https://github.com/linuxwacom/wacom-hid-descriptors/issues/154#issue-892789312"
Found: HP HP EliteBook x360 1030 G3
Is this correct? (Y/N) n
Please specify OEM and/or product with the --oem=<name> and --product=<name> arguments.

$ ./git-update.sh sysinfo.h8eClGGagq.tar.gz \
  --url="https://github.com/linuxwacom/wacom-hid-descriptors/issues/154#issue-892789312" \
  --oem=HP --product="EliteBook x360 1030 G3"
Found: HP EliteBook x360 1030 G3
Is this correct? (Y/N) y
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  137k    0  137k    0     0   167k      0 --:--:-- --:--:-- --:--:--  167k
Attempting to parse HID data and create libwacom tablet definition...

The output is a new directory with the name of the OEM and product which contains a README file and the extracted sysinfo archive. If a tablet definition was created, it will be found inside the sysinfo subdirectory. The README can be filled in with relevant information such as if the sensor uses EMR or AES technology what the VID:PID and ACPI IDs are, etc. -- see other recently-committed READMEs for ideas. The tablet definition, if created, can be used to create a new pull request for the libwacom repository.

When adding the directory to the repository you may find that an identically-named directory already exists. This can occur if we get sysinfo archives for several variants of a system. To merge the directories simply move the sysinfo subdirectory (it will have a unique name that won't conflict) and then manually merge the README files so that metadata for both sysinfo files can be read.

Commits to the repository should include a link to the issue which contains the sysinfo script. We recommend adding a single line to the end of the commit message which says Link: <URL>. Commits / pull requests for the libwacom repository should likewise include the same Link: <URL> line to make tracing the origin of the tablet definition easier.

libwacom Tablet Definitions

The scripts/git-update.sh script will attempt to create a libwacom data file if possible. If, however, it is not able to auto-generate such a file you may need to manually create one in order to have the sensor be recognized by the control panel. Please see the libwacom documentation for information on how to create a tablet definition file by hand. Many of the fields (e.g. Name, Width, Height) are easy to determine manually. The DeviceMatch field will simply be the the bus:vid:pid, which can be found by determining which device in the sysinfo archive corresponds to the sensor. Note that libwacom uses human-readable bus names (e.g. usb or i2c) while the information from sysinfo will be numeric (e.g. 0003 or 0018 respectively).