Syngestures: Linux Multi-Touch Protocol Userland Daemon

syngestures is a utility providing multi-gesture support for various Linux touchpad/trackpad drivers implementing the Linux Multi-Touch Protocol, such as xf86-input-synaptics. Read more about syngesture, the impetus for its development, and how it fits into the X11/Wayland evdev/libinput ecosystem in the release announcement

Purpose and Design

syngestures is a daemon (background application) that listens for input events generated by your touchpad or trackpad and detects when multi-touch gestures are performed. It can be configured (globally or on a per-user level) to carry out user-defined actions when specific gestures are recognized (with support for unique configurations per-device if you have multiple touchpads installed).

It may be used alone or, more commonly, in conjunction with desktop environment/display server integration/driver - we recommend using it with xf86-input-synaptics under X11 for the most responsive and "natural" cursor movement and acceleration.

Dependencies

syngestures currently has a runtime dependency on the evtest binary that listens for and reports events generated by input devices. evtest is often directly installable via your distribution's package manager, e.g. sudo apt install evtest.

Security Considerations

Depending on your system configuration and at least until the evtest dependency is dropped, you may need to set the SUID bit on evtest to allow non-root users to invoke evtest without requiring the calling process to also be elevated (e.g. sudo chmod u+s $(which evtest)). Since syngestures currently allows running arbitrary commands in response to multi-touch gestures via its configuration files, it is not recommended to work around permission errors by invoking this application as sudo syngestures.

Installation

syngesture is written in rust and has no system build dependencies/requirements. It can be compiled and installed by checking out a copy of the source code and building with cargo, the rust package manager:

git clone https://github.com/mqudsi/syngesture.git
cd syngesture
cargo install --path .

alternatively, it may be installed directly via cargo:

cargo install syngestures

Configuration

syngesture is configured via one or more TOML configuration files, a sample file is included in this repository. Configuration files may be installed at a machine level to /usr/local/etc/syngestures.toml or with multiple per-device configuration files installed to /usr/local/etc/syngestures.d/*.toml, or at a user level with a configuration file at $HOME/.config/syngestures.toml or multiple per-device configuration files installed to $HOME/.config/syngestures.d/*.toml. Multiple files are supported and concatenated with user configuration files overriding the system configuration file.

The basic format of the configuration file is as follows, with a [[device]] node per input device implementing the MT protocol:

[[device]]
device = "/dev/input/by-path/pci-0000:00:15.0-platform-i2c_designware.0-event-mouse"
gestures = [
	# Navigate next
	{ type = "swipe", direction = "right", fingers = 3, execute = "xdotool key alt+Right" },
	# Navigate previous
	{ type = "swipe", direction = "left", fingers = 3, execute = "xdotool key alt+Left" },
	# Next desktop/workspace
	{ type = "swipe", direction = "right", fingers = 4, execute = "xdotool key Super_L+Right" },
	# Previous desktop/workspace
	{ type = "swipe", direction = "left", fingers = 4, execute = "xdotool key Super_L+Left" },
]

The value of device should be a stable path to your touchpad, it can often be found by looking at the output of dmesg. Wayland users may substitute the usage of xdotool for whatever alternative supports their display server/compositor/window manager.

The value of each gesture's type may be either swipe or tap; a numeric fingers parameter from 1 to 5 is required in both cases, but an additional direction (being one of right, left, up, or down) is required in case of swipe.

License

syngestures is developed and maintained by Mahmoud Al-Qudsi and released as open source under the MIT license, copyright NeoSmart Technologies 2020-2022.