Unofficial · for the Logitech G502 HERO · Linux

All of your G502 on Linux

An unofficial G HUB alternative: DPI levels and sniper, five onboard profiles, button remapping with G-Shift, macros, and lighting that follows your screen, your music and your games. Free, open source, and no Windows anywhere.

curl -fsSL https://g502hub.ahmedxsaad.me/install.sh | sh
Other ways to install

Screen sampler: the lights follow what's on your screen. Here, a demo film.

HERO 25K sensor

100 to 25,600 DPI

100200400800 16003200640012.8k25.6k 1 2 3 4 5 SNIPER DEFAULT
Lightsync

Lighting that watches with you

Effects saved on the mouse work anywhere. Live effects run from the tray and react to what's happening.

  • Screen sampler for films, videos and games, per zone: the whole screen, the center, or an edge.
  • Audio visualizer in pulse, spectrum or rainbow-beat style, from whatever is playing.
  • Color wave and DPI colors, so you always see which level you're on.
  • Fixed, breathing and color cycle stored in the mouse, with a color wheel and your own saved colors.
G502 HEROPROFILE 2: PROFILE 21600 DPI · LEVEL 3/4
The Lightsync page with the screen sampler selected
LIGHTSYNC · LIVE EFFECTS
Sensitivity

DPI you can feel

Drag a level on the track and the sensor follows while you drag.

  • Five levels from 100 to 25,600 in 50-DPI steps, with a default and a sniper level.
  • Report rate from 125 to 1000 Hz.
  • An on-screen popup shows the new DPI when you press G7 or G8.
G502 HEROPROFILE 2: PROFILE 21600 DPI · LEVEL 3/4
The Sensitivity page with four DPI levels on a track and the report rate at 1000 Hz
SENSITIVITY
Assignments

Eleven buttons, two layers

Hold G-Shift and every button does something else.

  • Any key combination, labelled for your keyboard layout: QWERTY, AZERTY, QWERTZ and the rest.
  • Mouse buttons, scrolling, DPI and profile controls, and media keys.
  • Macros recorded or built step by step: saved on the mouse, or run by the app to type text and repeat while held.
  • Everything is stored in the mouse, so it works on any computer.
G502 HEROPROFILE 2: PROFILE 21600 DPI · LEVEL 3/4
The Assignments page with the G6 sniper button selected
ASSIGNMENTS
Profiles

Five setups that live in the mouse

G9 switches between them, with or without the app.

  • Export a profile to a file and share it; import someone else's into any slot.
  • Rename, reorder the G9 cycle, copy, or reset a slot to factory.
  • A full backup of the mouse's memory before the first change of every session.
PROFILES
The Profiles page with five onboard slots
Games & apps

Rules that know what you're doing

The first rule that matches wins. When none does, your normal lighting and profile come back on their own.

WHENYouTube is playing→Red
WHEN“One Piece” is playing→Orange breathing, slot 3
WHENAny Steam game runs→Cover art colors, slot 1
WHENCounter-Strike 2 runs→Health, bomb, flashbangs
WHENmpv is in front→Screen sampler
G502 HEROPROFILE 2: PROFILE 21600 DPI · LEVEL 3/4
The Games and apps page with a YouTube rule active
GAMES & APPS
CS2 · DOTA 2

The game drives the lights

Through Valve's official Game State Integration: health on the logo, your team color on the DPI lights, a red beep that speeds up as the bomb counts down, a white flash for flashbangs. Set it up with one click.

PROTON · EXPERIMENTAL

LIGHTSYNC games, through Proton

Games like GTA V, Borderlands 3 or The Last of Us Part I talk to Logitech's lighting SDK. G502 Hub adds a small stand-in for it to that game's Proton prefix, so the game lights your mouse the way it does on Windows.

Safety

Built not to brick anything

  • Talks to the mouse over HID++ 2.0, the protocol G HUB uses, with no kernel driver and no root.
  • Backs up the whole onboard memory before the first change of a session, and every backup can be restored.
  • Writes only the user profile area, never the factory profiles, and reads every write back.
  • Keeps bytes it doesn't understand exactly as they were.
What a save does
Install

One line. Then plug in the mouse.

$ curl -fsSL https://g502hub.ahmedxsaad.me/install.sh | sh

Installs what it needs with your package manager (it asks for your password), adds the permission rule that lets your user talk to the mouse, and puts G502 Hub in your applications menu. Remove it with the same line plus -s -- --uninstall.

MouseLogitech G502 HERO, wired (USB 046d:c08b).
SystemBuilt on EndeavourOS with KDE Plasma 6 on Wayland. Fedora and Ubuntu: best effort.
Close Piperratbagd rewrites the mouse's G-Shift layer when it saves, so quit it first.
FAQ

Questions

Does it need Windows, Wine or G HUB?

No. G502 Hub is a native Linux app that talks to the mouse directly. Wine only comes in if you want Proton games to drive the lights.

Does anything leave my computer?

No. Screen and sound are analysed on your machine and never sent anywhere. The only download is the optional product photo of the mouse.

Will my settings work without the app?

Yes. DPI, buttons, report rate and the saved lighting live in the mouse's own memory, on Linux, Windows or a console. Live effects and rules need the app running, which it does quietly in the tray.

What about other G502 models?

Only the wired G502 HERO for now. If you have another G502 and want to help, open an issue with the info from the About page's "Copy for a bug report" button.

Macros?

Yes, two kinds. Saved on the mouse, a macro plays on any computer: keys, media keys, clicks, scrolling and waits. Run by G502 Hub, it can also type text in your keyboard layout, repeat while you hold the button, or toggle on and off. Record one by typing, or build it step by step.