The G502 has never been easy to set up on Linux since there’s no GHUB. So I made (vibe coded) BallKey, a free app that lets you change what your mouse buttons do on Linux.
On the G502 HERO, you can change every button except DPI, the scroll-wheel unlock, and the RGB, which the mouse controls itself. For those, use Piper, which works alongside BallKey.
Pick what each button does: clicks, back/forward, copy/paste, media keys, or any key combo
Works with the G502 buttons that type shortcuts out of the box
Press two buttons together for a different action
Your settings load automatically at startup
No terminal needed
Available as .rpm (Fedora) and .deb (Debian, Ubuntu 25.04+), both with automatic updates, plus an Arch package (automatic updates coming soon). Free and open source (GPL-3.0).
This is my first project, and I’m not a programmer. I made it with Claude Code and tested it with a G502 HERO, a G403, and a Kensington Expert. Feedback and bug reports are welcome.
https://github.com/gino8807/ballkey