Huion Inspiroy 2 setup is difficult

[whot]

I'm filing this here, in part to have something to point to and to gather my thoughts. This is not really a bug in libwacom though libwacom's requirements for UNIQ compound the isssue.

OOTB my Huion Inspiroy 2 S (H641P) works as tablet device but with limitations: the pad buttons and the wheel send keyboard shortcuts. The M and L version of the same tablet has three buttons missing.
This can be fixed by switching the tablet into vendor mode by reading (yes, reading) a specific usb string. The DIGImend kernel drivers do that and so does the standalone huion-switcher tool. The return value of that is the firmware ID that libwacom uses in the DeviceMatch lines.

The DIGImend drivers export that firmware ID as the HID_UNIQ sysattr which udev eventually copies into the UNIQ property that libwacom then queries on the event node.

Once switched, the device sends all events through a HID vendor collection¹ DIGImend historically changed/interpreted this collection so events become tablet events. For the Inspiroy 2 and later we decided that this should be done via a udev-hid-bpf eBPF program instead, it's more flexible, easier to develop and test, etc. But eBPF programs cannot yet set HID_UNIQ so huion-switcher is the stopgap solution here.

huion-switcher works around this by getting called for all VID 256c devices and its udev rule copies the HUION_FIRMWARE_ID into the HID_UNIQ and UNIQ property for all devices with that VID.

Which means to get this device to work on plug one needs to:

• install udev-hid-bpf and the corresponding BPF and a udev rule that triggers the load of this on plug²
  • with this the device will work correctly in OOTB or tablet mode (depending on device)
• install huion-switcher and the corresponding udev rule³
  • with this the device will send events via the HID vendor report, and udev sets the UNIQ property
• install libwacom 2.12.1 or later to have all the libwacom bits

Only with all these met will libwacom detect the device correctly.

Eventually the BPF program will be upstreamed into the kernel but there is no way right now to work around the huion-switcher tool requirement, not until HID-BPF has the ability to write the HID_UNIQ value.

Footnotes

1. the existing HID reports got mute. Those that resemble tablets so the device somewhat works OOTB. ↩

2. sudo udev-hid-bpf install --install-exe build/src/bpf/testing/10-Huion__Inspiroy-2-S.bpf.o as per the docs ↩

3. See the huion-switcher README ↩

[whot]

Tracker bug for udev-hid-bpf to be able to take over some things.

[bentiss]

But eBPF programs cannot yet set HID_UNIQ so huion-switcher is the stopgap solution here.

In kernel v6.11, since 33c0fb85b571b0f1bbdbf466e770eebeb29e6f41 you can set the hid->uniq property to the required value and then have HID_UNIQ automatically populated based on that.

It doesn't solve the issue of requiring huion-switcher for fetching the USB string, but at least huion-switcher isn't required to set this property up (i.e. knowing the rest of the stack)