mx3.enbonnet.com

MX3 Linux Driver

A Linux gesture driver for Logitech MX mice that watches raw mouse events and turns hold-and-move gestures into keyboard shortcuts through /dev/uinput.

Quick start GNOME extension

What this project does

The driver opens the MX mouse input device, tracks movement while a configured button is held, classifies the gesture direction, and injects the mapped key combination through a virtual keyboard.

What it does not do

It does not provide GNOME UI by itself. If you want a Quick Settings toggle inside GNOME Shell, pair it with MX3 Control for GNOME.

Project split

  • MX3 Linux Driver: the actual gesture engine and key injector
  • MX3 Control for GNOME: a GNOME Shell extension that starts, stops, and monitors mx3

Use them together

Install this driver first. Then install the GNOME extension if you want per-session controls in Quick Settings. The extension depends on the mx3 command from this repository.

Read the extension docs
Setup

Quick start

make
sudo make install
sudo modprobe uinput
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo systemctl daemon-reload
sudo systemctl enable --now mx3
sudo systemctl status mx3

The supported production path is the packaged root-managed systemd service.

Runtime

How it works

1

Scans /dev/input/event* for a matching Logitech mouse.

2

Creates a virtual keyboard through /dev/uinput.

3

Watches button presses and accumulates mouse movement.

4

Classifies the result as tap, directional swipe, or diagonal gesture.

5

Looks up the mapped action in the INI config and injects the key combo.

Supported buttons

Forward, back, middle, extra, side scroll click, and thumb gesture buttons can all be mapped.

Supported gestures

tap, left, right, up, down, and the four diagonal directions.

Configuration model

Configuration is loaded from the first matching file in the documented search order, with built-in defaults when no file is found.

GNOME pairing

How the GNOME extension fits in

Without the extension

The driver runs as a normal Linux service or CLI process and handles gestures on its own. This is the core functionality.

With the extension

The GNOME extension starts mx3 --daemon --pid-file=/tmp/mx3.pid, watches the PID file, checks whether the process still exists, and exposes start, stop, and restart controls in Quick Settings.

Recommended flows

Choose your setup

System-wide service

Best for a production Linux setup. Use the packaged systemd service and manage logs with journalctl.

GNOME session control

Best when you want a desktop toggle. Install the extension after the driver, verify mx3 --help works in your GNOME session, then control it from Quick Settings.

More docs

Repository documents

Release process

Documents version alignment, package validation, and release artifacts.

Troubleshooting

First things to check

  • sudo journalctl -u mx3 -f for service logs
  • sudo mx3 -l debug for foreground debugging
  • Verify /dev/uinput exists and the uinput module is loaded
  • Force a device with mx3 -d /dev/input/eventN if autodetection misses your mouse