Piper: A GTK Application for Configuring Gaming Mice on Linux

What Piper Does and Who Uses It

Gaming mice sold on Windows typically include proprietary configuration software. On Linux, that software does not run, so users either accept factory defaults or resort to low-level utilities. Piper fills the gap by providing a GTK+ interface that reads and writes mouse configuration through the ratbagd DBus daemon. The user opens Piper, sees the mouse's available buttons, DPI steps, and lighting options, makes changes through the GUI, and writes them back to the device's onboard memory.

The target audience is Linux users with supported gaming mice who want a native, graphical configuration tool. Piper is not a universal mouse driver; it cannot add support for a device that libratbag does not already know about. The README is explicit on this point: the list of supported devices depends entirely on libratbag, and device protocols are reverse-engineered, so available features may not match the manufacturer's documentation.

Architecture: Piper as a Frontend to ratbagd

Piper does not communicate with the mouse hardware directly. It sends all configuration requests through ratbagd, the libratbag daemon, over DBus. This separation means Piper can be updated independently of the device protocol code, and changes to supported devices only require updating libratbag.

The README notes a consequence of this architecture: if ratbagd is not running on the system bus, Piper displays a mousetrap icon in the interface rather than the device configuration. This is the primary diagnostic indicator that something is wrong. The README lists three causes: ratbagd is not running, ratbagd needs to be updated to a newer version, or an unexpected error occurred.

Because Piper depends on ratbagd and libratbag, the README recommends that users running Piper from the git repository also run the git version of libratbag. This ensures that bug fixes in libratbag, which may be necessary for correct device behavior, are present in the installation.

Building and Installing Piper from Source

Piper uses the meson build system. The README gives the complete build sequence. Clone the repository, then initialize the build directory with a prefix for system-wide installation:

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

To compile and install:

ninja -C builddir
sudo ninja -C builddir install

The builddir name is configurable; it can be any directory. If dependencies are missing, the meson step will fail with an error listing what is needed. The Piper wiki covers how to install those dependencies on common distributions.

For development work, the repository provides a piper.devel binary that loads data files from the git directory rather than from the installed prefix. This means code changes take effect immediately without reinstalling:

ninja -C builddir
./builddir/piper.devel

The piper.devel binary still requires ratbagd to be running on the system bus. The build does not provide a mock ratbagd for offline development.

Code Quality and Test Infrastructure

Piper's Python code follows PEP8 using the black formatter. The pyproject.toml in the repository configures both black and ruff for linting. The ruff configuration enables several rule sets: pycodestyle, pyflakes, pyupgrade (for modern Python syntax), flake8-bugbear (common bugs), flake8-pie, flake8-return, pep8-naming (for exception class names), and flake8-simplify. Two rules are explicitly ignored: E501 (line length, because some lines cannot be shortened) and SIM105 (contextlib.suppress, because the maintainers prefer try-except constructs over the library approach).

The project targets Python 3.7 as its minimum version, as declared in both pyproject.toml (tool.black target-version) and the ruff configuration. This means Piper can run on distributions that ship an older Python, though modern Fedora, Debian, and Ubuntu releases all provide a compatible version.

To run the test suite before submitting a patch:

meson test -C builddir

Code formatting is checked as part of the test suite, so a patch with unformatted code will fail the tests. The README instructs contributors to run this check before submitting a pull request.

Limitations and Unsupported Scenarios

Piper's most significant limitation is device coverage. Because each gaming mouse protocol must be reverse-engineered and contributed to libratbag, many gaming mice have partial support or no support at all. The README acknowledges this: device-specific protocols have to be reverse-engineered, and the features available may vary compared to what the manufacturer advertises. A user who buys a mouse expecting full LED control may find that libratbag supports only DPI steps for that device.

Piper also has no fallback for running without ratbagd. There is no local configuration mode, no ability to import or export profiles as files independent of the daemon, and no simulation mode for testing the interface on a machine without a supported mouse. This makes development setup dependent on having the full daemon stack running.

Finally, Piper is a Linux-only application. Windows and macOS users must use the manufacturer's software or alternatives specific to those platforms. Piper has no plans documented in the README to support non-Linux operating systems.

Comparison with ratbagctl

ratbagctl is the command-line interface to the same ratbagd daemon that Piper uses. The difference is entirely in the interaction model. ratbagctl lets a user list devices, read and write profiles, and adjust DPI by name from a terminal without any graphical dependencies. Piper provides the same access through a point-and-click interface with visual representations of the mouse layout.

For users comfortable with command-line tools, ratbagctl is sufficient and adds no GTK dependency. For users who prefer a visual interface or who need to configure button mappings while looking at a diagram of the mouse, Piper is the more approachable option. Both tools produce the same result at the hardware level: configuration commands sent to ratbagd over DBus. The choice between them is purely about workflow preference.

Editorial conclusion

Piper is the right tool for Linux users who own a libratbag-supported gaming mouse and want a graphical interface for profile and button configuration without resorting to the ratbagctl command line. It is not suitable for devices not supported by libratbag, and it will not run if ratbagd is not active on the system bus. Before building from source, check the libratbag device list at github.com/libratbag/libratbag/tree/master/data/devices to confirm the target mouse is supported, because the protocol for each device is reverse-engineered and features may differ from what the manufacturer advertises.

Frequently asked questions

Official sources

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