Customizing my tablet
via command line

07/30/23 2348 words

I own a Huion Inspiroy H640P. Unfortunately, the driver doesn't have great support on Arch Linux, so I wondered if there was a way to change the settings programmatically.

The three things I wanted to customize:

1. Invert the tablet display (I'm left-handed, so I want the buttons to be on the right, not the left).
2. Restrict the tablet to one monitor. I use two monitors, and the default setting is to map the tablet across both, doubling the horizontal sensitivity.
3. The tablet has six buttons on the side, and I want to map them to useful commands (e.g. moving a page up or down.)

After a bit of web browsing, I managed to cobble up a solution in a Bash script. This post will go through what I did.

Probing the tablet

Because I'm running the X Window System, I can use the xinput utility to gather info on my devices. If we execute xinput list on the command line, we should get something like:

$ xinput list
⎡ Virtual core pointer                          id=2    [master pointer  (3)]
⎜   ...
⎜   ↳ HUION Huion Tablet_H640P Pad              id=13   [slave  pointer  (2)]
⎜   ↳ HUION Huion Tablet_H640P Pen Pen (0)      id=22   [slave  pointer  (2)]
⎜   ...
⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
    ...
    ↳ HUION Huion Tablet_H640P Pen              id=11   [slave  keyboard (3)]
    ↳ HUION Huion Tablet_H640P Keyboard         id=13   [slave  keyboard (3)]
    ...

The "..." means I removed irrelevant output. What's left are all the input devices associated with the Huion tablet, but figuring out the exact function of the listed devices from name alone isn't that intuitive. Let's poke into HUION Huion Tablet_H640P Pad by calling xinput list-props 13, where 13 is the id of the device:

$ xinput list-props 13
Device 'HUION Huion Tablet_H640P Pad':
        Device Enabled (153):   1
        Coordinate Transformation Matrix (155): 1.000000, 0.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000, 0.000000, 1.000000
        libinput Left Handed Enabled (303):     0
        libinput Left Handed Enabled Default (304):     0
        libinput Send Events Modes Available (266):     1, 0
        libinput Send Events Mode Enabled (267):        0, 0
        libinput Send Events Mode Enabled Default (268):        0, 0
        Device Node (269):      "/dev/input/event5"
        Device Product ID (270):        9580, 109

Okay, there's some useful information here. We know the device is enabled and there are some libinput settings currently set to false (0). In fact, there's a property specifically for left-handed use, so I set that property to true via xinput set-prop 13 303 1, where 303 is the id of the property. But that didn't do anything.

What's most interesting to me, though, is the property named Coordinate Transformation Matrix. What seems to be a list of nine floats is actually the identity matrix in disguise once we arrange it in a 3x3 grid. This is a typical representation for anything related to computer graphics, and it also gave me a clue on how I could customize the tablet's display: I needed to use affine transformations.

To stay on topic, I won't go too deep into matrices or transformations, so there may be some intuitive gaps in my explanations.

Reorienting the tablet

In the previous section, I mentioned how the Coordinate Transformation Matrix was actually the identity matrix in disguise: \[ [1.000000\quad 0.000000\ \cdots\ 0.000000\quad 1.000000]\rightarrow \begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{bmatrix} \] We can think of the identity matrix as the "default state" for the tablet -> screen mapping. The reason why we represent the screen as a matrix is to afford a convenience: by multiplying this matrix with other matrices, we can change the orientation of the screen rather easily.

Affine transformations

Okay, so we have something called an "identity matrix" that represents the default mapping. What can we do with it?

Let's start with a motivating example. Imagine we hook up a tablet to a single monitor, but the tablet's vertical input is upside down:

If we point our stylus at the bottom left of the tablet's drawing area, the cursor would display in the top left of the screen instead. To fix this, we first need to flip the tablet across the x-axis. Assuming we have a Coordinate Transformation Matrix to work with, we can multiply the identity matrix by:

For those unfamiliar, the intuition behind the "flip" matrix is to turn all the y-coordinates in the default state negative, thus "flipping" it over the x-axis. Here's a whole list of affine transformations and their corresponding matrices; I'll be pulling from this chart later on.

Another thing: we need to order the transformations from right to left, starting from the most recent transformation to the last. This will be useful to keep in mind while we work with more complex transformations.

Now the screen should be oriented correctly, but because we flipped over an axis, the tablet's drawing area is actually out of bounds. If we picture the tablet itself on a grid, this notion becomes a little more clear:

I put a little red marker to demonstrate how the tablet's orientation changed after the flip, but see how the screen lies outside the tablet's drawing area after the transformation? To solve this problem, we can perform a translation and move the transformed screen up 1. Visually, this looks like:

Mathematically:

In matrix algebra, the identity matrix can be thought as a \(1\); in other words, multiplying a matrix \(A\) by an identity matrix gives \(A\). So if we toss out the identity from the previous equation, it gives us the same answer:

If we set that matrix as our new Coordinate Transformation Matrix, it should correctly orient the tablet -> screen mapping.

Putting it all together

Let's take a look at the Coordinate Transformation Matrix again: \[ \begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{bmatrix} \] This matrix represents the tablet -> monitor mapping, and it's currently the identity matrix because we haven't made any changes yet (the default state). In my case, the tablet maps its drawing area over two monitors like this:

But the goal is to have something like this:

Contrary to the previous example, the origin is actually located in the bottom-right corner. This is because the origin's default position was in the top-left (a computer graphics standard with an interesting history), and then I rotated the tablet 180 degrees to move the buttons onto the right side. Here's a picture with the true axes:

I'll be visualizing the transformations on a graph, so don't worry if the change in coordinates feel confusing.

With that, we can start customizing. To keep things concise, here's how we can fix the mapping with three transformations:

We know that each transformation has a corresponding matrix and we can combine transformations by multiplying them from most recent to last. Then, our equation looks like this:

That matrix is our new Coordinate Transformation Matrix. Let's look at our device list again:

$ xinput list
⎡ Virtual core pointer                          id=2    [master pointer  (3)]
⎜   ...
⎜   ↳ HUION Huion Tablet_H640P Pad              id=13   [slave  pointer  (2)]
⎜   ↳ HUION Huion Tablet_H640P Pen Pen (0)      id=22   [slave  pointer  (2)]
⎜   ...
⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
    ...
    ↳ HUION Huion Tablet_H640P Pen              id=11   [slave  keyboard (3)]
    ↳ HUION Huion Tablet_H640P Keyboard         id=13   [slave  keyboard (3)]
    ...

We can set properties via xinput set-prop, but here we need to modify the tablet pen device (id=22), not the tablet pad (id=13). I don't know the exact reasons why, but after testing this empirically, it's the one that worked.

To set our new matrix, we enter the command: xinput set-prop 22 --type=float "Coordinate Transformation Matrix" -0.5 0 0.5 0 -1 1 0 0 1. This should correctly re-orient the tablet.

Customizing buttons

After figuring out how to customize the tablet -> screen mapping, I wanted to go a step further and customize the tablet buttons, too. The Inspiroy H640P has 6 buttons on the side:

We can access the button mapping with xinput get-button-map 13, where 13 is the id of the tablet pad:

$ xinput get-button-map 13
1 2 3 4 5 6 7 8 9 10

This tells us that there are 10 button inputs mapped to the tablet, with each button corresponding to a key id (1, 2, 3...) that represents what the button does. However, we don't know which button corresponds to what key id! We can figure this out using xinput test.

xinput test executes an interactive program that receives an input signal (a button press) and outputs information about that signal. So if we call xinput test 13 and press a few tablet buttons, our output would be something like:

$ xinput test 13
button press   10
button release 10
button press   9
button release 9
button press   8
button release 8
... # etc.

This gives us a direct method of assigning key id's to all the buttons. In this case, we have the mapping:

Now we need to figure out how to change them.

Modifying the button map

I like using my tablet for web-browsing, so my idea was to set the top two buttons (10 and 9) to be "page forward" and "page back", respectively. But "page forward/back" is already modeled as mouse buttons, so is there a way to probe what the id of those mouse buttons are and assign it to the tablet?

From the Arch wiki page on mouse buttons, we can use xev to check signals from the mouse:

$ xev -event button | grep button
state 0x10, button 9, same_screen YES   # page forward 
state 0x10, button 9, same_screen YES
state 0x10, button 8, same_screen YES   # page back 
state 0x10, button 8, same_screen YES
... # etc.

xev functions similarly to xinput test, in that both commands execute a program which reads and displays information about events. The previous code revealed that "page forward" has button id 9, while "page back" has button id 8. Interestingly enough, our tablet already assigned those id's by default, but not in a location I wanted.

To change this, we use xinput again but with the set-button-map argument:

$ xinput set-button-map 13 1 2 3 4 5 6 7 8 8 9

Don't be fooled by the long chain of numbers: there are only two arguments here. The first is the id of the tablet pad (13), and everything afterward is the button map we extracted from the previous section through get-button-map. This time, we performed a re-map and changed button 9 -> 8 and button 10 -> 9. I left the rest of the buttons as-is. Now, the top two buttons will send an event corresponding to those new id's and execute page forward/back accordingly.

Keyboard macros

The next thing I wanted to do was set buttons 8 and 3 to be PgUp/PgDn. This is tricky, because the tablet buttons read mouse button inputs, not keyboard inputs. As far as I know, there isn't a mouse button that corresponds to PgUp/PgDn; the closest thing we have is the scroll wheel, and that doesn't scroll far enough, especially when our button would only scroll once for every press!

One solution would be to define a custom mouse button id and hook it up to a keyboard automation utility called xdotool. In other words, we can use macros to make a mouse button act like a keyboard button.

To emulate a keyboard key using xdotool, we can simply type xdotool key [key]. So if we want to signal the letter "p", we do xdotool key p.

By using this list of key codes, we know how to call PgUp/PgDn:

xdotool key Page_Up
xdotool key Page_Down

There's also a utility called xbindkeys which binds an input (keyboard or mouse) to a command. The idea here is to use xbindkeys and bind custom mouse buttons to the xdotool commands in the previous code block, then map our tablet buttons to those custom mouse buttons. By the transitive property, our tablet will then be able to emulate keyboard inputs.

First, we create an empty file called .xbindkeysrc in our home directory. Within the file, we include the following lines:

"xdotool key PgUp"
    b:100

"xdotool key PgDown"
    b:101

The lines in quotes are our key commands, while b:100 and b:101 represent mouse button id's. I set them to 100 and 101 because default button id's don't go that high, so I'm assured they won't overwrite any existing functionality.

Once we save .xbindkeysrc, we can either call xbindkeys directly from the command line or place it in our window manager's config file to make the changes permanent.

Regardless, the final step is to change tablet buttons 8 and 3 to our custom-defined buttons. All we need to do here is edit the button map again:

$ xinput set-button-map 13 1 2 101 4 5 6 7 100 8 9

To prevent confusion, I also disabled all the other buttons by setting them to 99, which has no event attached:

$ xinput set-button-map 13 99 99 101 99 99 99 99 100 8 9

And we're finished.

Conclusion

Here's a summary of what we did:

1. Used xinput to get and set properties on the tablet
2. Reoriented the tablet's drawing area using affine transformations
3. Used xdotool and xbindkeys to modify our tablet buttons

It's easy to wrap our commands inside a Bash function and call it whenever the tablet is plugged in. For example, here's what I currently use:

# put this in ~/.bashrc

tablet-setup() {
    # device id's may change, so dynamically extract and assign to variable
    pen_id=$(xinput | grep -oP 'H640P Pen Pen.*id=\K\w+')
    pad_id=$(xinput | grep -oP 'H640P Pad.*id=\K\w+')

    echo 'pen id='$pen_id
    echo 'pad id='$pad_id

    # reorient tablet 
    xinput set-prop $pen_id --type=float "Coordinate Transformation Matrix" -0.5 0 0.5 0 -1 1 0 0 1

    # rebind buttons
    xinput set-button-map $pad_id 99 99 101 99 99 99 99 100 8 9 
}

And don't forget the xbindkeysrc config file:

# put this in ~/.xbindkeysrc

"xdotool key PgUp"
    b:100

"xdotool key PgDown"
    b:101

My next challenge is figuring out how to automate this, but I'll save that problem for later.

back