Merge 2e3ec225e1 into 8a941c5553
This commit is contained in:
Daniel Barrientos Anariba
GitHub
commit
d7d615e2e8
|
|
@ -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