diff --git a/docs/mx-master.md b/docs/mx-master.md new file mode 100644 index 00000000..80f887e1 --- /dev/null +++ b/docs/mx-master.md @@ -0,0 +1,222 @@ +--- +title: Configuring an MX Master +layout: 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 + +```yaml +--- +- 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: + +```yaml +--- +- 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: + +```yaml +--- +- 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: + +```yaml +--- +- 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 +%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](https://pwr-solaar.github.io/Solaar/installation). + +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](https://pwr-solaar.github.io/Solaar/rules). diff --git a/docs/rules.md b/docs/rules.md index da19895d..c14a69f2 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -330,3 +330,7 @@ switches the mouse to host 3 after popping up a simple notification. ![Solaar-divert-back](screenshots/Solaar-main-window-back-divert.png) ![Solaar-rule-back-host](screenshots/Solaar-rule-editor.png) + +For a worked-through configuration of one device — which buttons can be diverted, the +gestures and thumb wheel, and the settings that need no rules at all — see +[the MX Master page](https://pwr-solaar.github.io/Solaar/mx-master). diff --git a/mkdocs.yml b/mkdocs.yml index 9a267ace..53fd3ab1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,7 @@ nav: - Capabilities: capabilities.md - Issues: issues.md - Rules: rules.md + - MX Master: mx-master.md - Installation: installation.md - Uninstallation: uninstallation.md - Translation: i18n.md