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
@@ -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