Configuring the XpPen ACK05 Remote with only FLOSS on GNU/Linux: my investigation and workarounds.

Here is my research on how to use and configure the XPPen ACK05 Remote using only Free Libre and Open Source drivers and software under GNU/Linux. As you'll see, it's quite limited and some features just don't work. This guide will be updated as soon as I have new information on how to improve it, or as soon as new development improves support for this device.

Terminology:

• ACK05 → The XPPen ACK05 Remote Controler device.
• FLOSS → Free/Libre and Open-Source Software.

Update:

• 2024-10-07: At the request of @whot, I released the full hid-recorder, on the udev-hid-bpf project.
• 2024-10-06: Added the Input-Remapper method thanks to a comment by Raghukamath.

Device presentation

The ACK05, looks like a numeric keypad with a dial ring and nothing written on the keys. It comes with the "Pro (gen2)" tablet models of the XpPen brand: the Artist Pro (gen2) 14, 16 and 19 but also the Deco Pro (gen2) XLW, LW and MW. Well, it sounds like XPPen just decided to make the ACK05 the default remote for all their future tablets.

I got mine with my XpPen Artist 16 Pro (Gen2), which I reviewed last year.

But you can also buy one alone on the XpPen store for about $50. In fact, you don't need to pair the ACK05 with a tablet to use it properly; it's a standalone device. For artists, this small keyboard gives them closer access to a number of common keyboard shortcuts.

Photo of the XPpen ACK05 in usage situation for me, a right handed user of the Artist 16 Pro

Disassembling the ACK05

The ACK05 is also a tiny programmable keyboard in disguise, the Official User Manual (PDF) mention the device has a small memory to store the configuration. It also has its own microcontroller unit (MCU), an ID M52833 QIAAA0 2310AI code on it, a Nordic nRF52* family. It's a multi-protocol system-on-chip with lots of information and specifications (PDF) on the manufacturer's website.

Photo: tearing down the ACK05 device

What works, what doesn't

USB-C cable connection → it works out-of-the-box. For some reason, it's the only way to connect the device on GNU/Linux right now.

Bluetooth direct → it doesn't work. I tested it on three Bluetooth-enabled GNU/Linux computers I had at home and different distros. You can turn on the device and press the middle-of-the-dial button for 6 seconds until the LED flashes quickly, but none of them will see or pair with the device.

The USB dongle → it doesn't work. This is strange because I have never seen a mouse or keyboard with its own USB dongle have this kind of problem.

The Default Keyboard Shortcuts → it works out-of-the-box with a rather questionable layout. On the plus side, you have the three keys Shift, Ctrl and Alt clearly side by side in the middle of the device, and underneath a space bar that is easy to reach with the thumb. Undo and redo are surprisingly FLOSS standard: Ctrl+Z for undo, and Ctrl+Shift+Z for redo. On the bad side, the ACK05 key layout under GNU/Linux will automatically load the same layout as your main keyboard layout: in my case an Azerty French keyboard. This means that the default Ctrl+Z of the ACK05 will return a Ctrl+W by default, which is dangerous because it closes the document in many applications. In addition, while shortcuts like Ctrl+O for opening files and Ctrl+N for creating new ones are standard, their non-frequent use in workflows raises questions about their necessity, since these actions are typically performed only once per artwork.

The Dial → it kinda works out-of-the-box. The dial returns a Ctrl+ and Ctrl- action. It zooms in and out in Krita, and that's fine. However, the middle button of the dial has no effect and feels like it is disabled.

Customisation of keys → you can improve it, slightly. And that's my transition to the next part of this article!

Customising the keys

The input-remapper method

Input remapper is a software that can change the behavior of almost any input device. It supports X11, Wayland, combinations, programmable macros, joysticks, wheels, triggers, buttons, mouse movements and more. In short, it maps any input to any other input.

If you haven't read the User Guide, it might take you a while to understand the GUI and how to set up your first key association with a new device. But once you get started, you'll notice it can also map macros and also mouse clicks if you ever want a key to trigger Krita's pop-up palette. A list of examples will help you understand the endless possibilities, like setting new shortcuts when you double-tap a key, or assigning multimedia keys.

Also, amazingly, the input remapper is able to catch the event for the middle key of the dial. It catches it for a "Ctrl+$" input, no surprise this key didn't do anything on my computer. but setting the dial with it is still very difficult: it looks like it's not capable of catching the events correctly. When tested: the keys of the dial remains not really functional.

Finally, the input remapper developers made it easy to move the configuration from one machine to another by storing the preferences in JSON files that are simply stored in $HOME/.config/input-remapper-2.

So the main drawbacks: the dial doesn't work with it and I couldn't find a macro code to switch to the next preset. So it looks like it is not possible to use multiple layout this way.

The Input-remapper interface while configuring the first top row of buttons of the ACK05

The udev/hwdb.d method

If you can't install or run input-remapper, your only other option is to manipulate the keystrokes of the default built-in layout directly with a udev/hwdb.d ruleset. This is far from ideal and has many limitations, but at least it succeed at customizing a part of the dial inputs. I have already published a full tutorial on this for USB numeric keypads.

the MSC Scan code on the default layout.

The limitations: You cannot change, for example, the 'Ctrl+O' (double-key) shortcut to 'M' (single-key). You can only replace one of the keys in the shortcut. For example, you can change the 'O' to a 'T', and the shortcut will become 'Ctrl+T' (transform tool in Krita). Also keep in mind that changing 'Ctrl' will affect all other shortcuts that use 'Ctrl', so it's generally not advisable to do this.

With this limitation, all I can do is find a better use for the top three shortcuts. I'm going to replace them with a quick action combo in Krita to deform/scale/rotate an area: Ctrl+r (rectangular selection), Ctrl+t (transform), Enter (apply/confirm/validate). I'll also fix the bug with the French Azerty layout that prevents me from using Undo and Redo.

The MSC Scan change proposal, in green.

Follow the my previous tutorial for detailed steps, but in short, I create a new udev/hwdb.d rule:

sudo $EDITOR /etc/udev/hwdb.d/99-xppen-ack05-remote.hwdb

And I paste this custom code for the keys (and also my fix for the Azerty keyboard on the last line).

evdev:input:b0003v28BDp0202*
 KEYBOARD_KEY_70012=0x13 # [o] => [r]
 KEYBOARD_KEY_70011=0x14 # [n] => [t]
 KEYBOARD_KEY_7003e=0x1c # [F5] => [enter]
 KEYBOARD_KEY_7001d=0x11 # /! azerty french keyboard fix [z] => [w]

then I save and refresh systemd-hwdb and udevadm.

sudo systemd-hwdb update && sleep 2 && sudo udevadm trigger

done!

Programing the hardware

It's probably impossible to program the ACK05 with FLOSS. And by that I mean storing a firmware directly in the flash memory of the micro controller and reprogram the default shortcut keys at root.

I spent more than a day trying and every method I tried was a dead end. Even for specialized FLOSS software in programmable keyboards like QMK Firmware it is impossible. FLOSS projects tend to flee the Nordic nRF52* family of micro controllers because all the tools available so far are proprietary.

(Note: I'm not even 100% convinced that this is a feature of the product, but there is a "Save" and "Import" feature on the Windows driver, according to the documentation. It could simply be a way to save the setting that the driver will load later).

Conclusion

No wireless and a dial that does not really work (especially the middle button). Yes, it's far from what this device is capable of: being wireless and having multiple layouts.

But the fact that it somehow works for its core functionality "out-of-the-box" and without anyone working on a specific driver is a kind of small miracle of ingenuity; both from XpPen and from the input-remapping team and input Linux developers. So bravo!

An idea for XpPen engineers; if you want to make the next iteration better, just look at how an open source project like the Duckypad handles drivers and customization.

In any case, a simple $15 USB numeric keypad will be of more value to your workflow under GNU/Linux such as the one I build in my tutorial. There are many variations on this: my favorite shortcut device at the moment is a little yellow "8Bit do Zero 2" gamepad. It connects via bluetooth and has a built-in mode that turns all buttons into keyboard input (with only one key press, for video games). With a udev/hwdb.d rule it became a perfect keyboard shortcut tool while painting. Especially because I can hold it in my left hand and it follows all my positions.

Sources

• The ACK05 Official User Manual (PDF).
• The ACK05 on XpPen store (not affiliated
• Screenshot on Reddit of firmware uploading on MsWin (in comments).
• QMK Firmware, a FLOSS CLI app for keyboard firmware.
• QMK "Compatible Microcontrollers" documentation.
• QMK issues mentioning nRF52 on Github
• nRF52 MCU informations, specifications (PDFs).
• Adafruit_nRF51822_Flasher.
• Nordic proprietary CLI tool for nRF52
• Arch Linux documentation about Scancode using Udev
• Review of the XpPen windows proprietary driver on Parkablog
• ACK05 hid-recorder dials and all keys: issue on the udev-hid-bpf project