Support for Huion devices

Devices from Huion and Gaomon are supported but with a few conditions outlined on this page. Note that Gaomon tablets are just re-branded Huion devices, they both use the vendor ID 0x256c so for the remainder of the page we will only refer to Huion.

Firmware mode vs. vendor mode

Most Huion devices export three HID devices:

• the first node is a "proprietary" vendor device
• the second node is a tablet pen device
• the third node is a keyboard device

In the default firmware mode the vendor HID device will not send any events, pen events will be sent through the pen device and the pad buttons will emulate keyboard events through the keyboard node (e.g. Ctrl+C or simply Space). The hid-recorder tool can be used to show the various events.

By reading a "hidden" USB string descriptor we can switch the device into vendor mode. Doing so sends all events (pen and buttons) through the vendor device. Importantly, the pad buttons are sent as normal buttons instead of keyboard shortcuts. Once that is done we only need to teach the kernel how the vendor protocol works - this is done either with the hid-uclogic driver of udev-hid-bpf, see below.

Identifying Huion devices

libwacom uses the DeviceMatch line in the corresponding .tablet file to distinguish devices. A match typically looks like this:

# A usb device with vendor id 056a and product id 0303
DeviceMatch=usb|056a|0303

This match does not work on most Huion devices because Huion re-uses product IDs between different devices. libwacom also supports a name string match that can be appended to the DeviceMatch:

DeviceMatch=usb|256c|006e|HUION 420 Pen;usb|256c|006e|HUION 420 Pad

This works for some devices, e.g. the Huion 420. Note that the kernel creates multiple suffixed devices for each physical device (Pen, Pad and Finger if touch is supported) and all must be added to the DeviceMatch line.

However, even the name match does not work for devices where both product ID and device name are identical between different devices. Those devices we can only distinguish based on the UNIQ field contains the device's firmware version prefix. For eample the Gaomon S620 does this:

#                   | PID|--------- name ---------|-- UNIQ --|
DeviceMatch=usb|256c|006d|GAOMON Gaomon Tablet Pen|OEM02_T18e;usb|256c|006d|GAOMON Gaomon Tablet Pad|OEM02_T18e;

Uniq matching was added in libwacom 2.12 (June 2024). To check the UNIQ field on your device run this command against your device's event node:

$ udevadm info /sys/class/input/event20 | grep UNIQ
E: UNIQ=OEM02_T18e_20191130

Note that the UNIQ value may have a date suffixed - libwacom's DeviceMatch only needs to contain the date-less prefix.

Kernel hid-uclogic support for UNIQ

The hid-uclogic driver switches the tablet into vendor mode and provides the kernel with a HID report descriptor on how to interpret the vendor packages. Support for setting the UNIQ field is available as of kernel v6.10 (kernel commit a721b1423b049323d0987700ff125b46208046f9). This however is available in the hid-uclogic driver only. For devices that are handled by the hid-uclogic driver this field will be set and libwacom will detect the device automatically. To check if you device is handled by this driver run:

$ udevadm info /sys/class/input/event20/device/device | grep DRIVER
DRIVER=hid_uclogic

Replace the event node number (event20) to match one of the event nodes for your device.

Note that using hid-uclogic for Huion devices has been deprecated in favour of using udev-hid-bpf, see below.

udev-hid-bpf (with huion-switcher)

udev-hid-bpf is a new (v6.3+) approach on implementing tablet drivers for Huion devices. It uses eBPF programs to replace the HID report descriptors so the kernel knows how to interpret the vendor packages. Unlike the hid-uclogic kernel driver such a eBPF program can also change the default firmware mode packages and thus change the emulated keyboard events back into normal tablet buttons. It can work in both firmware mode and vendor mode.

Currently an eBPF program loaded via udev-hid-bpf requires some other tool to switch into vendor mode - this tool is huion-switcher. However, as external tool huion-switcher cannot set the UNIQ field on the device directly, it must be triggered by a udev rule.

We recommend installing huion-switcher and udev-hid-bpf which enables this sequence on device plug:

• udev calls huion-switcher which reads and prints the firmware string and switches to vendor mode
• udev captures the firmware string and copies it into the UNIQ udev property
• udev triggers udev-hid-bpf
• udev-hid-bpf loads the corresponding eBPF file for this device which replaces the HID report descriptor for the device
• the default hid-generic kernel driver can now interpret the events as they are coming from the device

At some later point when libwacom is invoked it can also read the UNIQ udev property and thus has access to the firmware matching in the .tablet file.