readme update + working niri-touchscreen-gestures
This commit is contained in:
1 parent
f29efa11bb
commit
e2c46226f7
8 files changed
+207
-33
No files matched your search
@@ -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
@@ -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
|
||||
@@ -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.
|
||||
@@ -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"]
|
||||
Reference in new issue
Block a user