451 lines
20 KiB
Markdown
451 lines
20 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
cd /home/trager/Nextcloud/Projekte/C++/gKeyMapper
|
||
```
|
||
|
||
(Alternatively clone the repository or copy the project folder to your own location.)
|
||
|
||
## Build
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
make translations
|
||
```
|
||
|
||
Adding or changing a translation, adding a language, and the checks around them
|
||
are described in [po/README.md](po/README.md). `scripts/i18n.sh` does the work and
|
||
is wired into the Makefile:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
./gkeymapper
|
||
```
|
||
|
||
With explicit language files (useful for testing from the build directory):
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
./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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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"):
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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](https://github.com/JSubelj/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:
|
||
|
||
```bash
|
||
sudo apt install -y libgtk-4-dev
|
||
```
|
||
|
||
Then verify:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|