KDE Peripherals

A KDE Plasma 6 system tray widget and a small user daemon for gaming mice and keyboards that have no native Linux configuration tool. It shows battery levels and lets you change DPI, polling rate, sensor options, button mapping and lighting without the vendor's Windows or web software.

Supported devices

Device	Connection	Features	Status
MADLIONS MAD R+ (Compx chip, 373b:1040 MAD 8K dongle)	2.4 GHz dongle	battery, voltage, DPI stages, polling rate up to 8 kHz, lift-off distance, sensor mode, motion sync, angle snapping, ripple control, sensor angle, debounce, button mapping, sleep timeout, long-distance mode, DPI indicator	tested
MAD R, MAD R Major, MAD R Major+ and other ATK/Compx mice	2.4 GHz dongle	same protocol	untested
Royal Kludge RK96 RGB (258a:0089)	USB cable	lighting effect, brightness, speed, colour, rainbow mode, lighting timeout, music visualization (follow the effect, spectrum, rainbow, pulse; reaction strength, tempo, inverted)	tested
Xbox, Steam Controller, DualSense and other gamepads	Bluetooth, receiver, USB	battery and connection state from the kernel (power_supply) or BlueZ, disconnect button for Bluetooth controllers	Xbox Wireless Controller over Bluetooth: untested
Logitech HID++ 2.0 devices	Unifying, Bolt, Lightspeed receivers, Bluetooth, USB	battery, firmware, DPI, polling rate, SmartShift, wheel mode, natural scrolling, thumb wheel direction, Fn inversion, Easy-Switch channel, KDE actions on the gesture, actions, mode shift, middle, back and forward buttons, gestures	MX Master 4 over Bluetooth: tested; receivers and other models untested

Devices marked untested show a banner in the widget with a link to report how they work.

Notes

• MAD R+: the dongle relays every request to the mouse. While the mouse sleeps only the last known values are shown; move the mouse to wake it up. Writes take effect immediately and are stored in the mouse. Factory reset, pairing and firmware update commands are never sent.
• RK96: the keyboard protocol is write-only, so current settings cannot be read back. The widget shows the last values set from it; changes made with Fn shortcuts on the keyboard are not visible. Only the wired connection carries configuration commands; over 2.4 GHz and Bluetooth the keyboard cannot be configured.
• Battery in Power and Battery: Plasma lists batteries known to UPower, which only reads BlueZ and kernel power supplies. For devices whose battery only the daemon knows (MAD R+, Logitech devices without the kernel driver) the system service peripherals-batteryd creates a virtual HID device through /dev/uhid with a fixed mouse or keyboard descriptor that never sends input, plus a battery report. The kernel turns it into a power supply and UPower shows it next to other devices. The service only accepts Set(id, name, kind, percent, charging) and Remove(id) over the system bus, removes devices when their owner disconnects, allows eight per caller and runs sandboxed with access to /dev/uhid only.
• RK96 music styles: By effect draws the music in the spirit of the selected lighting effect and in its colour (the custom colour or a rainbow): wave effects become a wave sped up by the bass, reactive effects spawn ripples on bass beats, Stars Twinkle sparkles with the treble, steady and breathing pulse with the loudness. Loudness, bass and treble each adapt to the current music, so the full brightness range is used at any volume. Reaction strength narrows that range, Tempo follows the music speeds animations up on loud passages, and Dim to the music inverts both: the keyboard is lit in silence and the music dims it.
• RK96 speed levels: stock firmware has five speeds. Setting speedLevels=9 in the [rk-0089] group of ~/.config/io.github.rodiada/peripheralsd.conf widens the slider to nine for keyboards running a firmware patched for nine levels; with stock firmware speeds above five would produce garbage.
• RK96 music visualization: the daemon records the default output with pw-cat (PipeWire) and streams per-key colours with the keyboard's non-saving command 06 00 at 20 frames per second. The keyboard drops back to its own effect about two seconds after the last frame and rewrites its settings in flash at that moment, so the daemon keeps streaming a dim idle frame during silence instead of stopping; flash is written once when the visualization is switched off. The capture stream is tagged like Plasma's own volume meter so it does not trigger the "microphone in use" indicator. Only the USB cable carries these commands; over Bluetooth and 2.4 GHz the radio module forwards nothing but the lock-key LEDs.
• Logitech buttons and gestures: a button with an action assigned is diverted over HID++ and the daemon runs the matching KDE global shortcut (Overview, desktop grid, show desktop, switching desktops, window actions, application launcher, KRunner, screenshots, media and volume). In Gestures mode the gesture button also diverts mouse movement while held: moving up, down, left or right, or pressing without moving, runs one of five actions. Diverting is not stored in the mouse, so the daemon applies it again after every reconnect; with the daemon stopped the buttons return to their defaults.
• Logitech receivers: with the kernel's hid-logitech-dj driver every paired device gets its own node and is handled like a directly connected one; without it the daemon talks to the receiver slots itself.
• Kernel driver: Bluetooth Logitech mice that the running kernel does not know yet end up on hid-generic, which ignores HID++ features such as high-resolution scrolling. The udev rule runs kde-peripherals-bind-driver, which loads hid-logitech-hidpp, registers the device ID and rebinds the mouse to it, falling back to hid-generic if that fails. After a kernel update the new modules are only usable after a reboot.
• Logitech: only features that cannot break input are exposed. Scroll events are never diverted to HID++, buttons are not remapped, and high-resolution scrolling is left alone: unless the kernel's hid-logitech-hidpp driver handles the device, turning it on makes the wheel scroll several times faster.

Installation

Packages

Every release ships packages for Arch Linux (.pkg.tar.zst), Debian 13 / Ubuntu (.deb) and Fedora (.rpm).

sudo pacman -U kde-peripherals-*.pkg.tar.zst     # Arch
sudo apt install ./kde-peripherals_*_amd64.deb   # Debian, Ubuntu
sudo dnf install ./kde-peripherals-*.rpm         # Fedora

Arch Linux from source

cd packaging/arch
makepkg -si

packaging/arch-git builds the latest commit.

Into your home directory

./install.sh      # builds into ~/.local; installs only the udev rule system-wide (asks for sudo)
./uninstall.sh

From source

cmake -B build -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
sudo cmake --install build
sudo udevadm control --reload
sudo udevadm trigger --subsystem-match=hidraw

Then enable "Mouse", "Keyboard" and "Gamepad" in the system tray settings. The daemon starts on demand through D-Bus activation.

The udev rule 70-kde-peripherals.rules grants the logged-in user access to the hidraw nodes of supported devices (uaccess tag). Nothing runs as root.

D-Bus API

Service io.github.rodiada.Peripherals, object /io/github/rodiada/Peripherals, interface io.github.rodiada.Peripherals:

• property Devices (string): JSON array of devices. Each entry has id, kind, vendor, name, transport, online, optional battery, charging, firmware, error, and a controls array describing the available settings (choice, toggle, slider, dpi, color, action).
• method Apply(id: s, change: s): applies a JSON object of {key: value} pairs, where keys are control keys from controls.
• method Rescan().

busctl --user get-property io.github.rodiada.Peripherals /io/github/rodiada/Peripherals \
    io.github.rodiada.Peripherals Devices

Tests

cmake -B build -DPERIPHERALS_TESTS=ON
cmake --build build
for t in build/*-test; do $t; done

References

Protocol facts were learned from the official ATK HUB web driver, the official Royal Kludge software, and open documentation of these protocols in libatk-rs, Linux-ATK, atk-tool, Rangoli, kludgeknight and Solaar. No code was copied from them.

Disclaimer

Not affiliated with MADLIONS, ATK, Royal Kludge or Logitech. Writing settings to devices is at your own risk.

License

MIT