# niri-touchscreen-gestures A lightweight Python daemon that reads multi-touch events from a touchscreen via [`evdev`](https://python-evdev.readthedocs.io/), detects **swipe/tap gestures**, and either dispatches an action to the [niri](https://github.com/YaLTeR/niri) Wayland compositor or **forwards synthetic input (click/scroll) to whatever window currently has focus**. **Now with built-in defaults** — just run `niri-touchscreen-gestures` with no arguments to get started with sensible 3- and 4-finger gesture mappings. It works by: - Listening to absolute multi-touch (MT) events from an evdev touchscreen device - Tracking finger start/end positions, timing, and movement vectors - Classifying swipes (up/down/left/right), taps, double-taps, long-taps, and continuous 2-finger scroll drags - Looking up the gesture in a TOML config, scoped by the currently-focused app (queried over niri's IPC socket), and either sending an `Action` command to niri or forwarding synthetic input via [`wlrctl`](https://git.sr.ht/~brocellous/wlrctl) (niri implements the `wlr-virtual-pointer-unstable-v1`/`virtual-keyboard-unstable-v1` protocols natively, so no `ydotool`/`uinput`/root daemon is needed) ## Features - **Pure event-driven**: No polling, uses `evdev.InputDevice.read_loop()` - **Multi-finger support**: Automatically counts active fingers (2–4+) - **Tap gestures**: single tap, double tap, and long-press, forwarded as clicks - **Continuous scroll**: 2-finger vertical drags forward live scroll deltas, not just a one-shot action - **Per-app rules**: gestures can be scoped to whichever app currently has focus, with a global fallback - **Configurable mappings**: TOML file maps gestures like `3-finger-left` to niri actions or forwarded input - **Auto device detection**: Finds the first touchscreen (or accepts explicit `--device`) - **Robust state machine**: Pure functions for gesture classification with comprehensive tests - **Lightweight**: Minimal dependencies (`evdev`, `pydantic`, `pydantic-settings`, `wlrctl`) ## Installation This package is provided as a Nix derivation in this repository: ```nix # In your configuration environment.systemPackages = [ pkgs.niri-touchscreen-gestures ]; ``` Or build it directly: ```bash nix build .#niri-touchscreen-gestures ``` ### From PyPI (if published) ```bash pip install niri-touchscreen-gestures ``` Requires Python 3.10+ and the `input` group (for raw evdev access). ## Usage The simplest way to run it is with **no arguments** — it now uses sensible built-in defaults for 3- and 4-finger gestures: ```bash niri-touchscreen-gestures ``` You can still override the defaults: ```bash # Use a custom config niri-touchscreen-gestures --config ~/.config/niri/gestures.toml # Change swipe sensitivity niri-touchscreen-gestures --threshold 40 # Use a specific device (bypasses auto-detection) niri-touchscreen-gestures --device /dev/input/event5 # Pick which niri output the touchscreen maps to (only needed with >1 output connected) niri-touchscreen-gestures --touch-output eDP-1 ``` ### Command-line options - `--config PATH`: Path to TOML configuration file (optional — uses built-in defaults) - `--threshold N` (default: 60): Minimum pixels of movement to register a swipe - `--device /dev/input/eventX`: Explicit evdev device (bypasses auto-detection) - `--touch-output NAME`: Name of the niri output the touchscreen is mapped to (e.g. `eDP-1`, matching niri's `input { touch { map-to-output "..." } }` config). Forwarded clicks are placed at the tapped location by mapping the raw touch coordinate onto this output's logical geometry (queried from niri's `Outputs` IPC request). If omitted, the daemon auto-selects the sole enabled output — pass this explicitly once a second monitor is connected. The program must run with access to `/dev/input/event*` devices (typically via the `input` group) and with the `NIRI_SOCKET` environment variable set. ### Forwarded clicks click where you tapped Since `wlrctl pointer move` is relative-only (no absolute positioning, and no way to query the pointer's current position), a forwarded click warps the pointer to the tapped location before clicking: one large relative move clamps it to niri's logical origin `(0, 0)`, then a second move by the tap's mapped logical coordinate lands it exactly there. This assumes niri's default layout (some output at `(0, 0)`, outputs arranged contiguously) — an unusual multi-monitor arrangement with gaps could make this land in the wrong spot, but this isn't a concern on a single-display laptop. ## Configuration The tool ships with **sensible defaults** that match the example below. You only need to provide a config file if you want to customize the mappings. See [`example-config.toml`](example-config.toml): ```toml [global] "3-finger-up" = "FocusWorkspaceDown" "3-finger-down" = "FocusWorkspaceUp" "3-finger-left" = "FocusColumnRight" "3-finger-right" = "FocusColumnLeft" "4-finger-up" = "ToggleOverview" "4-finger-down" = "ToggleOverview" [apps."dev.zed.Zed"] "1-finger-tap" = "forward:click-left" "1-finger-double-tap" = "forward:click-right" "1-finger-long-tap" = "forward:click-right" "2-finger-scroll" = "forward:scroll" ``` The `[global]` table's mappings are the **built-in defaults**. `[apps.""]` tables add rules that only apply while that app has focus (matched by its Wayland `app_id`, as reported by niri's `FocusedWindow` IPC query) and take priority over `[global]` for the same key. Gesture keys: - `"-finger-"` — swipe, `direction` = `up`/`down`/`left`/`right` - `"1-finger-tap"` / `"1-finger-double-tap"` / `"1-finger-long-tap"` — tap gestures - `"-finger-scroll"` — continuous drag scroll (currently supported for `N = 2`) Action values: - A niri action name (see below, or [niri's config.rs](https://github.com/YaLTeR/niri/blob/main/src/niri/config.rs)) - `"forward:click-left"` / `"forward:click-right"` / `"forward:scroll"` — synthetic input forwarded to the focused window via `wlrctl` **Tip**: Place a custom config at `~/.config/niri/gestures.toml` and launch the daemon from a user systemd service or your niri startup script. ## Supported niri Actions Currently typed for these common actions (more can be added easily): - `FocusWorkspaceUp` - `FocusWorkspaceDown` - `FocusColumnLeft` - `FocusColumnRight` - `ToggleOverview` See [`nirictl.py`](niri_touchscreen_gestures/nirictl.py) for the list. ## How It Works 1. **Device Selection**: `touchscreen_identifier.py` scans `/dev/input` for devices with `EV_ABS` capabilities that aren't mice or touchpads. 2. **Event Loop**: Reads raw `EV_ABS` events (`ABS_MT_SLOT`, `ABS_MT_TRACKING_ID`, `ABS_MT_POSITION_X/Y`). 3. **State Tracking**: Maintains per-slot (per-finger) start/current coordinates and start time. 4. **Gesture Detection**: On finger lift (`TRACKING_ID == -1`), classifies a tap/long-tap (low movement) or a swipe (movement past threshold). A lone tap is held for a short debounce window (via a background timer) to see if a second tap follows and it becomes a double-tap. 2-finger vertical drags stream continuous scroll deltas on every position update, instead of waiting for lift. 5. **Focused-app resolution**: Queries niri's `FocusedWindow` IPC request (once per gesture, cached for its duration) and resolves the gesture key against `[apps.""]` first, falling back to `[global]`. 6. **Dispatch**: Niri actions are sent as JSON over niri's IPC socket; `forward:*` actions are sent to the focused window via `wlrctl pointer click/scroll`. All core logic is in `detector/gestures.py` and is unit-tested. ## Development ```bash # Enter dev shell (includes the package + test deps) nix develop # Run tests pytest # Run with example config NIRI_SOCKET=/run/user/$(id -u)/niri/socket \ niri-touchscreen-gestures --config example-config.toml ``` The project uses: - [`hatchling`](https://hatch.pypa.io/) for building - `pydantic` for config validation - Pure functions where possible for testability ## License MIT. See [LICENSE](LICENSE) (or the `default.nix` meta). ## See Also - [niri](https://github.com/YaLTeR/niri) — The scrollable-tiling Wayland compositor - [niri's IPC](https://github.com/YaLTeR/niri/blob/main/doc/ipc.md) — JSON socket protocol used - [evdev](https://www.freedesktop.org/software/libevdev/doc/latest/) — Linux input event interface --- **Part of [nixos-setup](https://github.com/skykanin/nixos-setup)** by Ari Sosnovsky.