Piper: a GTK frontend for configuring gaming mice through ratbagd

What Piper solves, and for whom

Gaming mice are usually configured with a vendor utility that exists only for Windows or macOS. On Linux the mouse still works, but resolution stages, button remapping and LED behaviour are whatever the firmware defaults to. Piper addresses that gap for Linux desktop users. It is a GTK application that presents resolution, button and LED pages for a connected mouse, and it is explicitly a frontend rather than a driver: the README states that Piper is merely a graphical frontend to the ratbagd DBus daemon. The audience is therefore narrow and specific. You need a Linux system with a running ratbagd, and you need a mouse that libratbag already knows how to talk to. Piper itself does not decide which devices work. The README points at the libratbag device files for the list of all known devices, and notes that the device-specific protocols usually have to be reverse-engineered, with features that may vary from what the manufacturer advertises. That sentence is the honest core of the project: this is community reverse engineering, and the feature set per mouse is whatever someone managed to decode.

How Piper talks to the mouse: GTK on top of ratbagd over DBus

The architecture is a three-layer chain. Piper is the top layer, a GTK interface written in Python. Below it sits ratbagd, a daemon that owns the actual device communication and exposes it over DBus. Below that sit the individual device protocols implemented in libratbag. Piper never touches the hardware directly, which explains nearly every behaviour a user will notice. Because the daemon is the middle layer, Piper cannot show you a device that ratbagd has not enumerated, and it cannot offer a setting that the libratbag protocol implementation does not expose. The README describes an error page, the mousetrap, that appears when ratbagd is not running, when ratbagd needs to be updated to a newer version, or when some other unexpected error occurs. The mousetrap is the single most useful diagnostic in the project, because it collapses the most common failure modes into one screen. The README also recommends that if you run Piper from git, you use libratbag from git as well, to make sure the latest bugfixes are applied. That is a direct consequence of the layering: a Piper build and a ratbagd build that are far apart in age can disagree about the DBus interface.

Installing Piper and configuring a mouse for the first time

The README does not put installation steps in the repository. It says to see the project wiki's Installation page for how to install Piper, and it points at the same wiki page for what to do when you encounter missing dependencies. So the distribution-specific route (your package manager, a Flatpak, or a distribution package) is documented outside the repository and is not reproduced here. What the README does document is building from git with the meson build system. The first block clones the repository and initializes the build directory with a prefix of /usr/:

git clone https://github.com/libratbag/piper.git
cd piper
meson builddir --prefix=/usr/

After that, building and installing are two ninja invocations. The README notes that builddir is just the build output directory and can be renamed:

ninja -C builddir
sudo ninja -C builddir install

For iterating on the code there is a special binary, piper.devel, which uses data files from the git directory instead of installed ones. The README says this removes the need to install Piper after every code change, while still requiring ratbagd on the system bus:

ninja -C builddir
./builddir/piper.devel

Once Piper starts, the first real use is to check that it lists your mouse at all. If you see the mousetrap instead, the README's own explanation applies: ratbagd is probably not running, or it is older than what Piper expects. Fix the daemon before touching anything in the UI. If you are contributing rather than just using, the README asks that you run the test suite before submitting changes:

meson test -C builddir

That suite includes a formatting check: Piper tries to conform to PEP8 using the black formatter, and the pyproject.toml in the repository sets target-version to py37 for both black and ruff.

Where Piper stops being the right tool

The most important limitation is stated plainly in the README and is easy to underestimate: Piper is merely a frontend, and the list of supported devices depends on libratbag. If your mouse is not in the libratbag device files, Piper has nothing to show you, and no amount of Piper configuration will change that. The reverse-engineering caveat compounds it. Because protocols are decoded by hand, two mice from the same vendor can have very different levels of support, and the README warns that available features may vary from the manufacturer's advertised features. A mouse whose box promises onboard profiles and sixteen lighting zones may expose three buttons and one LED zone in Piper. There is also a hard runtime dependency that makes Piper unsuitable for some setups: it needs ratbagd on the system bus. On a minimal system, a container, or a machine where you deliberately do not run system services, Piper will show the error page and nothing else. Finally, the repository is not a self-contained installation guide. The README defers installation and dependency troubleshooting to the wiki, so anyone who wants a single authoritative document inside the repository will not find one. That is a documentation gap, not a bug, but it shapes the support experience.

Piper against vendor utilities and against scripting ratbagd directly

The obvious alternative is the manufacturer's own configuration software. The difference is not just platform support. Vendor utilities typically bundle their own driver and their own device database, so installing one means installing a privileged component that the vendor controls and updates on its own schedule. Piper takes the opposite approach: the device knowledge lives in libratbag, an independent project, and Piper is a thin GTK layer over a DBus daemon. The trade-off is coverage. A vendor utility will support the vendor's newest mouse on day one; libratbag supports it only after someone reverse-engineers the protocol and adds a device file. The second alternative is not using Piper at all and driving ratbagd directly over DBus. Since Piper is only a frontend, anything it does is reachable through the daemon's interface, which makes sense for scripted or headless configuration where no GTK session exists. The difference in approach is convenience versus repeatability: Piper gives you a visual editor for a single machine, while talking to ratbagd directly lets you encode settings in a script. Piper does not attempt to be a configuration-management tool, and the README never suggests it is one.

Maintenance, build dependencies and the GPL-2.0 licence

The repository is not archived, and the last push was on 2026-08-12, which is recent enough that the codebase is being touched, though the README gives no release cadence and the repository has no published releases. The upgrade cost is dominated by the layering described earlier. Piper and libratbag are separate projects with separate release schedules, and the README explicitly recommends using libratbag from git when running Piper from git so that the latest bugfixes are applied. In practice that means a distribution upgrade can move ratbagd and Piper out of step, and the symptom is the mousetrap page rather than a clear version error. Budget for checking the ratbagd version whenever Piper misbehaves after an upgrade. On the build side, Piper uses meson and ninja, and the repository carries a pyproject.toml configuring black and ruff with a Python 3.7 target, so tooling is pinned to what the project actually supports rather than to the newest interpreter. Piper is licensed under GPL-2.0, with the full text in the COPYING file. That is a copyleft licence, which matters if you intend to redistribute a modified Piper or link it into a larger product; the README states the licence and points at COPYING rather than summarizing obligations. This is not legal advice, and anyone planning to redistribute should read COPYING and, where relevant, take their own advice.

Editorial conclusion

Piper is worth adopting if you already run Linux, your mouse appears in the libratbag device files, and you want resolution, button and LED settings in a GUI rather than through a vendor utility that does not ship for your distribution. Skip it if ratbagd is not running on the system bus, if your device is absent from libratbag's device list. Before installing, check the libratbag data/devices directory for your exact model and confirm which ratbagd version your distribution ships, because the mousetrap error page is the usual sign of a version mismatch.

Frequently asked questions

Official sources

1. Issues
2. libratbag/piper on GitHub
3. License: GPL-2.0
4. README