Solaar/docs/mx-master.md

title	layout
Configuring an MX Master	page

Configuring an MX Master 3 / 3S

People often arrive at Solaar from Logitech Options+ or LogiOps expecting to find the same gestures and button remappings, and get stuck because Solaar does not present them as a single list of behaviours. The work is split across two layers, and a setup only works when both are right — which is the usual reason a rule "does nothing".

This page walks through a complete MX Master 3 / 3S configuration. Everything on it was checked against an MX Master 3S on a Logi Bolt receiver; other MX mice work the same way, though the exact set of buttons differs.

The two layers

Settings live on the device and are applied by Solaar whenever the device connects. Scroll behaviour, DPI and SmartShift are settings, and nothing else is needed to use them.

Rules live in ~/.config/solaar/rules.yaml and react to notifications sent by the device. A button only sends notifications once its Key/Button Diversion is changed from Regular, so a rule that matches a button you have not diverted can never fire.

What you want	Diversion needed	Rule needed
DPI, SmartShift, scroll direction	no	no
A button that types a key combination	Diverted	yes
Mouse gestures (hold a button, move)	Mouse Gestures	yes
Thumb wheel doing something other than horizontal scroll	Thumb Wheel Diversion on	yes

What your mouse reports

Start from what the device actually says rather than from a list of button names copied from somewhere else:

solaar show

The Reprogrammable keys section lists every button with the exact name to use in rules. Only buttons whose report includes divertable can be diverted. On an MX Master 3S:

    0: Left Button               , default: Left Click
    1: Right Button              , default: Right Click
    2: Middle Button             , default: Mouse Middle Button
    3: Back Button               , default: Mouse Back Button
    4: Forward Button            , default: Mouse Forward Button
    5: Mouse Gesture Button      , default: Gesture Button Navigation
    6: Smart Shift               , default: Smart Shift
    7: Virtual Gesture Button    , default: Virtual Gesture Button

Mouse Gesture Button is the large thumb button, and Smart Shift is the button behind the scroll wheel.

Settings that need no rules

These are set in the main window and are all Solaar needs to know about:

Setting	Notes
Sensitivity (DPI)	Pointer speed, in steps the device reports.
Scroll Wheel Ratcheted	Ratcheted for a clicky wheel, Free Spinning for a free wheel.
Scroll Wheel Ratchet Speed	How fast the wheel must spin before it disengages the ratchet — the equivalent of a SmartShift threshold.
Scroll Wheel Direction, Thumb Wheel Direction	Invert a wheel.
Scroll Wheel Resolution	High-resolution scrolling.

Remapping a button

Two steps, both required.

1. Divert the button. In the main window, set Key/Button Diversion for the button to Diverted. From the command line:

solaar config "MX Master 3S" divert-keys "Mouse Gesture Button" Diverted

2. Add a rule that matches the button and does something. Rules can be written in the rule editor (main window, Rule Editor) or directly in ~/.config/solaar/rules.yaml.

Thumb button opens the GNOME overview

---
- Key: [Mouse Gesture Button, pressed]
- KeyPress: [Super_L]
...

Back and Forward navigate in the browser

The two side buttons already send back/forward events by default. Divert them only if you want something else — here, the keyboard shortcuts that also work in applications that ignore the dedicated buttons:

---
- Key: [Back Button, pressed]
- KeyPress: [Alt_L, Left]
...
---
- Key: [Forward Button, pressed]
- KeyPress: [Alt_L, Right]
...

KeyPress takes X11 key symbol names, not evdev key codes: Super_L, not KEY_LEFTMETA.

Mouse gestures

Set Key/Button Diversion for the thumb button to Mouse Gestures rather than Diverted. Holding that button, moving the mouse, and releasing it then produces a single notification describing the movement, which MouseGesture conditions match.

Switching workspaces by holding the thumb button and flicking left or right:

---
- MouseGesture: [Mouse Left]
- KeyPress: [Super_L, Page_Up]
...
---
- MouseGesture: [Mouse Right]
- KeyPress: [Super_L, Page_Down]
...

A gesture can chain several movements, so [Mouse Up, Mouse Up] is a different gesture from [Mouse Up]. Pressing and releasing the button without moving produces a No-op gesture, which can be given its own rule — useful for keeping an action on a button that is otherwise used for gestures.

Thumb wheel

Turn on Thumb Wheel Diversion, then match the wheel with thumb_wheel_up and thumb_wheel_down. Switching browser tabs:

---
- Feature: THUMB WHEEL
- Rule: [Test: [thumb_wheel_up, 5], KeyPress: [Control_L, Shift_L, Tab]]
- Rule: [Test: [thumb_wheel_down, 5], KeyPress: [Control_L, Tab]]
...

The integer argument matters. The thumb wheel reports many small increments, so a bare thumb_wheel_up test fires far too often for a discrete action like changing tabs. With a parameter the test is only true once the accumulated displacement passes that value, and the displacement is then reduced by it — raise the number for slower switching, lower it for faster.

A complete example

%YAML 1.3
---
- Key: [Mouse Gesture Button, pressed]
- KeyPress: [Super_L]
...
---
- Key: [Back Button, pressed]
- KeyPress: [Alt_L, Left]
...
---
- Key: [Forward Button, pressed]
- KeyPress: [Alt_L, Right]
...
---
- Feature: THUMB WHEEL
- Rule: [Test: [thumb_wheel_up, 5], KeyPress: [Control_L, Shift_L, Tab]]
- Rule: [Test: [thumb_wheel_down, 5], KeyPress: [Control_L, Tab]]
...

with Key/Button Diversion set to Diverted for Mouse Gesture Button, Back Button and Forward Button, and Thumb Wheel Diversion turned on.

Coming from LogiOps

logid.cfg	Solaar
dpi: 1500	Sensitivity (DPI) setting
smartshift: { on: true; threshold: 15 }	Scroll Wheel Ratcheted and Scroll Wheel Ratchet Speed
hiresscroll: { hires: ... }	Scroll Wheel Resolution setting
buttons: ({ cid: 0xc3; action = Keypress ... })	divert Mouse Gesture Button, then a Key rule with KeyPress
cid: 0x53 / cid: 0x56	Back Button / Forward Button
gestures on a button	Key/Button Diversion set to Mouse Gestures, then MouseGesture rules
evdev names (KEY_LEFTMETA)	X11 key symbols (Super_L)

Control IDs do not appear in Solaar's interface; use the button names from solaar show instead.

Do not run LogiOps and Solaar against the same device at the same time. Both reprogram the same controls, and whichever writes last wins, which looks like settings randomly reverting.

Session notes

KeyPress, MouseScroll and MouseClick actions are performed through a uinput virtual device, so they work under both X11 and Wayland. This needs Solaar's udev rule to be installed; see the installation page.

Two kinds of condition are more limited under Wayland, because no Wayland protocol exposes what they need:

• Modifiers conditions cannot read the keyboard modifier state.
• Process and MouseProcess conditions need the Solaar GNOME extension, and work only under GNOME.

Solaar reports both limitations at startup when it detects a Wayland session.

For the full set of conditions and actions see the rules page.