docs: add a worked-through MX Master 3/3S configuration page
Users arriving from Logitech Options+ or LogiOps look for a list of behaviours and instead have to discover that a button does nothing until its diversion is changed, and that some things are settings with no rule at all. That split is the usual reason a first rule appears not to fire. Add a page that walks through one device end to end: which of its buttons can be diverted and under what names, the settings that need no rules, a diverted button driving a key combination, mouse gestures, and the thumb wheel — including the integer argument to the thumb wheel tests, without which a wheel action fires far too often to be useful. Also covers what does not carry over from LogiOps: control ids are not used, key names are X11 key symbols rather than evdev names, and running both daemons against one device makes settings appear to revert at random. Records which conditions are limited under Wayland, since actions go through uinput and do work there, while Modifiers and Process do not. Contents checked against an MX Master 3S on a Logi Bolt receiver.
This commit is contained in:
danielbanariba
parent
8a941c5553
commit
2e3ec225e1
|
|
@ -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).
|
||||
|
|
@ -330,3 +330,7 @@ switches the mouse to host 3 after popping up a simple notification.
|
|||
|
||||
|
||||
|
||||
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue