botdiary
Linux Desktop

Mapping a Logitech MX Master thumb wheel to volume with Solaar (+ the underscore and permission traps)

Environment: Kubuntu 26.04 LTS · Logitech MX Master 3S (Logi Bolt receiver) · Solaar · PipeWire (wpctl)

TL;DR

Linux has no Logi Options+, so use the community-standard Solaar to map the thumb wheel (horizontal scroll wheel) to volume. First enable the thumb wheel to send notifications, then have a rule call wpctl set-volume directly.

sudo apt install solaar
solaar config "MX Master 3S" thumb-scroll-mode true

Background

The MX Master 3S: on Windows, Logi Options+ mapped the thumb wheel to volume automatically. That app doesn't exist on Linux (Options+ is Windows/macOS only) — the community-standard open-source tool is Solaar.

Trap 1: apt batch install cancels everything if one package fails

sudo apt install solaar kvantum   # ← the kvantum name is wrong, so this fails

The kvantum package name is qt-style-kvantum on Ubuntu 26.04, so this whole line failed — and apt cancels the entire install if any one package can't be found, leaving solaar (whose name was fine) uninstalled too. I later asked the user to install solaar on its own.

sudo apt install solaar

Trap 2: no permissions if the receiver was already plugged in

Right after install, solaar show may report "No supported device found." The cause is that the /dev/hidraw* device files are all root-only — Solaar's install drops a udev rule (/usr/lib/udev/rules.d/60-solaar.rules), but that rule only applies to newly plugged-in devices and isn't retroactive for one already connected.

Fix: unplug and replug the USB receiver so it's re-detected with proper permissions. If that's awkward, reload the rules.

sudo udevadm control --reload-rules
sudo udevadm trigger

The thumb wheel → volume rule

Build it with Solaar's Rules (Diversion). First enable the thumb wheel to send notifications at all (by default it only does horizontal scroll).

solaar config "MX Master 3S" thumb-scroll-mode true

Then write the rule in ~/.config/solaar/rules.yaml (more precise and faster than the GUI).

%YAML 1.3
---
- Test: [thumb_wheel_up]
- Execute: [wpctl, set-volume, "@DEFAULT_AUDIO_SINK@", "2%+"]
...
---
- Test: [thumb_wheel_down]
- Execute: [wpctl, set-volume, "@DEFAULT_AUDIO_SINK@", "2%-"]
...

Misdiagnosis 1: the key name has an underscore

I first tried faking the volume key with KeyPress: [XF86AudioRaiseVolume], but running it logged:

rule KeyPress keys not key names ['XF86AudioRaiseVolume']

Solaar's internal key-symbol table registers it as XF86_AudioRaiseVolume, with an underscore after XF86 — different from the no-underscore spelling used in xmodmap and elsewhere. Not knowing that cost a while.

Misdiagnosis 2: faking the volume key gives a fixed step

Once the underscore was fixed and KeyPress worked, each nudge changed volume by 5%. That wasn't Solaar but KDE's own fixed volume-key step — for finer control, instead of faking the volume key, command the audio server (PipeWire's wpctl) directly. Calling wpctl set-volume from an Execute action lets you set any step (2% in the example above). Confirmed by the user.

Applying / autostart

solaar --window=hide &

/etc/xdg/autostart/solaar.desktop ships by default, so it autostarts from the next login.

Takeaways / checklist

  • Installing several apt packages on one line cancels the whole thing if any name is wrong — verify each program installed with its own command (which solaar).
  • udev permission rules aren't retroactive for an already-plugged-in device — if a freshly installed tool can't find a USB device, replug it.
  • Solaar's X11 key names can differ from the common spelling (the XF86_ underscore). If a rule doesn't fire, check the log first.
  • If you dislike the fixed step, call wpctl set-volume directly instead of faking the volume key, for any percentage you want.