223 lines
7.6 KiB
Markdown
223 lines
7.6 KiB
Markdown
---
|
|
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).
|