Files
nixos-setup/pkgs/niri-touchscreen-gestures/README.md
T
2026-07-28 16:21:57 -04:00

196 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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."<app-id>"]` 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:
- `"<N>-finger-<direction>"` — swipe, `direction` = `up`/`down`/`left`/`right`
- `"1-finger-tap"` / `"1-finger-double-tap"` / `"1-finger-long-tap"` — tap gestures
- `"<N>-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."<app-id>"]` 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.