From e2c46226f70a1bf607f3e3ae74b9ff05f8d5af11 Mon Sep 17 00:00:00 2001 From: Ari Sosnovsky Date: Sat, 11 Jul 2026 22:45:33 -0400 Subject: [PATCH] readme update + working niri-touchscreen-gestures --- README.md | 43 +++++ hosts/fwbook.nix | 12 +- pkgs/niri-touchscreen-gestures/.gitignore | 1 + pkgs/niri-touchscreen-gestures/README.md | 154 ++++++++++++++++-- pkgs/niri-touchscreen-gestures/default.nix | 3 +- .../niri_touchscreen_gestures/argparser.py | 22 ++- .../detector/gestures.py | 1 - pkgs/niri-touchscreen-gestures/pyproject.toml | 4 +- 8 files changed, 207 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index e8fc0f3..df474a2 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ nixos-setup/ ├── bin/ │ └── skyg # Main CLI tool for managing NixOS configurations ├── configs/ # Application-specific configurations +├── pkgs/ # Custom packages (niri-touchscreen-gestures, grok-cli, ds4) ├── hosts/ # Host-specific NixOS configurations │ ├── *.nix # Host configuration files (fwbook, hl-bigbox1, hl-minipc*, etc.) │ ├── *.hardware-configuration.nix # Hardware-specific configurations @@ -24,6 +25,34 @@ nixos-setup/ └── README.md # This file ``` +## Using This Flake + +To use the custom packages in your own NixOS/Home Manager configuration: + +```nix +{ + inputs.nixos-setup.url = "github:skykanin/nixos-setup"; + + outputs = { self, nixpkgs, nixos-setup, ... }: + let + system = "x86_64-linux"; + pkgs = nixos-setup.lib.pkgs.${system}; + in { + environment.systemPackages = with pkgs; [ + niri-touchscreen-gestures + grok-cli + ds4 + ]; + }; +} +``` + +You can also import `nixos-setup.lib` to reuse `makeNixOs`, `makeHomeManagerUsers`, and other utilities. + +See [`pkgs/ABOUTME.md`](pkgs/ABOUTME.md) for details on each package. + +**Key packages:** `niri-touchscreen-gestures` (run `niri-touchscreen-gestures` — uses built-in defaults), `grok-cli`, and `ds4` (local LLM inference with CPU/ROCm/CUDA support). + ## Quick Start The `skyg` script is your main interface for managing these configurations. It's located in `bin/skyg` and uses NuShell. @@ -94,6 +123,18 @@ skyg rollback skyg hm switch ``` +### Using Custom Packages + +All packages from `pkgs/` are available in your configuration as `pkgs.` thanks to the overlay. + +Example: + +```nix +environment.systemPackages = with pkgs; [ niri-touchscreen-gestures grok-cli ds4 ]; +``` + +See [`pkgs/ABOUTME.md`](pkgs/ABOUTME.md) for details on each package. + ## Managing Secrets Secrets are encrypted using [agenix](https://github.com/ryantm/agenix) and stored in `secrets/`. @@ -112,3 +153,5 @@ Available profiles include: - **Local**: `fwbook` (Framework laptop) - **Remote**: `hl-bigbox1`, `hl-bigbox2`, `hl-fwdesk`, `hl-fws1`, `hl-minipc1`, `hl-minipc2`, `hl-minipc3`, `hl-terra1` - **ISO**: `iso` (bootable image) + +All profiles automatically have access to the custom packages from the `pkgs/` directory. diff --git a/hosts/fwbook.nix b/hosts/fwbook.nix index ad616cf..c10ff43 100644 --- a/hosts/fwbook.nix +++ b/hosts/fwbook.nix @@ -121,6 +121,7 @@ in ); in (with pkgs; [ + # Improvement of Life grim slurp wl-clipboard @@ -132,6 +133,8 @@ in wl-screenrec ffmpeg gifski + libusb1 + lshw jq # Work @@ -143,14 +146,10 @@ in openfortivpn-webview-qt nodejs - # Util - libusb1 - - # wine + # Emulation wineWowPackages.stable winetricks wineWowPackages.waylandFull - lshw # Video recording & editing obs-studio @@ -231,6 +230,9 @@ in pi-coding-agent hermes-agent.packages.${pkgs.stdenv.hostPlatform.system}.desktop hermes-agent.packages.${pkgs.stdenv.hostPlatform.system}.default + + # My Own + niri-touchscreen-gestures ]); services.usbmuxd.enable = true; services.flatpak.packages = [ diff --git a/pkgs/niri-touchscreen-gestures/.gitignore b/pkgs/niri-touchscreen-gestures/.gitignore index bee8a64..375de91 100644 --- a/pkgs/niri-touchscreen-gestures/.gitignore +++ b/pkgs/niri-touchscreen-gestures/.gitignore @@ -1 +1,2 @@ __pycache__ +.pytest_cache diff --git a/pkgs/niri-touchscreen-gestures/README.md b/pkgs/niri-touchscreen-gestures/README.md index 09ba154..697cdbf 100644 --- a/pkgs/niri-touchscreen-gestures/README.md +++ b/pkgs/niri-touchscreen-gestures/README.md @@ -1,39 +1,157 @@ # niri-touchscreen-gestures -Detect 2/3/4-finger (or more) touchscreen swipes and dispatch arbitrary `niri msg action` commands (or any shell command). +A lightweight Python daemon that reads multi-touch events from a touchscreen via [`evdev`](https://python-evdev.readthedocs.io/), detects **2/3/4-finger swipe gestures**, and dispatches configurable actions to the [niri](https://github.com/YaLTeR/niri) Wayland compositor. + +**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 and movement vectors +- Classifying swipes (up/down/left/right) once they exceed a configurable pixel threshold +- Looking up the gesture in a TOML config and sending an `Action` command to niri's Unix socket (`$NIRI_SOCKET`) + +## Features + +- **Pure event-driven**: No polling, uses `evdev.InputDevice.read_loop()` +- **Multi-finger support**: Automatically counts active fingers (2–4+) +- **Configurable mappings**: TOML file maps gestures like `3-finger-left` to niri actions +- **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`) + +## 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 --config ~/.config/niri/gestures.toml +niri-touchscreen-gestures ``` -Optional flags: +You can still override the defaults: -- `--threshold N` — minimum pixels of movement to register a swipe (default 60) -- `--device /dev/input/eventN` — explicit evdev device (auto-detection usually works on Framework laptops) +```bash +# Use a custom config +niri-touchscreen-gestures --config ~/.config/niri/gestures.toml -## Config (TOML) +# Change swipe sensitivity +niri-touchscreen-gestures --threshold 40 -Keys are `-finger-` where `N` is the finger count and `direction` is one of `up|down|left|right`. +# Use a specific device (bypasses auto-detection) +niri-touchscreen-gestures --device /dev/input/event5 +``` -Values are arrays of command arrays; each inner array is passed verbatim to `subprocess.run`. +### Command-line options -Example (`~/.config/niri/gestures.toml`): +- `--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) + +The program must run with access to `/dev/input/event*` devices (typically via the `input` group) and with the `NIRI_SOCKET` environment variable set. + +## 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 -"2-finger-up" = [["niri", "msg", "action", "focus-workspace-up"]] -"2-finger-down" = [["niri", "msg", "action", "focus-workspace-down"]] -"3-finger-left" = [["niri", "msg", "action", "focus-column-left"]] -"3-finger-right" = [["niri", "msg", "action", "focus-column-right"]] -"4-finger-up" = [["niri", "msg", "action", "toggle-overview"]] +# Example config for niri-touchscreen-gestures +# +# Keys are "-finger-" where: +# N = 2, 3, 4 (or more) +# direction = up | down | left | right +# +# Values are niri actions. See https://github.com/YaLTeR/niri/blob/main/src/niri/config.rs +# for the full list of available actions. + +"3-finger-up" = "FocusWorkspaceDown" +"3-finger-down" = "FocusWorkspaceUp" +"3-finger-left" = "FocusColumnRight" +"3-finger-right" = "FocusColumnLeft" +"4-finger-up" = "ToggleOverview" +"4-finger-down" = "ToggleOverview" ``` -## Requirements +These exact mappings are now the **built-in defaults**. You can map gestures to any niri action that accepts no parameters. -- User must be in the `input` group (or otherwise have read access to the touchscreen evdev node). -- Python ≥ 3.10, `evdev`, `pydantic`/`pydantic-settings`. +**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 and current coordinates. +4. **Gesture Detection**: On finger lift (`TRACKING_ID == -1`), computes delta and classifies direction if movement exceeds threshold. +5. **Action Dispatch**: Looks up `"{finger_count}-finger-{direction}"` in config and sends JSON command to niri's IPC socket. + +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 +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. diff --git a/pkgs/niri-touchscreen-gestures/default.nix b/pkgs/niri-touchscreen-gestures/default.nix index 90281b2..2494f2f 100644 --- a/pkgs/niri-touchscreen-gestures/default.nix +++ b/pkgs/niri-touchscreen-gestures/default.nix @@ -20,11 +20,10 @@ python3.pkgs.buildPythonApplication { pydantic pydantic-settings typing-extensions - ], ]; meta = { - description = "Touchscreen gesture detector for niri (2/3/4-finger swipes → niri actions)"; + description = "Touchscreen gesture detector for niri (2/3/4-finger swipes → niri actions). Just run `niri-touchscreen-gestures` — no config needed."; homepage = "https://github.com/skykanin/nixos-setup"; license = lib.licenses.mit; sourceProvenance = [ lib.sourceTypes.fromSource ]; diff --git a/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/argparser.py b/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/argparser.py index 94a01be..88ff26f 100644 --- a/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/argparser.py +++ b/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/argparser.py @@ -20,8 +20,8 @@ def get_parser() -> argparse.ArgumentParser: ) parser.add_argument( "--config", - required=True, - help="Path to TOML config file", + default=None, + help="Path to TOML config file (optional - uses built-in defaults)", ) parser.add_argument( "--threshold", @@ -39,10 +39,22 @@ def get_parser() -> argparse.ArgumentParser: def process_args( args: argparse.Namespace, ) -> tuple[GestureConfig, evdev.InputDevice, int]: - if not os.path.exists(args.config): + if args.config is None: + config = GestureConfig( + gestures={ + "3-finger-up": "FocusWorkspaceDown", + "3-finger-down": "FocusWorkspaceUp", + "3-finger-left": "FocusColumnRight", + "3-finger-right": "FocusColumnLeft", + "4-finger-up": "ToggleOverview", + "4-finger-down": "ToggleOverview", + } + ) + elif not os.path.exists(args.config): raise FileNotFoundError(f"Config not found: {args.config}") - logger.info(f"niri-touchscreen-gestures: using config {args.config}") - config = GestureConfig.from_toml(args.config) + else: + logger.info(f"niri-touchscreen-gestures: using config {args.config}") + config = GestureConfig.from_toml(args.config) if args.device is None: devices = list(identify_touchscreen_via_evdev()) diff --git a/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/detector/gestures.py b/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/detector/gestures.py index 8b8e11a..e048edb 100644 --- a/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/detector/gestures.py +++ b/pkgs/niri-touchscreen-gestures/niri_touchscreen_gestures/detector/gestures.py @@ -41,7 +41,6 @@ def _handle_event( """Pure event handler. Returns (new_state, action_or_None).""" if ev.type != evdev.ecodes.EV_ABS: return state, None - slot: Slot = state.slots.get(state.current_slot, empty_slot()).copy() new_slots: dict[FingerNumber, Slot] = {k: v.copy() for k, v in state.slots.items()} diff --git a/pkgs/niri-touchscreen-gestures/pyproject.toml b/pkgs/niri-touchscreen-gestures/pyproject.toml index ffc55b7..4d82617 100644 --- a/pkgs/niri-touchscreen-gestures/pyproject.toml +++ b/pkgs/niri-touchscreen-gestures/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "niri-touchscreen-gestures" version = "0.1.0" -description = "Touchscreen gesture detector for niri (2/3/4-finger swipes → niri actions)" +description = "Touchscreen gesture detector for niri (2/3/4-finger swipes → niri actions). Just run `niri-touchscreen-gestures` — no config needed." readme = "README.md" license = { text = "MIT" } requires-python = ">=3.10" @@ -18,7 +18,7 @@ dependencies = [ ] [project.scripts] -niri-touchscreen-gestures = "niri_touchscreen_gestures.cli:main" +niri-touchscreen-gestures = "niri_touchscreen_gestures.main:main_runtime" [tool.hatch.build.targets.wheel] packages = ["niri_touchscreen_gestures"]