blog.nek0.eu/site/posts/2021-06-27-Hacking-my-XP-Pen-drawing-tablets.md

---
title: Hacking my XP-Pen drawing tablets
author: nek0
tags:
- hardware
- hacking
- drawing
description: Enabling functions on my XP-Pen tablets without proprietary driver
---

Hi there,

Long time no see. I am currently quite busy finishing my apprenticeship so my
free time suffers a bit, but my goal is now in reach. Only my oral exam is left
to pass and then I will be done.

So today I want to write about some hardware issues I had with my drawing
tablets and which I solved thanks to
[this blog post by David Revoy](https://www.davidrevoy.com/article842/review-of-the-xp-pen-artist-24-pro-on-linux).

I have been drawing digitally a lot in my free time and thus own at least one
drawing tablet. I stuck with the brand "XP-Pen" as they seem to have a fairly
good quality for a reasonable price. Also they seem to support linux (at least
in their own strange way). They do ship a driver for their tablets, which is
proprietary and needs to run in the background all the time and seems not to
be able to remember its settings (at least not on my [NixOS][nixos]).

So up until recently I was bound to work with what worked out of the box with
Deco Pro M, which was most of the functionality it provided, even the pen tilt
was recognized out of the box. The only things I was missing was making a
right-click with my pen, assigning the hotkeys on my tablet and mapping the
tablet to a specific Display on a multi monitor setup.

This is where David's blog post enters the stage, where he provides a detailed
guide on how to set up a XP-Pen Artist 24 drawing monitor in linux without
using the proprietary driver. I was able to extrapolate from that and adjust my
`/etc/nixos/configuration.nix` to configure my tablet according to my needs.

What I want to try with this blog post is to provide a more general guide on
how to configure most, if not any, XP-Pen drawing tablets or monitors on NixOS.

## The procedure

First of all, You need to find out the identifier for your tablet. with the
tablet plugged into the USB port, run `lsusb` (which is part of the `usbutils`
package). You should get some lines of output with an entry similar to this one:

```
Bus 001 Device 005: ID 28bd:0904 XP-Pen 11 inch PenTablet
```

The `28bd:0904` is the ID we are looking for. Note that the part after the
colon varies from device to device, so don't just copy&paste.

Now we enter the realm of the configuration. First of all, we need to enable
the digimend driver with the following settings:

```nix
services.xserver.digimend.enable = true;
```

Now we move on to having the wacom driver actually manage the XP-Pen devices.
For this we have to add rules to the `Xorg.conf`, which is conveniently handled
like this:

```nix
services.xserver.inputClassSections = [
  ''
    Identifier "XP-Pen 11 inch PenTablet"
    MatchUSBID "28bd:0904"
    MatchIsTablet "on"
    MatchDevicePath "/dev/input/event*"
    Driver "wacom"
  ''
  ''
    Identifier "XP-Pen 11 inch PenTablet"
    MatchUSBID "28bd:0904"
    MatchIsKeyboard "on"
    MatchDevicePath "/dev/input/event*"
    Driver "libinput"
  ''
];
```

These two sections match to my tablet, so alter all occurences of the lines
`Identifier` and `MatchUSBID` to match your device, otherwise it will not work.

With this you tell your system to let the wacom driver handle all tablet input
it can handle, everything else will be interpreted as a keyboard by `libinput`,
which includes all the hotkeys on your tablet, if you have any.

Now comes the fun part mapping the upper stylus button to be a right-click. For
this we need to analyse the input of the stylus using `evtest` (which is
contained within the package of the same name). With root permissions we run
`evtest` and see output containing lines similar to this:

```
...
/dev/input/event21:	11 inch PenTablet Mouse
/dev/input/event22:	11 inch PenTablet Keyboard
/dev/input/event23:	11 inch PenTablet
...
Select the device event number [0-23]: 
```

Select the device without `Mouse` or `Keyboard`, so `23` in this example.

You will get an overview of all input events supported by this device and when
you bring your stylus near the pad it should pick up all movements and button
presses you make and print them onto the console. To abort this testing, press
`Ctrl` + `C` on your keyboard.

Depending on your device, the output of the stylus test will produce a lot of
output, because all position and tilt changes will be recorded onto the console.
what we are looking for though is the input of the upper stylus button, so
press it a few times trying to hold the pen as steady as possible and abort
shortly after your button presses.

Now you need to look for specific lines in the console output, which will look
somewhat like this:

```
Event: time 1624813216.995575, type 4 (EV_MSC), code 4 (MSC_SCAN), value d0045
```

The most important keyword here is the `code 4 (MSC_SCAN)`, so search for that,
and note the value behind it. In this case it is `d0045`. This value, by the
way, seems to be the standard value for the right-click with XP-Pen tablets,
as it is the same with all three tablets or monitors I have set up with this
method so far.

After we extracted the right-click value of the stylus, let's return to our
configuration file and add the following option:

```nix
services.udev.extraHwdb = ''
  evdev:input:b0003v28BDp0904e0100-e0*
    KEYBOARD_KEY_d0045=0x14c
'';
```

This rule will do the actual remapping of the button press on the stylus to
right-click. Note, that the USB-ID of your device is present in here too,
so change this line so it matches your device:

```
evdev:input:b0003v<vendor-id>p<product-id>e0100-e0*
```

The line below contains the value of the upper stylus button (`d0045`) and maps
it to the right-click value (`0x14c`).

Congratulations. You just configured right-click on your stylus.

To map your hotkeys on your tablet, you need to run `evtest` again, but this
time you want to test the device with the keyboard description. Press your
hotkeys and note the values behind the `code 4 (MSC_SCAN)` lines. 

Then remap the values to your desired keys. Note that not all hotkeys support
multikey bindings, but only those emitting multiple different keypress codes.

I hope this tutorial is helpful for you in any way. If you feel that I missed
something or need some clarification, just get in touch and I will expand this
article as needed.

Keep calm and wash hands.

## Errata and Addenda

### How to map your tablet input to a specific monitor

I completely forgot to write about this part. The most generic way to do this
is to find out the ID of your stylus via `xinput`, and then the number of the
graphics output you want to map it to using `xrandr --listactivemonitors`.
You are interested in the number prefacing the monitor/connection descriptor.

After accomplishing this, you enter the following command:

```bash
xinput map-to-output <Stylus-ID> HEAD-<Output-No>
```

### Wrong driver activation

In the article I stated to enable the wacom driver, which actually is not
absolutely needed, but I forgot to mention the digimend driver,
Which is activated by this setting:

```nix
services.xserver.digimend.enable = true;
```

The according section in the article has also been corrected.

[nixos]: https://nixos.org