A native Linux control panel for Logitech MX Master 4, with haptics, Actions Ring and Smart Actions.
Note
0.2.0 is unreleased and in early development. Hardware discovery and listener cleanup have live Bolt evidence; physical setting changes, panel interaction and Bluetooth still need validation. See the validation record.
MX4 Linux is a GTK 4 / Libadwaita application and CLI for MX Master 4 owners on Linux. It uses Solaar's HID++ implementation to discover the mouse's capabilities and expose supported settings. Its desktop features target Niri on Wayland; no Logitech Windows or macOS executable is required.
- Control supported mouse settings. Adjust DPI, wheel modes and direction, SmartShift, haptic strength, panel force and built-in button assignments when reported by the device.
- Choose from eight ring actions. Press the haptic panel once to open the ring at the pointer, then select an action with a click or keyboard. A second panel press, or a right click outside the circles, closes it.
- Group related actions. Turn a position into a side menu of up to six existing routines. The editor shows a live ring preview and keeps labels and assignments together.
- Build Smart Actions. Combine shortcuts, application launches, text, delays and Niri commands, with optional exact application conditions.
- Find controls quickly. Mouse, Actions and Profiles have separate views; the wheel preview and ring respond with finite animations and respect the desktop animation preference.
- Reuse manual profiles. Save current hardware settings and apply them by name; haptic playback is excluded.
- Inspect before changing. JSON discovery, access diagnostics, simulated GUI preview and action dry runs are available from the CLI.
MX4 Linux brings selected mouse controls and a native Actions Ring into a Linux desktop workflow. For example, the ring can copy text, launch a terminal or move to another Niri workspace without opening the settings window.
Solaar supplies the underlying device protocol implementation. MX4 Linux adds a focused GTK 4 interface and Niri desktop actions around it. It exposes discovered settings instead of assuming every connection or firmware offers the same controls.
| Requirement | Details |
|---|---|
| OS | Linux; verified environment: Arch Linux on Niri / Wayland. Other distributions and architectures are not validated. |
| Runtime | Python 3.11+; setup uses the distribution's Python GObject bindings. |
| GUI | GTK 4.12+, Libadwaita 1.4+ and Python GObject. Hardware/configuration CLI commands do not need a graphical session. |
| Typography | Fontconfig and JetBrains Mono Regular/Bold. Setup verifies the family and installs the bundled OFL-licensed fonts when missing. |
| Mouse access | MX Master 4 and read/write access to its hidraw interface, through Bolt or Bluetooth. Live discovery has been verified through Bolt. |
| Desktop features | Niri and an active Wayland session; gtk4-layer-shell library and typelib for the overlay. |
| Optional | wtype for native keyboard input. Setup can build pinned wtype 0.4; /dev/uinput is an optional shortcut fallback. |
Distribution packages and the optional helper's build requirements are listed in the installation guide.
Install the system dependencies, then install from source:
git clone https://github.com/Dijo-404/mx4-linux.git
cd mx4-linux
./scripts/setup.shSetup creates .venv with system site packages, installs MX4 Linux and pinned Solaar 1.1.20, and attempts to build the optional Wayland keyboard helper when needed. It installs no system service or autostart entry.
The npm package launches the same native GTK application. Install the system dependencies above and Node.js 22+, then either run from this checkout:
npm ci --ignore-scripts
npm run setup
npm start
npm start -- gui --demoOr build and install the self-contained local package:
npm pack
npm install --global --prefix "$HOME/.local" ./mx4-linux-0.2.0.tgz
~/.local/bin/mx4-linux setup
~/.local/bin/mx4-linuxAdd ~/.local/bin to your PATH to use mx4-linux directly. No npm registry release has been published by this change. npm installation runs no setup hooks; the explicit setup command downloads Python dependencies into a versioned user environment, without sudo. GTK libraries and Python GObject remain system dependencies. See npm installation for runtime locations, updates and removal.
If doctor reports denied device access, install the device rule:
./scripts/install-udev-rule.sh --dry-run
./scripts/install-udev-rule.shThe second command uses sudo, reloads udev rules and reapplies them to matching connected interfaces. An existing Solaar rule may already provide access. To add a user desktop launcher, run ./scripts/install-desktop.sh after setup.
Choose Quit MX4 Linux from the application menu, then update your checkout and refresh its environment:
git pull --ff-only
./scripts/setup.shRecreate .venv after a system Python version upgrade. Rerun ./scripts/install-desktop.sh if you move the checkout.
Choose Quit MX4 Linux from the application menu, then remove its environment and optional launcher from the checkout:
rm -rf -- .venv .tools
rm -f -- "${XDG_DATA_HOME:-$HOME/.local/share}/applications/io.github.mx4linux.Control.desktop"
rm -f -- "${XDG_DATA_HOME:-$HOME/.local/share}/icons/hicolor/scalable/apps/io.github.mx4linux.Control.svg"Saved settings remain in ${XDG_CONFIG_HOME:-$HOME/.config}/mx4-linux/. See complete removal for optional configuration and installed udev rule removal.
Warning
Run the application as your regular desktop user. Use the access-rule installer when permissions are missing; do not launch the GUI with sudo.
.venv/bin/mx4-linux doctor # check session and Logitech device permissions
.venv/bin/mx4-linux devices --json # discover the mouse and its supported settings
.venv/bin/mx4-linux # open the control panelOpen Actions Ring and click Enable beside Mouse integration, then use the haptic panel from the application you want to control. Opening the editor keeps integration enabled; saved changes update its assignments. Closing the settings window keeps enabled integration running in the background by default. Reopen MX4 Linux from your launcher to return to it. Disable stops integration; Quit (Ctrl+Q) exits the application and restores the selected buttons' prior reporting flags. Application Settings lets you turn off background operation.
To launch an installed app from the ring, choose Add application, select the position under Replace the action at, search for the app and select it, then Save changes. Choosing or saving an application does not launch it. Smart Actions also offers an Open application step for longer routines.
Battery labels refresh automatically. An unavailable reading clears the old percentage; background updates preserve the footer's last operation message.
Use .venv/bin/mx4-linux in this checkout, or activate .venv before using mx4-linux directly.
| Command | Description |
|---|---|
mx4-linux / mx4-linux gui |
Open the native control panel. |
mx4-linux gui --demo |
Preview a simulated mouse without physical device access. |
mx4-linux doctor [--json] |
Inspect the desktop session and Logitech node permissions. |
mx4-linux devices [--json] |
List discovered mice, capabilities and diagnostics. |
mx4-linux set DEVICE SETTING VALUE [--key BUTTON] |
Write one discovered setting; --key selects a button assignment. |
mx4-linux profile list |
List saved hardware profiles. |
mx4-linux profile save NAME [--device DEVICE] |
Save the selected mouse's current settings. |
mx4-linux profile apply NAME [--device DEVICE] |
Validate and apply a profile manually. |
mx4-linux ring [--preview] |
Show the ring; preview prints steps without execution or feedback. |
mx4-linux actions list / actions show [ID] |
Inspect routines or export the complete desktop configuration. |
mx4-linux actions run ID [--dry-run] |
Execute a routine, or validate and print its steps. |
mx4-linux actions validate FILE / actions import FILE |
Check or save a complete desktop JSON configuration. |
mx4-linux --help / --version |
Show command help or the application version. |
Successful CLI requests return 0; handled runtime/configuration failures return 1; command-line syntax errors return 2.
In the main window, Escape closes the current inspector, then returns to the previous page. It does not close the app from Home. Open dropdowns and dialogs handle Escape first. Ctrl+Q quits the application, including background integration. In the action editor, Ctrl+S saves and Escape closes with an unsaved-changes prompt when needed.
These keys apply while the Actions Ring is open:
| Key | Action |
|---|---|
1–8 |
Select and run the corresponding position, clockwise from the top. |
| Arrow keys | Move the selection. |
Enter |
Run the selected action or open its group. |
Escape |
Return from an action group, or close the ring. |
Set a discovered DPI and save a profile
.venv/bin/mx4-linux devices --json
device_id='["/dev/hidraw4",2]' # example only: replace with the discovered ID
.venv/bin/mx4-linux set "$device_id" dpi 1600
.venv/bin/mx4-linux profile save Work --device "$device_id"Copy the current device ID as a single quoted string; its embedded JSON quotes must reach the CLI unchanged. Use a DPI choice reported by your mouse. Values are JSON integers or booleans; choice and button IDs come from discovery. Refresh IDs after reconnecting.
Preview before running a routine
.venv/bin/mx4-linux actions show copy
.venv/bin/mx4-linux actions run copy --dry-run
.venv/bin/mx4-linux ring --previewExport, validate and import desktop configuration
.venv/bin/mx4-linux actions show > desktop.json
.venv/bin/mx4-linux actions validate desktop.json
.venv/bin/mx4-linux actions import desktop.jsonImport replaces the saved desktop configuration. Disable and re-enable GUI mouse integration after a CLI import to apply changed button bindings.
Hardware profiles live in $XDG_CONFIG_HOME/mx4-linux/profiles.json; desktop actions live in $XDG_CONFIG_HOME/mx4-linux/desktop.json. The default configuration directory is ~/.config. Use the GUI editor or export/import commands instead of editing a file while it is being saved.
A desktop document requires all six top-level keys. This minimal example assigns Copy to all eight positions:
{
"version": 1,
"ring": ["copy", "copy", "copy", "copy", "copy", "copy", "copy", "copy"],
"actions": {
"copy": {"label": "Copy", "steps": [{"type": "shortcut", "keys": ["CTRL", "C"]}]}
},
"button_bindings": {},
"ring_button": 416,
"haptic_feedback": true
}Without a saved desktop file, defaults provide Overview, Screenshot, Terminal, Next workspace, Paste, Copy, Undo and Previous workspace. The full schema, defaults and limits are in docs/configuration.md.
| Variable | Effect |
|---|---|
XDG_CONFIG_HOME |
Overrides the configuration root; defaults to ~/.config. |
XDG_DATA_HOME |
Overrides the desktop launcher's data root; defaults to ~/.local/share. |
TERMINAL |
Preferred terminal command for the default Terminal action, if executable. |
PYTHON |
System Python used by source setup or mx4-linux setup; defaults to python3. |
MX4_LINUX_PYTHON |
npm launcher override for an existing Python environment with the runtime dependencies installed. |
WAYLAND_DISPLAY |
Identifies the active Wayland session for native input and optional helper setup. |
XDG_SESSION_TYPE, XDG_CURRENT_DESKTOP |
Included in doctor diagnostics. |
| Path | Contents |
|---|---|
.venv/, .tools/ |
Local Python environment and optional wtype source/build cache. |
$XDG_CONFIG_HOME/mx4-linux/desktop.json |
Saved ring assignments, routines and button bindings. |
$XDG_CONFIG_HOME/mx4-linux/profiles.json |
Manually saved hardware profiles. |
$XDG_CONFIG_HOME/mx4-linux/*.json.lock |
Locks for configuration/profile writes. |
$XDG_DATA_HOME/applications/io.github.mx4linux.Control.desktop |
Optional launcher pointing to this checkout. |
$XDG_DATA_HOME/icons/hicolor/scalable/apps/io.github.mx4linux.Control.svg |
Application icon installed with the launcher. |
/etc/udev/rules.d/70-mx4-linux.rules |
Optional active-seat access rule for Bolt and MX4 Bluetooth hidraw interfaces. |
/etc/udev/rules.d/71-mx4-input.rules |
Optional active-seat access rule for the uinput fallback. |
Default XDG roots apply when the variables are unset. Configuration saves replace the corresponding JSON file atomically. Installer scripts replace their named launcher/rule files without creating backups.
- The application has no telemetry or application-managed network requests. Setup downloads dependencies and, when needed, wtype source; configured commands can make their own network requests.
- Mouse integration is opt-in. It temporarily diverts only selected nonprimary buttons and restores their previous reporting flags on clean disable or exit.
- Smart Actions execute the commands and input you configure. Commands use explicit argument arrays without an implicit shell; review imported routines before running them. Native wtype text preserves the clipboard; the
wl-copyfallback replaces it before pasting. - Hardware writes apply immediately. Profiles are validated before writing, but a hardware failure can leave earlier changes applied; refresh to inspect the result. Haptic playback is never saved or replayed by profiles.
flowchart LR
UI["GTK control panel / CLI"] --> HW["Isolated settings worker"]
HW --> HID["Solaar HID++ / MX Master 4"]
HID --> Events["Isolated event worker"]
Events --> Ring["Actions Ring"]
Ring --> Actions["Smart Actions"]
Actions --> Desktop["Niri IPC / wtype / uinput"]
Solaar runs outside the GTK 4 UI to avoid its GTK 3 imports and to isolate device handles. A separate retained event session handles opted-in mouse controls, while the UI manages ring selection and cancellable routines. Settings writes validate the discovered schema and verify readback except for command-only haptic playback. See architecture for lifecycle and cleanup details.
| Component | Tool |
|---|---|
| Application | Python 3.11+ |
| Native UI | GTK 4 / Libadwaita / PyGObject |
| Mouse protocol | Solaar 1.1.20, pinned because internal APIs are used |
| Overlay | gtk4-layer-shell |
| Desktop input | Niri IPC, wtype, python-evdev |
| Tests | pytest |
.
├── src/mx4_linux/ # control panel, protocol workers and desktop actions
├── tests/ # simulated hardware, validation and lifecycle checks
├── data/ # optional udev access rules
├── docs/ # user guides, research and validation records
├── evidence/ # retained installer analysis and hardware smoke records
├── scripts/ # setup, helper build and access installers
└── README.md
Read docs/architecture.md and CONTRIBUTING.md before making changes. After installing the system dependencies:
git clone https://github.com/Dijo-404/mx4-linux.git
cd mx4-linux
./scripts/setup.sh # install runtime and development tools
.venv/bin/python -m pytest -q # run automated checks
.venv/bin/python -m ruff check src tests # syntax, undefined names and unused imports
.venv/bin/python -m compileall -q src tests # check Python compilation
for script in scripts/*.sh; do bash -n "$script"; done # check shell syntax
npm ci --ignore-scripts
npm test && npm run check && npm run test:package # launcher and packed installThe recorded validation includes simulated hardware tests, live Bolt discovery, event reporting restoration, a GTK ring preview and controlled native input. These checks do not establish physical setting behavior or real panel selection; see validation notes.
No accessible mouse or permission denied
Wake the mouse and run .venv/bin/mx4-linux doctor --json. If access is denied, preview and install the device rule, then click Check again or Refresh:
./scripts/install-udev-rule.sh --dry-run
./scripts/install-udev-rule.shThe installer triggers matching interfaces already connected; a rules reload alone does not apply new ACLs to existing devices. Close competing configuration tools if discovery or writes remain inconsistent.
GTK imports fail after a Python upgrade
Install your distribution's current Python GObject bindings, recreate the local environment and rerun setup:
rm -rf -- .venv
./scripts/setup.shShortcuts need wtype or uinput access
On Niri, install your distribution's wtype package or build the pinned local helper:
./scripts/setup-wtype.shThe optional shortcut fallback rule is installed with ./scripts/install-input-access.sh; preview it with --dry-run. Without wtype, text actions need wl-copy and paste through the clipboard. See the desktop feature guide.
- Flow is deferred for a later Linux, Windows and macOS implementation. Options+ plugins and automatic per-application hardware profiles are not implemented.
- Desktop integration targets Niri on Wayland. Other compositors are unverified; the ring may fall back to a normal window and Niri actions require Niri.
- The ring opens at the pointer on supported Wayland desktops and stays inside screen edges, with a centered fallback if pointer location is unavailable. Ring/button-triggered input requires a valid target and refuses shortcuts/text when an MX4 configuration window is focused; direct CLI routine execution uses the current focus without this GUI guard.
- Hardware settings may reset after power loss or reconnect. Profiles apply manually; no daemon or automatic reapplication is installed.
- Physical DPI, wheel, button and haptic changes, panel press/move/release, feedback ticks, reconnect while holding and Bluetooth still need interactive validation.
- Native settings panel, diagnostics, haptic commands and manual profiles
- Actions Ring, Smart Actions editor and opt-in extra-button shortcuts
- Niri focus handling and optional native Wayland keyboard helper
- Complete physical panel, settings, reconnect and Bluetooth checks
- Add compositor adapters beyond Niri
- Explore Flow across Linux, Windows and macOS
| Guide | What's in it |
|---|---|
| Installation | Dependencies, manual setup, access rules and complete removal |
| Configuration | Desktop schema, defaults, profiles and environment variables |
| Architecture | Workers, event lifecycle, focus and action execution |
| Interface design | Monospaced typography, warm neutral themes and native motion |
| UI polish verification | Native captures, motion lifecycle, font installation and package checks |
| Desktop features | Ring interaction, Smart Actions and Niri bindings |
| Validation | Recorded checks and remaining hardware work |
| Linux support research | Protocol sources and implementation constraints |
| Installer analysis | Static artifact investigation and evidence limits |
| Installed Windows Options+ analysis | MX4 interface/agent protocols, haptics, force sensing and remaining gaps |
| Changelog | User-visible changes and release history |
Issues and pull requests are welcome. Read CONTRIBUTING.md before opening a PR, and use GitHub Issues for bugs and feature requests.
Use the private contact guidance in SECURITY.md before sharing sensitive details. Please do not disclose vulnerabilities or credentials in public issues.
Released under GPL-3.0-or-later. Solaar retains its GPL-2.0-or-later license; the optional wtype helper retains its MIT license.
- Solaar for the HID++ implementation and MX Master 4 feature definitions.
- wtype for native Wayland keyboard input.
- gtk4-layer-shell and Niri for overlay and desktop APIs.
