keydial-config

Web GUI for remapping the Huion Keydial Mini (K20) on Linux. Click buttons on a visual layout to assign actions — keys, combos, macros, or typed text. Swap between profiles in one click.

Built on keyd, so it works at the evdev level and supports Wayland natively.

Why

The Keydial Mini ships with Windows-only configuration software. On Linux, keyd can remap it — but editing .conf files by hand means memorizing which physical button sends which keycode. This shows you the device layout and lets you assign actions by clicking.

How it works

Browser UI  →  Flask API  →  .conf file  →  keyd-apply (sudo helper)  →  keyd reload

• Flask reads and writes keyd .conf files
• A locked-down sudo helper copies the config to /etc/keyd/ and reloads keyd
• Flask never runs as root

Install

Requires Python 3.11+ and a Huion Keydial Mini (256c:8251). The installer handles everything else — keyd, venv, sudo helper, systemd service, desktop shortcut.

git clone https://github.com/lukeslp/huion-keydial-linux.git
cd huion-keydial-linux
./setup.sh

That's it. The GUI starts automatically and survives reboots. Search "Keydial" in your app launcher to open it.

• Cheat sheet: http://localhost:8484/layout
• Editor: http://localhost:8484

Manual setup

If you'd rather not run the installer:

python3 -m venv venv && source venv/bin/activate
pip install flask

# Sudo helper (lets Flask apply configs without running as root)
sudo cp keyd-apply.sh /usr/local/bin/keyd-apply
sudo chmod +x /usr/local/bin/keyd-apply
echo "$USER ALL=(ALL) NOPASSWD: /usr/local/bin/keyd-apply" | sudo tee /etc/sudoers.d/keyd-apply

# Run manually
python3 app.py --port 8484

Profiles

Ships with three profiles:

• claude-code — Arrow diamond on the physical cluster, tap/hold dual-action for quality gates, slash commands across the device
• general — Desktop navigation, clipboard shortcuts, workspace switching
• krita — Brush tools, layer management, view controls

Pick one from the dropdown, customize it, Save & Apply.

Custom macros

Type any text in the custom macro field and the device plays it back keystroke-by-keystroke. Check "+Enter" to append a return. Good for slash commands or anything you type often.

Physical button map

The Keydial Mini sends these raw keycodes (discovered via sudo keyd monitor):

Row 1:  k         g         l         delete
Row 2:  i         d         b         e
Row 3:  s         z         c         v
Row 4:  lctrl     lalt      lshift
Row 5:  space     n
Standalone: enter
Dial push: playpause
Dial scroll: page up / page down (native, no remap needed)

Project structure

setup.sh              Installer — keyd, venv, sudo helper, systemd service, desktop shortcut
app.py                Flask app — parse/generate keyd .conf, apply via sudo helper
keyd-apply.sh         Copies .conf to /etc/keyd/ and runs keyd reload (sudo)
templates/index.html  Editor UI with visual keydial layout
templates/layout.html Read-only quick reference view
profiles/*.conf       Pre-built keyd configs

Adapting to other devices

The device ID and physical layout are defined at the top of app.py. To support a different keyd-compatible device:

1. Run sudo keyd monitor, press every button, and record the keycodes
2. Update DEVICE_ID and the LAYOUT dict in app.py
3. Add or modify profiles in profiles/

License

MIT