mx3-gnome.enbonnet.com

MX3 Control for GNOME

A GNOME Shell extension that adds a Quick Settings control for the external mx3 daemon. It does not implement gesture handling itself. It controls the driver from your desktop session.

Install flow Driver docs

What this project does

It adds an MX3 Control tile to GNOME Quick Settings and lets you start, stop, restart, and monitor the mx3 background process from the GNOME Shell UI.

Dependency

This extension requires the mx3 executable from MX3 Linux Driver. Without that command, the extension loads but cannot control anything.

Project split

  • Driver: reads the mouse, classifies gestures, injects keys
  • GNOME extension: provides desktop controls for that driver

Use them together

Install the driver first, confirm mx3 --help works in the same session where GNOME Shell runs, then install this extension to manage the daemon visually.

Read the driver docs
Setup

Install flow

# 1. Install the driver first
mx3 --help

# 2. Install the extension
make install

# 3. Enable it
gnome-extensions enable mx3-control-gnome@enbonnet.github.com

If the extension is not listed immediately, log out and back in once so GNOME Shell refreshes its extension list.

Architecture

How it works

1

On enable, the extension creates an Mx3Manager and refreshes status.

2

The manager resolves the mx3 executable from PATH or common install paths.

3

When started from Quick Settings, it launches mx3 --daemon --pid-file=/tmp/mx3.pid.

4

It reads /tmp/mx3.pid and checks /proc/<pid> to determine whether the daemon is still alive.

5

The Quick Settings tile updates to show Running, Stopped, or Error, with restart and preferences actions.

Session UX

Single-click toggling for start and stop, plus submenu actions for restart and preferences.

Status model

The extension polls every 3 seconds and surfaces the last startup or runtime error in the menu.

Preferences

Current preferences expose one setting: automatically start the daemon when the extension is enabled.

Driver relationship

How this differs from the driver

The driver owns

Device detection, gesture classification, configuration parsing, and virtual keyboard injection through /dev/uinput.

This extension owns

GNOME Shell integration only: Quick Settings UI, preferences, daemon launch, PID tracking, and error presentation.

Best practice

Recommended combined setup

  1. Install and validate the driver first.
  2. Make sure the mx3 binary is visible in the GNOME session.
  3. Install and enable the extension.
  4. Use Quick Settings for session-level control and use the driver config for gesture mapping.
Troubleshooting

Common failure points

mx3 missing

If the tile reports an error immediately, confirm mx3 --help works in a terminal inside the same desktop session.

Permission problems

If the driver cannot open /dev/uinput, fix the driver installation and host permissions first. The extension cannot solve system device access issues.

Testing

Verification commands

make pack
./run-headless-test.sh

# optional visual test
./run-visual-test.sh

The documented working approach for recent GNOME Shell versions in this repository is gnome-shell-test-tool.