keyd profile + live HUD for a 4x3 macro pad

mini-keyboard

Turn the generic USB mini keyboard 4132:2107 into a modal macro pad: application shortcuts, navigation keys, and a calculator-style number layer. The companion HUD shows the active map, collapses when idle, and lets you edit mappings without hand-writing keyd config.

Install guide Choose setup path

Input layer: keyd
Desktop: KDE Plasma 6 / Wayland
Device: 4x3 USB pad

Preview of the 4 by 3 macro pad and the live HUD panel.

Two ways to use it

Install manually, or let this page run supported local actions.

Manual setup is the default path. If you already use web2local, this page can also trigger a small local helper for status checks, validation, logs, and HUD setup.

Option 1

Manual terminal setup

Clone the repo, install keyd, apply the keyd profile, then start the HUD. Use the Start section below for the exact commands.

Read the manual steps

Option 2

Use web2local from this page

Start web2local locally, then use this page to call tools/web2local-minipad.sh. The helper only accepts named actions, not free-form shell input.

python3 /home/lue/boring/web2local/daemon.py

Open web2local

web2local actions

After web2local is running, set the local checkout path and run one of the supported helper actions.

Local checkout path

web2local output appears here.

Quick start

Manual setup from a terminal.

The installer copies config/default.conf to /etc/keyd/, restarts keyd so the default mode is clean, and installs the root helper used by the HUD editor.

1. Clone the repo

git clone https://github.com/LueApp/mini-keyboard.git
cd mini-keyboard

2. Install keyd

sudo apt-get install -y keyd

3. Apply the mini-pad config

./install.sh

4. Launch the HUD

hud/install-hud.sh

Mode guide

Three maps, switched by row-corner chords.

Press both outer keys of a row at the same time. Single taps still run their normal per-mode action; only the two-key chord changes mode.

Daily use

The HUD only stays large when it is useful.

Unplugged

The panel hides when the configured USB pad is not connected.

Connected and idle

After about 10 seconds, the HUD collapses to a small draggable mode dot.

In use

Any pad activity or a click on the dot expands the full key map immediately.

Editing guideline

Use the panel editor for regular remaps.

Click the edit control in the HUD, choose a mode, then click any key cell. The save path writes through pkexec /usr/local/sbin/minipad-apply, validates the keyd file, restarts keyd, and rolls back automatically if the daemon reports errors.

Open edit mode
Select the mode pill you want to change, or add a new mode with its own two-key chord.
Remap a key
Pick a preset or type a raw keyd value such as C-c, up, 5, or macro(text enter).
Save safely
The helper rejects symlinked input, inline comments, unsafe mode names, duplicate chords, and keyd command() bindings.

Troubleshooting

Useful checks when a mapping does not behave.

Config errors

journalctl -eu keyd

Discover device IDs

sudo keyd.rvaiya monitor

Watch mode changes

sg keyd -c 'keyd.rvaiya listen'

Post-remap output

python3 tools/keyout.py

Panic recovery: hold backspace + esc + enter to kill keyd and return raw input if keys ever wedge.