Skip to content
GingerbreadforkPublic

About

Logitech MX Master 4 Linux software, an open-source Logi Options+ alternative: mouse button remapping, gestures, smooth scrolling and haptics. No account or telemetry. Not affiliated with Logitech.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Familiar

Open-source software for the Logitech MX Master 4 on Linux.
Remap the buttons, add gestures, tune the wheel and the haptic panel,
with no account, no cloud and no telemetry.

Latest release Build status Runs on Linux MIT license

The Familiar window: a drawing of the MX Master 4 seen from above, and beside it a list of what each part does, from the scroll wheel to the battery

A familiar is the small animal companion that serves a witch, and mice were the classic choice. This one serves the MX Master. Not affiliated with Logitech.

Why

Logi Options+ does not run on Linux. Without it the MX Master 4 still works as a mouse, but the haptic panel sends a button most apps ignore, the wheel scrolls a whole notch at a time over the Bolt receiver, and there is no built-in way to change any of it.

Familiar sets all of that up. A small daemon talks to the mouse over HID++, and a settings window and a command line tool tell it what you want. Settings live in one plain text file on your computer, and the mouse keeps working if the daemon stops.

What it does

The window is built around a drawing of the mouse, top and underneath. Pick a part and change what it does; changes apply as you make them. It follows your system's light or dark setting, drawn in the mouse's own Pale Grey or Graphite.

Buttons and gestures

The haptic panel's sheet in gestures mode: a click presses Super and a double-click switches to computer 2, with the panel outlined on the drawing

Six buttons can be given something else to do: the wheel click, back, forward, the gesture button, the shift button behind the wheel and the haptic panel. Each takes one action, or a set of gestures: click, double-click, press and hold, and hold while moving the mouse in four or eight directions. A toggle holds an action down until you click again, for anyone who finds holding a button hard.

An action can be a keyboard shortcut, a media key, a mouse button, a shell command, a pointer speed, a switch to another computer or a haptic pattern. A button set to another mouse button is remapped inside the mouse, so it works even when the daemon is not running. Nothing is sent while the screen is locked. See docs/buttons.md.

Scrolling

The scroll wheel's sheet: notch by notch or free spin, how hard a flick lets the wheel go, notch strength, and smooth scrolling with its speed

Choose ratchet or free spin, how hard a flick lets the wheel go, and how firm the notches feel. Smooth scrolling takes the wheel over and sends hi-res scroll events, so pages move in small steps. Over a Logi Bolt receiver that is the only way to get hi-res scrolling on Linux today.

The thumb wheel can scroll sideways at a speed you set, change the volume, zoom or switch tabs, and a light tap on it can run an action of its own. See docs/scrolling.md.

Haptics

The haptic panel's feel: a switch for tapping back, its strength, how firm a press it needs, and a button for each built-in pattern

Set how strongly the panel taps back and how firm a press it needs, and try each of the mouse's built-in patterns under your thumb. Any program can play one with familiar haptic completed, so a few lines of shell can buzz the mouse when a long command or a service finishes. See docs/haptic-hooks.md.

Pointer speed and computers

The underside of the mouse beside its three Easy-Switch computers, two of them paired and named The underside in Graphite beside the pointer speed, set to 1000 DPI

Underneath are the sensor and the Easy-Switch button. Set the pointer speed from 200 to 8000 DPI, and name the three computers the mouse remembers or send it to another one.

Quick, light and private

Measured on an MX Master 4 over Bolt:

  • Idle: 6.7 MiB of memory, 7 threads, no wakeups at all. CI fails the build if the daemon grows past 20 MiB or wakes more than 5 times in 10 s (scripts/resource-budget.sh).
  • After a reconnect, configured settings are back in about 50 ms when the mouse kept them and about 130 ms when three had reset. familiar status shows the latest figure.
  • No network for the daemon: the systemd unit allows only Unix and netlink sockets. Check with systemctl --user show familiard -p RestrictAddressFamilies.
  • The only thing that uses the network is the window, to ask GitHub whether a newer release exists. That can be switched off under About.

What it cannot do yet

  • Per-app profiles. There is one profile, used everywhere.
  • The Actions Ring.
  • Bluetooth is untested; development has been over a Logi Bolt receiver.
  • Windows. The protocol library is portable, the rest is Linux only so far.
  • Firmware updates.
  • Packages other than .deb and .rpm.

Install

Packages for each release are on the Releases page: a .deb for Debian and Ubuntu and an .rpm for Fedora, with a SHA256SUMS file alongside. They are built for x86_64.

sudo apt install ./Familiar_<version>_amd64.deb       # Debian, Ubuntu
sudo dnf install ./Familiar-<version>-1.x86_64.rpm    # Fedora

The package holds the daemon, the familiar command and the window, the udev rule that lets you reach the mouse without root, and a systemd user service. The daemon starts by itself from your next login. To start it straight away:

systemctl --user start familiard

After that Familiar keeps itself up to date. The window looks for a newer release when it opens and offers to install it under About. Every package is signed and the signature is checked before anything is installed; installing asks for your password, since it goes through the package manager.

From source

Access to /dev/hidraw* is needed. Installing the udev rule once is the only step that needs root; everything else runs as your user:

sudo cp packaging/udev/70-familiar.rules /etc/udev/rules.d/
sudo udevadm control --reload && sudo udevadm trigger

Then build, install to ~/.local/bin and start the daemon as a systemd user service. This needs a Rust toolchain and the udev development package (systemd-devel on Fedora, libudev-dev on Debian and Ubuntu):

packaging/install-user.sh

To install the Familiar window as well, which needs pnpm and the WebKitGTK development packages (webkit2gtk4.1-devel on Fedora):

packaging/install-user.sh --app

The window is a client of the daemon only: closing it changes nothing, and every change it makes lands in the same config file. A copy built this way does not update itself. To build the .deb and .rpm packages instead, run packaging/build-packages.sh.

The daemon runs under a systemd watchdog: if it ever stops responding, systemd restarts it. The service starts with graphical-session.target. GNOME and KDE Plasma reach that target on their own; on a window manager or compositor that does not, the daemon will not start at login until the session starts the target (for example through uwsm), or until you run systemctl --user start familiard from its startup commands.

If Solaar or Logi Options+ is running it may change settings back. familiar status warns when it sees one.

The config file

Settings live in ~/.config/familiar/config.toml; see packaging/config.example.toml. The daemon applies them whenever the mouse connects, wakes or comes back from another host, and picks up edits to the file straight away. include pulls in per-machine files, so one file kept in git can serve several computers, and every write the daemon makes keeps the previous version next to the file as .bak.

[device."B042"]
dpi = 1600
smartshift = 12

[profile.default.buttons]
back = "key:alt+left"
haptic = { tap = "key:super", up = "key:volumeup", down = "key:volumedown" }

[profile.default.scroll]
smooth = true

The command line

familiar status                   # what the daemon sees: devices, battery, settings
familiar get                      # current settings
familiar diff                     # config against the device
familiar set dpi 1600             # through the daemon this is saved to the config
familiar set haptic 60 --temporary
familiar set wheel free           # or ratchet
familiar set smartshift 12        # shift speed, or "off"
familiar set torque 50
familiar set force 4000           # thumb panel press threshold
familiar haptic                   # list waveforms
familiar haptic completed         # play one
familiar host 2                   # Easy-Switch to channel 2
familiar host --rename laptop     # rename the current channel
familiar undivert                 # put every control back to normal
familiar diagnostics              # one file for bug reports, sent nowhere
familiar reload                   # reread the config now
familiar list                     # receivers and paired devices
familiar dump                     # identity, features, every readable setting
familiar events --divert gesture --raw-xy --thumb

When familiard is running, get, set, haptic and host go through it. --direct talks to the device instead; the daemon will then put its own settings back the next time the device reconnects.

events temporarily routes the named controls to HID++ and prints what the mouse sends; everything is restored on exit. --json prints one object per line, see docs/events.md. If something was killed and left a button dead, familiar undivert puts it back, and the daemon does the same whenever it starts or stops.

The daemon's D-Bus API is described in docs/dbus.md, and what has been learned about the mouse itself is in docs/protocol/mx-master-4.md.

Working on it

cargo test                        # everything, against a simulated mouse
cargo clippy --all-targets
pnpm --dir gui install
pnpm --dir gui dev                # the window in a browser, with stand-in data
pnpm --dir gui tauri dev          # the window itself, talking to the daemon

No hardware is needed for the tests: familiar-hidpp includes a simulated mouse behind a receiver, and the daemon's tests run against it.

Releasing

Pushing a tag like v0.2.0 runs the release workflow, which runs the tests, builds the packages on Ubuntu 22.04 and attaches them to a GitHub release with their checksums. The tag has to match the version in Cargo.toml, gui/src-tauri/Cargo.toml, gui/src-tauri/tauri.conf.json and gui/package.json; scripts/check-version.sh tells you whether all four agree. Starting the workflow by hand builds the packages and keeps them with the run, without releasing anything.

The workflow signs the packages for the updater when the repository has a TAURI_SIGNING_PRIVATE_KEY secret, and then publishes latest.json, the feed installed copies read. pnpm --dir gui tauri signer generate -w ~/.config/familiar/updater.key makes a key; its public half lives in gui/src-tauri/tauri.conf.json, so a new key means installed copies have to be updated by hand once. gh secret set TAURI_SIGNING_PRIVATE_KEY < ~/.config/familiar/updater.key stores it. Without the secret the packages still build, but installed copies are not offered that release.

Layout

Path Purpose
crates/familiar-hidpp HID++ framing, feature discovery, typed features, call allowlist
crates/familiar-hidraw Linux hidraw transport
crates/familiar-core Settings model and config file
crates/familiar-client D-Bus client shared by the command line tool and the window
crates/familiard Daemon: applies settings, D-Bus API, notifications
crates/familiar-cli Command line tool
gui The Familiar window, Tauri and Svelte
docs/protocol What we have learned about the device
packaging udev rule, systemd units, desktop entry, example config

Safety

The hidpp crate refuses to call any function it does not know to be safe. Internal, hidden and firmware update features are never touched, even with dump --research.

License

MIT. The Barlow fonts bundled with the window are under the SIL Open Font License.

About

Logitech MX Master 4 Linux software, an open-source Logi Options+ alternative: mouse button remapping, gestures, smooth scrolling and haptics. No account or telemetry. Not affiliated with Logitech.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages