readme update + working niri-touchscreen-gestures

This commit is contained in:
ari committed 2026-07-11 22:45:33 -04:00
1 parent f29efa11bb
commit e2c46226f7
8 files changed
+207 -33

No files matched your search

+43
View File
@@ -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.<name>` 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.
+7 -5
View File
@@ -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 = [
@@ -1 +1,2 @@
__pycache__
.pytest_cache
+136 -18
View File
@@ -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 `<N>-finger-<direction>` 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 "<N>-finger-<direction>" 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.
+1 -2
View File
@@ -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 ];
@@ -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())
@@ -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()}
@@ -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"]