386 lines
20 KiB
Markdown
386 lines
20 KiB
Markdown
# gKeyMapper daemon — implementation plan
|
||
|
||
Status: draft / proposal
|
||
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.
|
||
- **Next: M4 (D-Bus GUI channel)** — status, explicit `Reload`, `TestMapping`
|
||
and signals. The reload side of it is already covered by the M3 file watch.
|
||
|
||
## 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: <https://github.com/JSubelj/g910-gkey-macro-support>
|
||
|
||
- 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
|
||
`<linux/uinput.h>` / `<linux/input-event-codes.h>` — 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<n>=<type>:<target>` 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=…`, `ExecStart=gkeymapper-daemon`,
|
||
`Restart=on-failure`, `Documentation=…`. `BusName` enables D-Bus activation,
|
||
so starting the GUI can start the daemon on demand.
|
||
- 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 Proposed D-Bus interface
|
||
|
||
- Bus name: `<app-id>` — decide once (§11). Suggested: `dev.rager.gkeymapper`
|
||
(replace the current placeholder `com.example.gkeymapper`).
|
||
- 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). |
|
||
| `GetStatus` | `() -> (s version, b running, s device, s configPath)` | Status for the GUI footer/indicator. |
|
||
| `TestMapping` | `(u index) -> ()` | Fire mapping for G1..G9 without hardware (GUI "Test" button). |
|
||
| `SetProfile` | `(s profile) -> ()` | Reserved for M-key profiles (later). |
|
||
|
||
Signals
|
||
| Signal | Signature | Purpose |
|
||
|---|---|---|
|
||
| `KeyPressed` | `(u index, s action)` | A G-key fired (for GUI highlight/history). |
|
||
| `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.
|
||
- `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.
|
||
|
||
### 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 (small)
|
||
- On "Save mappings": keep writing the file, then call `Reload()` (ignore error).
|
||
- Add a footer status line: daemon running / device present / last reload, fed by
|
||
`GetStatus` + the `DeviceChanged`/`ConfigReloaded` signals.
|
||
- Optional "Test" button per row → `TestMapping(index)`.
|
||
- The key-name vocabulary must match: the capture dialog already writes
|
||
lowercase GDK key names; move the canonical name list into the shared module
|
||
(§6) so GUI and daemon agree on the same spellings.
|
||
|
||
## 6. Code layout
|
||
|
||
```
|
||
src/ # GUI (existing)
|
||
daemon/ # as implemented (see the list in §6 above)
|
||
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)
|
||
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)
|
||
po/ # shared catalogs (GUI strings)
|
||
```
|
||
|
||
Build: the Makefile gets a second target `gkeymapper-daemon` and install rules
|
||
for the unit, udev rule and modules-load fragment. New build dependency:
|
||
`libusb-1.0-0-dev` (GLib/GIO is already required by the GUI).
|
||
|
||
## 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.
|
||
|
||
## 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.** GDBus service (`Reload`, `GetStatus`, `TestMapping`, signals);
|
||
GUI status line + Reload-on-save + optional Test button.
|
||
- **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.
|
||
- 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.
|
||
|
||
## 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
|
||
|
||
- **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).** `SIGHUP` re-reads the config file
|
||
(the full D-Bus `Reload` comes with M4).
|
||
- **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).** A systemd **user** unit (not a system service): the
|
||
daemon needs the session for `/dev/uinput` and for the `DISPLAY` a `command`
|
||
action inherits. It is `Type=simple` for now; it becomes `Type=dbus` with a
|
||
`BusName` once M4 adds the D-Bus service. 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).
|