gKeyMapper

GTK4 application (C++) for remapping the G keys G1–G9 of a Logitech G910 to other keys or commands (Linux Mint / Ubuntu).

The GUI is complete. The background daemon (gkeymapper-daemon) that reads the G-keys from the keyboard and replays the actions is implemented as well; the GUI and the daemon talk over a small D-Bus channel (status, reload, test) — see docs/daemon-plan.md.

Only the daemon has to run. It is the part that reads the G keys and replays the action, and it runs as a systemd user service. The window is for editing the mappings and for the status: it may be closed at any time, and starting it with the session (Options → Start with the session) is a convenience, not a requirement.

Documentation and source comments are written in English.

Requirements

• Linux Mint / Ubuntu
• g++ (C++17)
• pkg-config
• gettext (for translations, msgfmt)
• GTK 4 development files
• libusb 1.0 development files (for the daemon)
• libxkbcommon development files (for the daemon's layout handling)
• GLib/GIO development files (for the GUI ↔ daemon D-Bus channel; libgtk-4-dev already pulls them in, but they are needed for make daemon on its own)

Install dependencies

sudo apt update
sudo apt install -y build-essential gettext libgtk-4-dev libusb-1.0-0-dev libxkbcommon-dev libglib2.0-dev

Afterwards pkg-config --modversion gtk4, pkg-config --modversion libusb-1.0 and pkg-config --modversion gio-2.0 should print versions.

Setting up the project

Change to the project directory:

cd gKeyMapper

(Use the path where you cloned or copied the repository.)

Build

make

This produces the gkeymapper GUI binary, the gkeymapper-daemon binary and the .mo translations under locale/. The daemon can also be built on its own with make daemon. The GUI has its icons (assets/icon.png, assets/icon.svg) compiled in (data/icons.gresource.xml → generated build/gresources.c), so the window icon works without an installed assets/ directory.

A .deb package can be built with

make deb

which produces gkeymapper_<version>_<arch>.deb. Installing it runs systemctl --user daemon-reload and systemctl --user enable --now gkeymapper-daemon for the installing user.

Rebuild translations

make translations

Adding or changing a translation, adding a language, and the checks around them are described in po/README.md. scripts/i18n.sh does the work and is wired into the Makefile:

make pot              # regenerate po/gkeymapper.pot from the sources
make i18n-check       # pot, catalogs and the language list of the GUI
make i18n-status      # per language: translated, fuzzy, untranslated

Run

Normal:

./gkeymapper

With explicit language files (useful for testing from the build directory):

LANG=de_DE.UTF-8 GKEYMAPPER_LOCALEDIR=$PWD/locale ./gkeymapper

Supported languages: German, English, Spanish, French.

The footer of the window shows the daemon state (Daemon: running · Device: … plus the last G key that fired, or Daemon: not reachable) and follows it live: start or stop the daemon while the GUI is open and the line updates itself. Two more states are reported explicitly: Device: not found (the daemon is up but has no keyboard) and Configuration error (a reload failed, so the daemon kept the mappings it had).

The window starts from the saved mappings: it loads ~/.config/gKeyMapper/mappings.conf when it opens, so Save mappings in a fresh window rewrites the same content instead of emptying the file.

Only one window is open at a time, and it is the one you just started: a new start closes the instance that is already running — including one from an older build — and then shows its own window, so a stale window can never stay next to a fresh one. The rows of the window it replaced come along, so an edit that was typed but never saved is still there; an instance from an older build cannot hand them over, and then the window shows the saved mappings. Saving itself stays explicit either way: press Save mappings.

Menu, tray icon and minimize to tray

The menu button in the title bar holds Export configuration... / Import configuration..., Options, Help (also F1), About and Quit (Ctrl+Q).

• Help opens a one-page explanation of the nine rows, the four types, the capture dialog, the daemon status and the tray.
• Options opens a small window with the GUI's own switches and the daemon in detail: state, version, keyboard, the config file it reads and the last G key that fired (the footer says the same in one line). The window is not modal, so it keeps updating while it is open. One of its switches is the language (System language, or a fixed de/en/es/fr): it switches the window, the menus and the tray menu right away — nothing to restart, and rows that were not saved yet are kept.
• Start with the session starts the window minimized in the tray when you log in: it writes the usual autostart entry (~/.config/autostart/gkeymapper.desktop, starting the binary that is running with the --start-hidden argument) and removes it again when you switch it off; an entry that the desktop's own startup tool has disabled counts as off, too. The window then waits in the tray until its Show, and only a desktop that hosts that icon can leave it hidden — one without a tray gets the window a few seconds after login. Like the window itself this is a convenience: the G keys do not need it, only the daemon has to run (see Running the daemon below).

Minimize to tray keeps gKeyMapper reachable from the panel: the window is hidden instead of closed when you close or minimize it, and the tray icon's menu shows it again (Show) or quits the program (Close). Closing still quits when the option is off — or when no panel hosts the tray icon, because then there would be no way back to the window. The option is remembered in ~/.config/gKeyMapper/gui.conf, a file of its own so mappings.conf stays a pure mapping file. The same file holds the chosen language; with System language (the default) the desktop's locale decides.

The tray icon is a StatusNotifierItem plus a com.canonical.dbusmenu menu over GIO — the same protocol libxapp and libappindicator wrap, only without their GTK3 dependency (a GTK4 process must not load GTK3). It needs no package of its own and works wherever the protocol is hosted: the Cinnamon panel (via xapp-sn-watcher), KDE, Unity or GNOME with the AppIndicator extension. The icon travels as a pixmap because the panel is a different process and cannot read the icons compiled into the binary.

Running the daemon

The daemon reads G1–G9 from the keyboard and replays the configured action (key through a virtual keyboard, command by launching the program):

./gkeymapper-daemon                 # uses ~/.config/gKeyMapper/mappings.conf
./gkeymapper-daemon /path/to.conf   # or an explicit file

• It reaches the keyboard through libusb (raw USB HID, vendor interface 1) and creates a virtual keyboard via /dev/uinput. Both need access for your user; make install ships a udev rule (TAG+="uaccess") for that. On Linux Mint the device already has such an ACL, otherwise install the rule or add your user to the input/uinput group.

• The media keys (mute / volume / play / next / previous / stop) keep working while it runs. The keyboard delivers them on the vendor interface — as a second kernel input device (…/input1, the "… G910 Keyboard" consumer device) when the daemon is not running — so the daemon picks those reports up and forwards them unchanged through its virtual keyboard. There is nothing to configure; they behave exactly as they do without the daemon.

• The mappings file is watched: save in the GUI and the daemon picks the change up by itself (within about half a second), no restart and no signal. SIGHUP/SIGUSR1 reload it on demand, which is also the fallback on systems without inotify:

  kill -HUP $(pgrep -x gkeymapper-daem)
  

  Note: the kernel truncates the process name to 15 characters, so pgrep -x gkeymapper-daemon does not match.

• A failed reload keeps the previous mappings, so a transient read error never silently disables every key. The GUI shows it as Configuration error in the footer.

• It does not need the keyboard to be present: when it is unplugged (or not there yet when the session starts) the daemon keeps running, reports Device: not found and looks for it again every 2 s. A re-plug needs no restart and keeps the GUI connection.

• A G key fires when its report first shows it as pressed: holding it down does not repeat the action, and two G keys held at once both fire (the report carries the state of all nine keys, not one key per report).

• keyhold is the exception to that: its keys stay pressed for as long as the G key is held, like a normal key (including the desktop's auto-repeat), so a game or a push-to-talk sees a key that is down exactly as long as you hold the G key. The keyboard's release report ends it. If the keyboard is unplugged or the daemon stops while a key is held, the daemon lets it go, so nothing stays stuck. Holding only makes sense for a single step: keyhold:ctrl+w is held, keyhold:ctrl+c,ctrl+v is replayed as a tap (the log says so).

• Only one instance may run: a second one prints why it cannot get the bus name and exits, instead of fighting over the keyboard and creating a second virtual keyboard.

• Key names are layout-independent: key:ctrl+z means the key that produces z on your layout. The layout is read from /etc/default/keyboard (XKBLAYOUT); without it, US key positions are used. Because the name is symbolic, the same entry keeps its meaning if the layout changes (as long as the layout has that key); a name the layout does not provide is skipped.

• altgr+... presses AltGr (level 3), e.g. key:altgr+7 types { on a German layout.

• command:... is run through the shell, so arguments work (command:/usr/bin/firefox --new-window); a plain program path is also fine. It inherits the environment of the user service, i.e. of your desktop session — DISPLAY, XAUTHORITY and PATH are already there on a normal setup. If a command cannot reach the display, export them into the user manager:

  systemctl --user import-environment DISPLAY WAYLAND_DISPLAY XAUTHORITY
  systemctl --user show-environment | grep DISPLAY
  

Stop it with Ctrl+C or kill; it reattaches the kernel driver on the way out.

Status and control over D-Bus

The daemon owns the name dev.rager.gkeymapper.Daemon on the session bus. The GUI uses that channel for its footer line ("Daemon: running / not reachable", the device and the last G key that fired) and to apply a save immediately. Nothing on this channel is on the keypress path, so a GUI that is slow or absent never delays an action.

D=dev.rager.gkeymapper.Daemon
O=/dev/rager/gkeymapper/Daemon

gdbus call --session --dest $D --object-path $O --method $D.GetStatus
gdbus call --session --dest $D --object-path $O --method $D.Reload
gdbus call --session --dest $D --object-path $O --method $D.TestMapping 0
gdbus monitor --session --dest $D      # KeyPressed / ConfigReloaded / DeviceChanged

• GetStatus → (version, running, device, configPath).
• Reload re-reads the mappings file; ConfigReloaded(ok) reports the result.
• TestMapping fires a mapping without touching the keyboard (useful to check a sequence). The index is 0-based: 0 = G1 … 8 = G9. It runs the same code path as a real keypress.
• KeyPressed(index, action) is emitted for every G key, real or tested.

If no session bus is available the daemon still works — it just runs without the GUI channel and logs that.

Install (optional)

sudo make install

Installs, under PREFIX (default /usr/local):

Path	What
bin/gkeymapper, bin/gkeymapper-daemon	the GUI and the daemon
share/locale/*/LC_MESSAGES/gkeymapper.mo	translations
share/gkeymapper/assets/, share/applications/, share/icons/	icon, .desktop file, icons
lib/udev/rules.d/60-gkeymapper.rules	lets your user reach the keyboard and /dev/uinput
lib/modules-load.d/gkeymapper.conf	loads the uinput module at boot
lib/systemd/user/gkeymapper-daemon.service	systemd user unit (binary path filled in from PREFIX)
share/dbus-1/services/dev.rager.gkeymapper.Daemon.service	D-Bus activation: the GUI can start the daemon on demand

Then enable the daemon for your session — it then starts automatically at login:

systemctl --user daemon-reload
systemctl --user enable --now gkeymapper-daemon
systemctl --user status gkeymapper-daemon

Enabling it is optional: the D-Bus activation file above lets the bus start the daemon as soon as the GUI asks for its status. With both in place the unit is used either way, so the daemon never runs twice.

It is a user service on purpose: it needs your session for /dev/uinput and so that a command action inherits DISPLAY/WAYLAND_DISPLAY. The unit does not run as root. make install reloads the udev rules for you; on a fresh machine replug the keyboard (or reboot) once so the ACL applies.

After installation

If the daemon is not running (the GUI footer says "Daemon: not reachable"):

systemctl --user daemon-reload
systemctl --user enable --now gkeymapper-daemon

The daemon needs the user's session for /dev/uinput and for the DISPLAY a command action inherits, so it runs as a user service, not a system service. If the commands above fail, check that your user session has systemd running (systemctl --user status).

Clean

make clean

Removes the binaries and the generated locale/ and build/ directories.

Capturing key sequences

For rows of type Key, the action button opens a capture dialog:

• Press keys one after another; each press becomes one step.
• Modifier keys (Ctrl, Alt, Shift, Super) held during a press are recorded as part of that step.
• Each step stores the base key (the unshifted key), so Shift+ß is recorded as shift+ssharp and not as the shifted symbol question.
• AltGr (level 3) is recorded as the altgr modifier plus the base key, so AltGr+7 becomes altgr+7.
• The live preview shows the sequence. Clear resets it, Done writes it into the row, Cancel discards it.

The sequence uses the same format as g910-gkey-macro-support: modifiers are joined with +, steps are separated with , (e.g. ctrl+c,ctrl+v or shift+f4,super+t). The modifier order is ctrl, alt, shift, super, altgr; parsing accepts any order.

Configuration format

Save mappings writes ~/.config/gKeyMapper/mappings.conf:

# gKeyMapper mappings (G1..G9)
G1=key:ctrl+c,ctrl+v
G2=command:/usr/bin/firefox
G3=disabled:
G4=keyhold:ctrl+w

The same format is used by Export/Import. key holds a captured shortcut sequence and fires it once, command a program path or command line, disabled ignores the G key, and keyhold keeps a single shortcut pressed for as long as the G key is held (in the GUI it is the Key (hold) entry in the Type dropdown). These map to the shortcut / run / nothing hotkey types of the reference project; the native C++ daemon (gkeymapper-daemon) reads this file and replays the actions — no Python involved.

Save mappings writes atomically (temporary file + rename), so the daemon never sees a half-written file and the watch reloads exactly once per save.

Project structure

src/main.cpp           # app actions + GUI + daemon status footer
src/keyrow.h           # KeyRow (one per G key)
src/mappings.{h,cpp}   # GUI glue: config file <-> row widgets
src/capturedialog.{h,cpp} # key-capture dialog
src/daemonclient.{h,cpp}  # D-Bus client for the daemon (status/reload)
src/singleinstance.{h,cpp} # one GUI only: a new start replaces a running one,
                          # taking the rows of its window along (unsaved edits)
src/trayicon.{h,cpp}   # tray icon: StatusNotifierItem + dbusmenu over GIO
src/settings.{h,cpp}   # gui.conf (window preferences, e.g. minimize to tray)
src/help.{h,cpp}       # help window
src/optionsdialog.{h,cpp} # options window: switches + detailed daemon status
shared/mapping.{h,cpp} # mappings format + shortcut parsing (GUI & daemon)
shared/keys.{h,cpp}    # canonical key names -> Linux key codes
shared/keymap.{h,cpp}  # layout-aware key lookups (xkbcommon), GUI + daemon
shared/ipc_ids.h       # app id + D-Bus names shared by GUI and daemon
daemon/main.cpp        # event loop: read G-keys, run the action
daemon/device_tables.{h,cpp}  # per-model raw HID report tables (G910)
daemon/g910_device.{h,cpp}    # libusb access to the vendor interface
daemon/uinput_keyboard.{h,cpp}# virtual keyboard for "key" mappings
daemon/action.{h,cpp}  # dispatch "key" / "command" / "disabled" / "keyhold"
daemon/config_watch.{h,cpp}   # inotify watch on mappings.conf (auto-reload)
daemon/ipc_dbus.{h,cpp}       # D-Bus service (status/reload/test/signals)
data/60-gkeymapper.rules      # udev rule (uaccess for device + /dev/uinput)
data/gkeymapper-uinput.conf   # modules-load.d fragment for uinput
data/gkeymapper-daemon.service# systemd user unit (installed by make install)
data/dev.rager.gkeymapper.Daemon.service # D-Bus activation (session bus)
docs/daemon-plan.md    # daemon plan (reference: g910-gkey-macro-support)
po/                    # Translations (pot/po/mo targets, po/README.md)
scripts/i18n.sh        # extract/update/check/status/todo/new for the catalogs
Makefile               # Build via pkg-config + gettext
.vscode/tasks.json     # VS Code tasks for make
README.md

Troubleshooting

Package gtk4 was not found

The GTK 4 development files are missing. Install them:

sudo apt install -y libgtk-4-dev

Then verify:

pkg-config --modversion gtk4

pkg-config cannot find .pc files (wrong search path)

In some environments PKG_CONFIG_PATH must be set explicitly. Standard path on Ubuntu/Mint:

export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/share/pkgconfig:/usr/lib/pkgconfig

Planned next steps

• The M1–M3 / MR keys of the G910 and profiles: swap mapping sets on the fly, which is what the reserved SetProfile D-Bus method was meant for. Deliberately left for later (see docs/daemon-plan.md §11).
• Key sequence timing: per-step delays for recorded macros.
• typeout: type out a fixed text, like the reference project's action of that name — not decided yet (see §11).

Not planned

• Remapping the media keys. The daemon forwards mute / volume / play / next / previous / stop unchanged, and that is meant to stay that way (see the note above): they are not G keys, so they get no rows in the GUI and no entry in the config file.