Documentation & Developer Manual

1. Quickstart & Installation

FingerSwipe runs as an unprivileged user daemon with direct device access granted through standard udev session tags (uaccess). Pre-built binary packages are available on GitHub Releases.

Debian / Ubuntu Installation

# Install deb package
sudo apt install ./fingerswipe_1.1.0_amd64.deb

# Enable and start user daemon
systemctl --user daemon-reload
systemctl --user enable --now fingerswipe.service

Universal Linux Installation (Arch / Fedora / openSUSE / Void)

tar -xzf fingerswipe-1.1.0-linux-x86_64.tar.gz
cd fingerswipe-1.1.0-linux-x86_64
sudo ./install.sh

systemctl --user daemon-reload
systemctl --user enable --now fingerswipe.service

2. Hardware Eligibility Diagnostic

Run the built-in diagnostic tool to verify that your touchpad supports multi-finger gesture events via libinput:

fingerswipe --check-hardware

Diagnostic Check Details:

Touchpad Presence: Queries udev for devices with ID_INPUT_TOUCHPAD=1.
Gesture Capabilities: Verifies LIBINPUT_DEVICE_CAP_GESTURE is reported by the kernel driver.
PipeWire Server: Checks communication with default audio output sink.
Display Backlight: Verifies write permissions to /sys/class/backlight.

3. Seamless In-Place Updates

Upgrades are zero-downtime. FingerSwipe gracefully reloads configurations and restarts without terminating your active desktop session.

# Debian / Ubuntu update
sudo apt install --reinstall ./fingerswipe_1.1.0_amd64.deb

# Universal installer update
sudo ./install.sh --update

4. System Architecture & Boundaries

FingerSwipe is structured into two cleanly separated layers: a lightweight C23 native gesture capture backend and a high-level policy engine written in Python 3.13.

Component	Layer	Technology	Responsibility
`libfingerswipe_native.so`	Native ABI	C23, libinput, libudev	Kernel gesture stream monitoring, 3-finger swipe detection, sub-ms event callbacks.
`fingerswipe.controller`	Controller	Python 3.13, ctypes	PipeWire volume control, 1% minimum brightness floor, KDE Plasma OSD feedback.
`fingerswipe.router`	Router	Python 3.13	Directional axis locking, delta vector filtering, curve smoothing.
`fingerswipe.service`	Service	systemd --user	Session lifecycle management, hot-reload, unprivileged operation.

5. C23 Native ABI Reference

Exported C ABI declarations defined in native/include/fingerswipe.h:

#pragma once

typedef struct fingerswipe_handle fingerswipe_handle;

typedef enum {
    FINGERSWIPE_EVENT_GESTURE_BEGIN = 0,
    FINGERSWIPE_EVENT_GESTURE_UPDATE = 1,
    FINGERSWIPE_EVENT_GESTURE_END = 2,
} fingerswipe_event_type_t;

typedef struct {
    fingerswipe_event_type_t type;
    int finger_count;
    double dx;
    double dy;
    uint64_t timestamp_us;
} fingerswipe_event_t;

typedef void (*fingerswipe_callback_t)(const fingerswipe_event_t* event, void* user_data);

fingerswipe_handle* fingerswipe_create(void);
int fingerswipe_start(fingerswipe_handle* handle, fingerswipe_callback_t cb, void* user_data);
void fingerswipe_stop(fingerswipe_handle* handle);
void fingerswipe_destroy(fingerswipe_handle* handle);

6. Configuration & Mathematical Curves

Config file path: ~/.config/fingerswipe/config.yaml.

Supported Sensitivity Curves

Linear: f(x) = sensitivity * x (1:1 motion tracking).
Exponential: f(x) = sgn(x) * |x|^1.4 * sensitivity (High precision at slow speeds).
Logarithmic: f(x) = sgn(x) * ln(1 + |x|) * sensitivity (Rapid initial response).

engine:
  dead_zone: 0.00
  smoothing: 1.00
  sensitivity: 1.00
  curve: linear
  axis_lock_threshold: 2.0

volume:
  enabled: true
  axis: vertical
  minimum: 0.0
  maximum: 1.0
  step: 0.01
  threshold: 4.0

brightness:
  enabled: true
  axis: horizontal
  minimum: 0.01
  maximum: 1.0
  step: 0.01
  threshold: 4.0

logging:
  level: INFO
  json: false

7. CLI Reference

The fingerswipe command-line executable provides daemon controls and real-time event debugging:

# Start the user daemon in foreground (for testing/logs)
fingerswipe --foreground

# Validate configuration syntax
fingerswipe --check-config

# Run hardware & environment diagnostic
fingerswipe --check-hardware

# Live gesture event monitor
fingerswipe --monitor

FingerSwipe Documentation