English · 한국어 · العربية · Deutsch · Español · Español (Latinoamérica) · Français · Bahasa Indonesia · Italiano · 日本語 · Polski · Português (Brasil) · Português (Portugal) · Русский · ไทย · Tiếng Việt · 简体中文 · 繁體中文
A Linux app that writes key settings to small USB macro keyboards — the ones sold with anything from a single knob to 21 keys, and up to four knobs. For each key and knob action (rotate left, press, rotate right) it sets key presses, a media key or a mouse action on layers 1–3, and the keyboard's lighting. It is the Linux counterpart of a macOS app built on the same rules, and speaks the same commands.
| Keyboard | Layout | Reads back | Waits | Lighting | Tried |
|---|---|---|---|---|---|
1189:8890 |
arranged by you — keys (up to 12), keys per row, knobs (up to 2) | no | no | three modes | yes — 6 keys and a knob |
vendor 1189 or 514C, product 8840 · 8842 · 8830–8833 · 8850 · 8851, newer firmware |
from what the keyboard says — 26 layouts | when connected | before each press | a mode, and a colour for each of keys 1–16 | yes — 514C:8850, 12 keys and 2 knobs |
| the same, older firmware | from what the keyboard says | when connected | one per key | a colour and a mode | no |
| the same, not saying what it is | chosen by you — 26 layouts | no | no | a colour and a mode | no |
The 1189:8890 is the keyboard the vendor's Windows tool "MINI KeyBoard" works with; the others are the ones the
vendor's cross-platform app "MINI_KEYBOARD" looks for. The app speaks both tools' commands. Most of the second
kind say how many keys and knobs they have and which firmware they run, and the app draws the layout the vendor's
app would; one that doesn't say gets the one of those layouts you pick. The vendor's app doesn't know the
1189:8890 and its own tool draws no shape, so its real shape isn't known: you tell the app how many keys and
knobs it has and how many keys are in a row, and it draws a tidy arrangement of that.
The app is available in 18 languages — English, Korean, Japanese, Chinese (Simplified and Traditional), German, Spanish (Spain and Latin America), French, Italian, Portuguese (Brazil and Portugal), Polish, Russian, Indonesian, Vietnamese, Thai and Arabic — and follows the language of the desktop. Other languages get English.
The source in this repository is MIT licensed. The app icon — in data/icons/, and the picture at the top — is
licensed under CC BY-SA 4.0 (LICENSES/CC-BY-SA-4.0.txt).
MINIKeyboard comes in four editions built on the same rules — the same commands, the same 18 languages. The three apps take the same keyboards; the web edition, which runs in the browser, takes them all but the 1189:8890.
| Repository | GitHub |
|---|---|
| MINIKeyboardApple |
github.com/hobbyworker/MINIKeyboardApple |
| MINIKeyboardWin |
github.com/hobbyworker/MINIKeyboardWin |
| MINIKeyboardLinux |
github.com/hobbyworker/MINIKeyboardLinux |
| MINIKeyboardWeb |
github.com/hobbyworker/MINIKeyboardWeb |
Open me.hobbyworker.MINIKeyboard.flatpakref in your software center, or run:
flatpak install --user https://mini-kb.hobbyworker.me/updates/linux/me.hobbyworker.MINIKeyboard.flatpakrefIt adds the app's own Flatpak repository, and the first install also fetches the GNOME runtime from Flathub. From then
on your software center — or flatpak update — brings new versions. Your settings stay.
Each version is also on the Releases page as a Flatpak
bundle — MINIKeyboard-<version>-x86_64.flatpak for Intel and AMD, -aarch64.flatpak for ARM — for a PC without a
connection, or for a particular version. A bundle installs with flatpak install --user <file> and then takes its
updates from the same repository.
Linux lets an app open a USB device only when a udev rule gives it to the signed-in user, and a Flatpak can't
install one. The first time, the app says that it needs access: How to Allow… shows the commands that write
the rule, with a button to copy them. Run them in a terminal once, then plug the keyboard in again. From a clone
of this repository, the same rule is data/60-minikeyboard.rules:
sudo install -m 644 data/60-minikeyboard.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger- The
1189:8890is written over USB directly (libusb): its configuration interface has only an OUT endpoint, so no driver takes it. - The others are written through the hidraw device of their first USB interface, as the vendor's app does. The keyboard keeps typing meanwhile.
make build # target/release/minikeyboard, for PREFIX (/usr/local unless given)
make install # after make build: the program, translations, desktop file, metainfo, icons and licences, into DESTDIR/PREFIX
make test # every crate's tests — no window opens, no keyboard is touched
make check # rustfmt and clippy; warnings are errors
make run # a debug build with its translationsIt needs Rust 1.88 or later and the development files of GTK 4, libadwaita 1.7 or later, libsoup 3 and libusb 1.0 —
on Debian and Ubuntu libgtk-4-dev libadwaita-1-dev libsoup-3.0-dev libusb-1.0-0-dev, on Fedora gtk4-devel libadwaita-devel libsoup3-devel libusb1-devel — and gettext's msgfmt for the translations.
The app's ID (me.hobbyworker.MINIKeyboard), name and links are its own and match the desktop file, metainfo and
icons in data/. A fork gives its own at build time: MINIKEYBOARD_APP_ID (also the icon's name),
MINIKEYBOARD_APP_NAME, MINIKEYBOARD_COPYRIGHT, MINIKEYBOARD_WEBSITE and MINIKEYBOARD_ISSUE_URL. make build
takes where the translations are from PREFIX; MINIKEYBOARD_LOCALE_DIR at run time overrides it, for trying a build.
The app can also tell about new versions itself: a build given MINIKEYBOARD_UPDATE_FEED reads that RSS feed at
launch and once a day — unless Check for updates automatically is switched off in Preferences — and on
Check for Updates…, and shows a banner that links to the new version's download page. The app's own builds don't
use it — Flatpak brings their updates — so they have no such menu item or setting.
The Simulator submenu lets you try the app without the keyboard in question: pick a 1189:8890, a layout on
newer firmware, or a keyboard that doesn't say what it is, and the app acts as if it were plugged in — through the same
commands, nothing going to USB. While one is in use, an orange bar at the top of the window says so, and Back to the
Keyboard on USB returns. Debug builds offer every kind (the 1189:8890's other report IDs, older firmware), and
MINIKEYBOARD_SIMULATED_KEYBOARD (for example 8890-3) starts on one. Device Log shows every report written and
every answer.
- Connect the keyboard over USB. The app finds it, and asks a keyboard of the second kind what it is; one that answers is read at once.
- A keyboard that doesn't say its shape asks for its layout the first time — one of the vendor app's layouts, or
for the
1189:8890its keys, keys per row and knobs — and how it sits in front of you. The app remembers both for that USB ID. Shape… and Rotate (Ctrl+T) change them later; a keyboard that said its shape only turns. - Pick a layer, then the key or knob action on the keyboard.
- Give it an action:
- Keys — hold modifiers (Ctrl, Alt, Shift, Super, and the right-hand ones), then click keys; each click adds a press. Modifiers Only turns the key into a modifier key. QWERTY lays the keys out as on a full-size keyboard, ABC in groups; only the keys the keyboard takes can be clicked.
- Multimedia, Mouse — replace what the key did.
- LED — the layer's lights; on newer firmware, select one of keys 1–16 to give it a colour.
- Delay — on firmware that keeps waits.
- Save (Ctrl+S) writes what changed. Read (Ctrl+R) asks a keyboard that reads back what it holds.
Preferences (Ctrl+,) picks the interface language (one of the 18, or the desktop's) and light or dark; in a build with an update feed, its General page has the automatic update check. About MINIKeyboard has the version and the open source licenses.
Preferences ▸ General ▸ Firmware Workarounds has Prevent key repeat after changing the lighting, on by
default. After its lighting is saved, the 1189:8890's firmware repeats a key's first stroke without end — its
maker's software does the same — so the app sends one more save, with no key in it, after the lighting. Off, the app
sends just what the maker's software sends. That keyboard also forgets its lighting when it's unplugged.
The rules live in crates whose dependencies point inwards — a layer that reaches outwards doesn't compile.
crates/
├── domain/ keyboards, actions, the controls of each layout and what each keyboard can hold; the ports; use cases (the standard library only)
├── datalayer/ the commands of each keyboard and the numbers its controls go by; finding it in sysfs and writing over USB (libusb) or hidraw; simulated keyboards
├── presentation/ view models and the values the screens draw — the layouts' geometry, key and colour tables, the udev rule (no toolkit)
├── ui/ GTK 4 and libadwaita — sees the presentation only; the new-version notice (libsoup)
└── minikeyboard/ the composition root: the only crate that sees them all
po/ translations, one file per language
data/ the desktop file, metainfo and icons, and the udev rule
LICENSES/ the icon's licence (CC BY-SA 4.0)
Zero warnings is the bar. Warnings are fixed, not switched off.
- Writing has been tried on two keyboards so far, on Fedora: a
1189:8890with six keys and a knob, and a514C:8850with twelve keys and two knobs, on newer firmware, opened through hidraw. The other keyboards are written as their vendor's app writes them — the commands are the macOS app's, byte for byte, and tests pin them — but none has been tried yet. - The
1189:8890, and keyboards that don't say what they are, can't report their settings, so the app shows only what was set in it. - One keyboard is open at a time. With several plugged in, the button beside the connection status chooses which; the
app opens the one chosen last time, or else the first it finds, a
1189:8890first. - Mouse movement and dragging are not offered.
MIT — see LICENSE. The app icon: CC BY-SA 4.0 — see LICENSES/CC-BY-SA-4.0.txt.
