matebook-gestures

Linux gesture daemon and configuration TUI for the Goodix haptic touchpad in the Huawei MateBook X Pro 2024.

Supported hardware

• Huawei MateBook X Pro 2024
• Goodix GXTP7863 touchpad, device ID 27C6:01E0
• x86_64 Linux with systemd, udev, hidraw, evdev, and uinput

Other touchpad IDs are not supported.

Gestures

Gesture	Default desktop action
Right-edge slide	Volume
Left-edge slide	Brightness
Top-edge slide	Workspace or media seek
One-knuckle double knock	Screenshot
Two-knuckle double knock	Screen recording
Top-left press	Toggle maximize
Top-right press	Close window

Features

• Maps firmware gesture reports to virtual keyboard events.
• Configures click sensitivity, vibration, and firmware gesture masks.
• Provides desktop, KDE, media, presenter, navigator, and minimal presets.
• Includes a TUI, health check, event trace, and safe live gesture test.
• Reloads configuration without restarting the daemon.
• Offers optional direct touchpad control with click classification and trackball inertia. Direct control is experimental and disabled by default.

See Experimental Features for behavior, tuning, limitations, and recovery steps.

Install

Prebuilt x86_64 archives are available for Debian 12 and 13; Ubuntu 22.04, 24.04, and 26.04; Fedora 44; and Arch Linux from GitHub Releases. See the Install and Build Guide for dependencies, checksums, upgrades, and source builds.

Quick source install:

make
make test
sudo make install
sudo matebook-gestures install
matebook-gestures config

Commands

Command	Purpose
matebook-gestures config	Configure settings; prompts for sudo when needed
matebook-gestures status	Check hardware, service, config, and udev setup
matebook-gestures events [--raw]	Watch gesture events
matebook-gestures keys	List valid key names
matebook-gestures preset list	List built-in presets
sudo matebook-gestures run --debug	Run the daemon in the foreground
sudo matebook-gestures uninstall [--purge]	Remove the service and rules

Configuration

Use the TUI rather than editing /etc/matebook-gestures.conf directly:

matebook-gestures config

For the default system config, the command relaunches itself through sudo and prompts for the administrator password. A custom --config PATH remains unprivileged.

Press t for touchpad controls and w for the live gesture test. The test shows recognized gestures and configured actions without executing them.

Direct-control click actions accept left, right, middle, none, key combinations, or exec: <command>. After a manual config edit, reload with:

sudo systemctl reload matebook-gestures

Safety

The service runs as root. Keep /etc/matebook-gestures.conf root-writable only, and treat exec: bindings as root shell commands.

Direct control grabs the physical touchpad. Keep a keyboard, console, or SSH session available when enabling it; this command returns control to libinput:

sudo systemctl stop matebook-gestures

Report vulnerabilities as described in SECURITY.md.

Troubleshooting

Start with:

matebook-gestures status

For foreground diagnostics:

sudo systemctl stop matebook-gestures
sudo matebook-gestures run --debug

Development

Run make WERROR=-Werror all test before submitting changes. See CONTRIBUTING.md.

License

MIT

Support

If this project helped you and you would like to throw me some coin, you may donate through here: