# gKeyMapper daemon — implementation plan Status: implemented (M0–M4 done, see "Implementation status") Scope: a native C/C++ background service that detects G1–G9 (and later M1–M3/MR and media keys) on the Logitech G910 and replays the mappings stored by the GUI. ## Implementation status - **M0 done** — `shared/mapping.{h,cpp}` (file format + shortcut parsing) and `shared/keys.{h,cpp}` (canonical names → Linux codes); the GUI uses them. Round-trip and shortcut parsing are covered by a small standalone test. - **M1 done** — `daemon/` builds (`gkeymapper-daemon`): device discovery, kernel-driver detach, F-key binding disable, 64-byte interrupt reads and G1–G9 decoding. Verified on hardware: all nine keys decode correctly (press and release), in order. - **M2 done** — action execution: `key` shortcuts are replayed through a `/dev/uinput` virtual keyboard, `command` runs via fork/exec (with a shell fallback so arguments work), `disabled` does nothing. Verified on hardware. - **M3 done** — config watching and lifecycle: `daemon/config_watch` watches the config *directory* with inotify, so a save in the GUI reloads within about half a second; `SIGHUP`/`SIGUSR1` stay as the fallback. `Save mappings` now writes atomically (temp file + `rename`), so the daemon never reads a half-written file. `make install` ships the udev rule, the `modules-load.d` fragment and the systemd **user** unit (`data/`). - **Layout handling (added during M2)** — key names are resolved through the active layout (`XKBLAYOUT` from `/etc/default/keyboard`, via xkbcommon). This matters because the US-position code `KEY_Z` (44) is `y` on a German keyboard; `z` is now correctly resolved to evdev 21. - **AltGr (added after M2)** — level-3 combinations are representable as `altgr+7`; the base (level 0) key is stored plus the `altgr` modifier. - **M4 done** — D-Bus control channel: `daemon/ipc_dbus` registers `dev.rager.gkeymapper.Daemon` on the session bus and serves `Reload`, `GetStatus` and `TestMapping`, plus the `KeyPressed`, `ConfigReloaded` and `DeviceChanged` signals. `src/daemonclient.{h,cpp}` is the GUI side: the footer shows `Daemon: running/not reachable`, the device and the last G key that fired, and `Save mappings` calls `Reload()` (the file watch stays the backstop). `make install` ships a D-Bus activation file, so the GUI can start the daemon on demand; the unit is `Type=dbus` with `BusName=`. A second instance refuses to start instead of fighting over the keyboard. Verified with `gdbus` (methods, signals, activation) and over AT-SPI (live footer). ## 1. Goals and non-goals Goals - Detect G-key presses in C/C++ and execute the configured action. - Run with a very small, stable resource footprint (idle ≈ 0 % CPU, few MB RSS, no interpreter, no polling when nothing happens). - Reuse the existing `mappings.conf` format as the single source of truth. - Let the GUI and the daemon run independently; either can start first. - No Python at runtime. Non-goals (v1) - Profiles (M1–M3/MR), per-locale text typing (`typeout`), embedded scripting. - GUI redesign beyond a status indicator / reload / test button. ## 2. What the Python reference does (and what we keep) Reference: - G-keys are **not** exposed as distinct evdev key codes. The driver therefore opens the keyboard's **vendor HID interface (USB interface 1) directly via libusb**, detaches the kernel driver from that interface, and reads raw interrupt-IN reports. - On start it sends a control transfer to **disable the firmware F-key→G-key binding**, so pressing G1..G9 no longer also emits F1..F9 on the normal keyboard interface. - Raw report byte patterns are looked up in tables (`events.macroKeys`, `memoryKeys`, `mediaKeys`, `releaseEvents`) and turned into actions. - A **uinput virtual keyboard** replays `shortcut` (press, later release), `typeout` (per-char), `uinput` (direct `KEY_*`); `run` uses `/bin/bash -c`. - Config is JSON at `~/.config/g910-gkeys/config.json`, reloaded on directory change (inotify via `fcntl`), plus `SIGUSR1` reload. - Ship: a **systemd --user** service and **udev rules** with `TAG+="uaccess"` for the device and `/dev/uinput`, so no root is needed. Relevant USB IDs (from the udev rules): `046d:c335`, `c33f`, `c33e`, `c32b`, `c24d`, `c22d`. The G910 in this project is `046d:c32b`. What we keep: libusb raw HID access, disabling the F-key binding, uinput output, config-dir watching. What we change: JSON→our line format, single-threaded event-driven loop instead of a Python loop with fixed sleeps, fork/exec reaping, and a real IPC channel to the GUI. ## 3. Architecture overview ``` +---------------------+ mappings.conf (shared truth) +----------------------+ | gkeymapper (GUI) | <------------ write / inotify ---------> | gkeymapper-daemon | | GTK4 + GIO/GDBus | | libusb + uinput | | | <===== D-Bus (session bus) ============> | GDBus + inotify | +---------------------+ status / reload / events +----------+-----------+ | raw HID (iface 1) v +----------------------+ | Logitech G910 | +----------+-----------+ | uinput v +----------------------+ | /dev/uinput keyboard | +----------------------+ ``` Key property: the **hot path never crosses IPC**. G-key press → decode → uinput happens entirely inside the daemon. IPC (D-Bus) is only used for control, status and notifications, so a slow/absent GUI never delays a keypress. ## 4. Daemon design ### 4.1 Process model - One process, single-threaded, event loop. - No threads in v1. `run`/`command` actions are launched with `fork()` + `execve()`; children are reaped via a `SIGCHLD`/`signalfd` handler so no zombies accumulate (the reference leaks a `Popen` per invocation). - `python` type is intentionally dropped. ### 4.2 Event loop Use one `poll()`/`epoll()` loop over: - the **libusb** file descriptor (from `libusb_get_pollfds()`; use libusb's async API or `libusb_interrupt_transfer` on a worker, see below), - an **inotify** fd for the config file/directory, - a **signalfd** for `SIGTERM`/`SIGINT`/`SIGUSR1`, - the **D-Bus** connection (GDBus integrates with the same `GMainContext`). Preferred: drive libusb asynchronously with `libusb_submit_transfer()` and fold the reported poll fds into the same loop (libusb has an official "poll with another event loop" pattern). That yields exactly **0 wakeups while idle** (excluding the kernel's own HID interrupts). If that is too much work for v1, fall back to a blocking `libusb_interrupt_transfer(..., timeout=1000)` inside a dedicated thread that posts events into the main loop — still cheap (1 wake/s). To keep GDBus and the fd loop together, the loop is easiest on the **GLib main loop** (`GMainLoop`): GDBus, `GFileMonitor` and `GSocket`/`GSource` cover inotify and signalfd, and libusb poll fds can be wrapped in a custom `GSource`. GLib is already a dependency of the GUI, so this adds no new library. If minimal footprint is the priority over convenience, a raw `epoll` loop is the alternative; decision point in §11. ### 4.3 Device layer (`libusb`) - Find the device by vendor/product from the supported-device table; pick interface 1, endpoint from the same table. - `libusb_detach_kernel_driver()` on interface 1; remember to `libusb_attach_kernel_driver()` on shutdown (reference does this). - Send the "disable F-key to G-key binding" control transfer (`bmRequestType=0x21, bRequest=0x09, wValue=0x0212, wIndex=1`) and consume the confirmation reports; ignore the known LED-return patterns (`\x11\xff\x0f`, `\x11\xff\x10`, `\x11\xff\xff`). - Hot-plug / re-plug: on `LIBUSB_ERROR_NO_DEVICE`/`IO` re-run discovery with a small backoff (reference re-inits in place). - Optional (later): `libusb_hotplug_register_callback` to react to device add/remove without polling. The device table in `supported_devices.py` (byte patterns per model) is ported to a generated C++ header (`constexpr` tables) — keep it a build-time artifact so the runtime does zero parsing. ### 4.4 Decoding - The report is a fixed-length byte blob. Build a **compile-time lookup**: a sorted array of `{report bytes, action id}` with binary search, or a small open-addressed hash keyed on the first 8 bytes. This replaces the Python `dict` + `list(...).index()` O(n) scans with O(1)/O(log n) and no allocation. - Categories: `macro` (G1..G9), `memory` (profiles, later), `media` (later), `release` (stops a held shortcut), and ignored/known-noise. ### 4.5 Action layer (uinput) - Open `/dev/uinput` once; `UI_SET_EVBIT` for `EV_KEY`, register the key set used by the mappings, `UI_DEV_CREATE`. Keep the fd for the daemon's lifetime. - Emit events by `write()`-ing `struct input_event` (from `` / `` — no libevdev needed). - `key` mapping = shortcut grammar `ctrl+c,ctrl+v`: - single combo: press modifiers+key in order, remember the keys, release them when the keyboard's `release` event arrives (mirror the reference's `press_release_fifo` stack). - comma list: `emit_combo()` each group (press+release). - `command` mapping: `fork()`; in the child `setsid()`, redirect stdio to `/dev/null`, `execve("/bin/sh", "-c", cmd)`. Reap via `SIGCHLD`. - `disabled`: no-op. - Give the uinput device a clear name/IDs (e.g. `gkeymapper virtual keyboard`) so `libinput`/users can identify it. ### 4.6 Config - Parse the existing `mappings.conf`: `G=:` with `type ∈ {key, command, disabled}`. - Parse at load and on change only; the runtime holds a small pre-parsed action per G-key (enum + fixed target buffer / `std::string`), so no parsing in the hot path. - Watch the config file (and, for atomic-save editors, its directory) with inotify/`GFileMonitor`; reload on `IN_CLOSE_WRITE`/`IN_MOVED_TO`. Debounce (e.g. 100 ms) to coalesce editor save bursts. - Also reload on `SIGUSR1` (manual/test) and on `Reload()` D-Bus call. ### 4.7 Privileges and packaging - udev rule with `TAG+="uaccess"` for the supported USB IDs and for `KERNEL=="uinput"` (mirrors the reference's `60-g910-gkeys.rules`). - `uinput` kernel module must be present; ship `/etc/modules-load.d/` fragment or document `modprobe uinput` (here it is built in). - **systemd --user** unit `gkeymapper-daemon.service`: `Type=dbus`, `BusName=dev.rager.gkeymapper.Daemon`, `ExecStart=gkeymapper-daemon`, `Restart=on-failure`, `ExecReload=SIGHUP`. `Type=dbus` + `BusName` make the unit count as started only once the name is owned — the state D-Bus activation and the GUI see. `make install` also ships the D-Bus activation file (`share/dbus-1/services/dev.rager.gkeymapper.Daemon.service`, with `SystemdService=gkeymapper-daemon.service`), so the bus starts the unit when the GUI asks for the daemon's status and the daemon runs exactly once either way. - Do **not** require root. Commands run with the user's privileges (the reference's "executed as root" note is a wiki artifact, not a design goal). ## 5. GUI ↔ daemon interaction Three layers, from loosest to tightest: 1. **Shared state = the config file** (`~/.config/gKeyMapper/mappings.conf`). The GUI is the writer, the daemon is a watcher/reader. This alone is enough for basic operation and is robust: whichever side starts first, the other converges. The daemon reloads via inotify; no coupling to the GUI process. 2. **Control/status = D-Bus on the session bus** (GDBus; part of GIO, already linked by the GUI). Used for status, explicit reload, and notifications. 3. **Lifecycle**: the daemon is a `systemd --user` service; the GUI can start it implicitly by calling a D-Bus method (activation) and can show whether it is running. ### 5.1 D-Bus interface (implemented) - App id: `dev.rager.gkeymapper` (replaces the placeholder `com.example.gkeymapper`); it is also the GApplication id. - Bus name: `dev.rager.gkeymapper.Daemon` — **not** the plain app id. `GtkApplication` owns the app id itself, in order to detect a second GUI instance; a daemon on the same name would make every GUI start look like a duplicate and exit. (The original plan had `` here; that clash was found while implementing M4.) - Object path: `/dev/rager/gkeymapper/Daemon` - Interface: `dev.rager.gkeymapper.Daemon` Methods | Method | Signature | Purpose | |---|---|---| | `Reload` | `() -> ()` | Re-read `mappings.conf` now (GUI "Save" also calls this). Result via the `ConfigReloaded` signal. | | `GetStatus` | `() -> (s version, b running, s device, s configPath)` | Status for the GUI footer/indicator. `device` is `""` before the keyboard is open, so the GUI can omit that part. | | `TestMapping` | `(u index) -> ()` | Fire the mapping of one G key without hardware; same code path as a real press. `index` is **0-based** (`0` = G1 … `8` = G9). Fails with a D-Bus error for an out-of-range index or a `disabled:`/empty row. | Signals | Signal | Signature | Purpose | |---|---|---| | `KeyPressed` | `(u index, s action)` | A G-key fired (GUI highlight/history; also emitted by `TestMapping`). | | `ConfigReloaded` | `(b ok)` | Daemon finished reloading. | | `DeviceChanged` | `(b present, s device)` | Keyboard attached/detached. | Notes - All are control-plane calls; none is on the keypress path. `DaemonService::pump()` dispatches once per daemon loop iteration, so a reply can take up to one read timeout (≤500 ms) — fine for status/reload, and the GUI calls asynchronously. - `Reload` is best-effort: inotify is the backstop if the call is lost. - If D-Bus is unavailable, the daemon still works; the GUI degrades to "no status" and "save only". Signals `SIGUSR1` (reload) / `SIGTERM` remain for scripted use, matching the reference. - `SetProfile` was dropped: it is reserved for the M-key profiles and would have been a no-op today. - The daemon requests its name with `DO_NOT_QUEUE` and exits (code 0, with a message) when another instance owns it, before it touches the device. ### 5.2 Interaction sequences Save in the GUI: ``` GUI: write mappings.conf (atomic: temp + rename) GUI: call Daemon.Reload() [optional, for immediacy] Daemon: inotify IN_MOVED_TO -> (re)parse -> apply Daemon: emit ConfigReloaded(ok) ``` Key press: ``` G910 --raw HID--> Daemon -> decode -> uinput emit / fork+exec Daemon: emit KeyPressed(index, action) [GUI only, non-blocking] ``` Start-up orders: - Daemon first, GUI later: GUI reads status via D-Bus; no config write needed. - GUI first, daemon later: GUI writes config; on daemon start it reads the file. ### 5.3 GUI-side changes (as implemented) - On "Save mappings": writes the file, then calls `Reload()` best-effort; the file watch is the backstop, so a lost call is harmless (a save therefore triggers two reloads, both idempotent). - Footer status line: `Daemon: running/not reachable` + `Device: …` + the last G key that fired, fed by `GetStatus`, the `DeviceChanged`/`ConfigReloaded` signals and `NameOwnerChanged` (so it follows the daemon starting/stopping). The `Device:` part is omitted while the device is not open yet. - No "Test" button per row: pressing the real key is the better test while the hardware is at hand, and `TestMapping` stays available over `gdbus`/`busctl` without widening the fixed-width rows. - The key-name vocabulary matches because the capture dialog already writes lowercase GDK key names and the canonical list lives in `shared/keys` (§6). ## 6. Code layout ``` src/ # GUI (existing) daemonclient.{h,cpp} # D-Bus client (status/reload/signals) daemon/ # as implemented (see §6 above) ipc_dbus.{h,cpp} # GDBus service (control plane) shared/ mapping.{h,cpp} # parse/format mappings.conf (used by GUI and daemon) keys.{h,cpp} # canonical names <-> gdk keyval <-> linux KEY_* keymap.{h,cpp} # layout-aware name <-> input code (xkbcommon) ipc_ids.h # app id, version, D-Bus names data/ 60-gkeymapper.rules # udev: uaccess for the device and /dev/uinput gkeymapper-uinput.conf # modules-load.d fragment (uinput) gkeymapper-daemon.service # systemd user unit (@BINDIR@ filled in on install) dev.rager.gkeymapper.Daemon.service # D-Bus activation for the same unit icons.gresource.xml # GUI icons compiled into the binary (GResource) po/ # shared catalogs (GUI strings) ``` Build: the Makefile gets a second target `gkeymapper-daemon` and install rules for the unit, udev rule, modules-load fragment and activation file. New build dependency: `libusb-1.0-0-dev` plus `libglib2.0-dev` (gio-2.0) for the daemon's D-Bus channel. ## 7. Resource-efficiency measures (summary) - No Python interpreter; native binary, tables in `.rodata`. - Event-driven loop, **no idle polling** (libusb async + inotify + signalfd; or a 1 s blocking USB read in the simple variant). - O(1)/O(log n) decode via compile-time tables instead of dict/linear scan. - One `uinput` fd for the process lifetime; fixed-size event writes; no per-event heap allocation. - Config parsed only on load/reload; hot path is table lookups + `write()`. - `fork`+`exec` for programs, children reaped (no zombies), stdio to `/dev/null`; no shell parsing for `key`/`uinput` actions. - Target footprint: idle 0 % CPU, wakeups only on real HID/DBus/file events, RSS in the low single-digit MB. Measured after M4 (systemd user unit, daemon idle): ~780 KB RSS, 14 ms CPU since start. The D-Bus control channel adds no wakeups of its own: `pump()` only dispatches what the loop's read timeout already woke up for. ## 8. Milestones - **M0 – Shared core.** `shared/mapping` + `shared/keys`; refactor the GUI to use them (still file-only). Unit tests for parse/format and key tables. - **M1 – Device bring-up.** `daemon` opens the G910 via libusb, disables the F-key binding, logs `G1..G9` presses. No output yet. - **M2 – Action layer.** uinput keyboard; `key` (shortcut, incl. release) and `command` work end-to-end. `disabled` no-op. - **M3 – Config & lifecycle (done).** config reload via inotify (`config_watch`, directory watch + atomic save) and `SIGHUP`/`SIGUSR1`; systemd --user unit + udev rule + modules-load, installed by `make install`. - **M4 – IPC (done).** GDBus service (`Reload`, `GetStatus`, `TestMapping`, signals); GUI status line + Reload-on-save; D-Bus activation file; unit `Type=dbus` + `BusName`; single-instance guard. - **M5 – Polish.** Packaging/install rules, docs, translations, hardening (hot-plug, debounce, error reporting to the GUI). ## 9. Testing strategy - Unit: mapping parser round-trip, key-name tables, decoder against recorded byte sequences from the reference tables. - Device: replay captured reports into the decoder (no hardware needed). - Integration: `evtest` / `libinput debug-events` to observe the virtual device; compare `xev` output for a configured shortcut between reference and daemon. - D-Bus (M4): `gdbus call` for `GetStatus`/`Reload`/`TestMapping`, `gdbus monitor` for the signals, and a `TestMapping` observed with `xinput test ` to confirm the emitted keycodes. The GUI's footer line is read back over AT-SPI to check the live status. - Permission tests: verify the udev rule grants access as a normal user. - Resource check: `powertop`/`perf` or simple wakeup counting while idle. ## 10. Risks / open points - **Device table size**: `supported_devices.py` is large; porting/generating the byte tables is real work and model-specific. - **Interface detach** may momentarily disturb the device; must re-attach on exit and handle crashes gracefully. - **Permissions**: relies on `TAG+="uaccess"` + a user service; must never fall back to requiring root silently. - **`command` environment**: `DISPLAY`/`WAYLAND_DISPLAY`/`XAUTHORITY` and `PATH` differ between a user service and an interactive shell; decide whether to inherit the user manager environment (`systemd --user` import-environment) or document `run` snippets setting `DISPLAY=:0` explicitly. - **Key-name vocabulary drift** between GUI (GDK names) and daemon (Linux KEY_*) is the most likely source of silent mismatches — that is why the shared table in M0 is mandatory before the daemon consumes the file. - **uinput device identity**: a second keyboard appears; choose stable name/vendor/product so the desktop does not confuse it with the real one. - **GUI does not load the config at startup** (found while testing M4, GUI-side, not a daemon issue): `build_ui()` fills the rows empty and only `Import configuration...` reads the file, so pressing `Save mappings` in a freshly opened window overwrites the user's mappings with empty ones. Loading `~/.config/gKeyMapper/mappings.conf` on start (or refusing to save unchanged rows) should be the next GUI fix. ## 11. Decisions to make 1. Bus name / app-id: replace `com.example.gkeymapper` with a real reverse-DNS id (suggested `dev.rager.gkeymapper`)? Affects the `.desktop` name too. 2. Event loop: GLib `GMainLoop` (simplest, reuses GIO) vs. raw `epoll` (leanest). 3. IPC: D-Bus (idiomatic, GIO already present) vs. a Unix socket (no bus dependency). Recommendation: D-Bus, with signals as a fallback. 4. Scope of v1: keep `key`/`command`/`disabled` only, or also port `typeout`/`media`? ### Resolved - **Bus name / app id (done in M4).** App id (and GApplication id) `dev.rager.gkeymapper`; the daemon uses `dev.rager.gkeymapper.Daemon` because GtkApplication owns the plain app id to detect a second GUI instance. The installed `.desktop` file keeps its name `gkeymapper.desktop` — both old and new app id yield the X11 `WM_CLASS` `gkeymapper`, which is what `StartupWMClass` matches (verified with `xprop`). - **IPC (done in M4).** D-Bus with GDBus: libdbus and sd-bus dev files are not installed on this machine, GIO is; the daemon links `gio-2.0`. - **IPC event integration (done in M4).** The daemon keeps its simple blocking loop instead of moving to a `GMainLoop`: `DaemonService::pump()` calls `g_main_context_iteration(ctx, FALSE)` once per iteration, so D-Bus is serviced without a thread and without blocking, at the cost of up to one read timeout of latency on the control plane. - **Status line widget (evaluated).** The daemon status stays a plain `GtkLabel` in the window footer. `GtkStatusbar` does exist in GTK4 and is themed, but it keeps a message stack (pop/push per context id) and GTK4 exposes it over AT-SPI as a generic `filler`, not as a "statusbar" role — so it was built, compared side by side and dropped. - **Event loop (as implemented, deviates from §4.2).** The daemon is single-threaded with a blocking `libusb_interrupt_transfer` and a 500 ms timeout; the config watch is drained once per iteration. That is ~2 idle wakeups/s at 0 % CPU (the "simple variant" of §4.2) rather than the preferred async libusb + GMainLoop design. Switching to libusb's async API with its poll fds in a `poll()` loop stays open if idle wakeups ever become a concern — the config watch would fold into the same set. - **Layout handling (done in M2).** Key names in the file are layout independent; the daemon resolves them through the active layout (`XKBLAYOUT` from `/etc/default/keyboard`, via xkbcommon) and only falls back to the US positions from `shared/keys`. This closes the vocabulary-drift risk for non-US layouts — a German `z` is evdev 21, not the US position 44. - **Reload without restart (done in M2, completed in M4).** `SIGHUP`/`SIGUSR1` re-read the config file; since M4 the GUI's `Save mappings` also calls the D-Bus `Reload`, and the inotify watch applies anything else. - **Config watching (done in M3).** The daemon watches the config **directory** with inotify rather than the file, so an atomic save (temp file + `rename`) and a recreated file are caught too. The loop iteration (≤ 500 ms) is the coalescing window, so one save yields exactly one reload; `SIGHUP`/`SIGUSR1` stay as the fallback and there is no extra fd in the loop. `Save mappings` in the GUI now writes atomically, so the daemon can never read a partial file. A failed reload keeps the previous mappings instead of disabling every key. - **Lifecycle (done in M3, extended in M4).** A systemd **user** unit (not a system service): the daemon needs the session for `/dev/uinput` and for the `DISPLAY` a `command` action inherits. Since M4 it is `Type=dbus` with `BusName=dev.rager.gkeymapper.Daemon`, and a D-Bus activation file lets the bus start it on demand, so enabling the unit is optional. The udev rule and the `modules-load.d` fragment live in `data/` and are installed by `make install` (under `PREFIX/lib/...`, which udev and systemd both search). - **Single instance (done in M4).** The daemon requests its bus name with `DO_NOT_QUEUE` and exits with a message when it is already taken — two instances would detach the kernel driver from each other and create two virtual keyboards. The check happens before the device is opened.