Skip to content

About

Advanced driver for G600 Logitech's mouse on linux, with profiles and advanced mapping

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

g600-linux

A small userspace driver and configurator for the Logitech G600 mouse on Linux: remap every button to shortcuts, media keys, macros, text, profile switches and more, with profiles that you edit in a graphical interface similar to Logitech Gaming Software (LGS).

Not affiliated with or endorsed by Logitech. Use at your own risk (see Safety).

Features

  • Remap the 17 programmable buttons (G3, G4, G5, G7–G20) to: keyboard shortcuts (Ctrl+W, Alt+F4…), media keys, mouse functions, scroll left/right, DPI controls, multi-key macros (with or without delays), typed text, profile/set switching.
  • A new profile automatically copies G3, G4, G5, G7 and G8 from the first profile of the set (change the list with "copy_on_new_profile" in config.json).
  • Click = one key, double click = another on the same button (for example click = Ctrl, double click = Shift).
  • A software G-Shift layer: assign "G-Shift" to any button to get a second layer of actions.
  • Sets of profiles: as many sets as you like, each with 1–12 profiles (the mouse itself only has 3 LED modes).
  • Import LGS XML profiles (whole profile as a new set, or one mode into the current profile).
  • A notice with the profile name and a dot in the LED colour when you switch profile (system notification by default, or an overlay popup, or off) and a tray icon to open the configurator or switch sets/profiles.
  • Live feedback: hovering a button on the mouse picture (or its label) highlights both, clicking the picture opens the editor, and pressing a button on the real mouse lights it up in the window.
  • Left click, right click and wheel click are never intercepted: the mouse keeps working if the daemon is stopped.
  • Everything is stored on the PC (~/.config/g600/config.json); only the LED colours live in the mouse.

How it works

g600 apply rewrites the mouse's button table once so that each programmable button sends a unique, harmless key (F13–F24 and a few unused keys). The daemon (g600 run, a systemd service) grabs those keys from the mouse's keyboard interface and replays the action you configured through a virtual keyboard/mouse (uinput). The GUI edits config.json; the daemon reloads it on the fly. Hardware access uses the mouse's HID feature reports directly (same protocol as libratbag).

Requirements

  • Linux with systemd, Python 3.8+, python-evdev, GTK 3 with PyGObject.
  • Developed on Linux Mint 22.3 Cinnamon (X11), also used on KDE Plasma and Fedora with a G600 (USB id 046d:c24a). Other distros are untested. On KDE the tray icon needs gir1.2-ayatanaappindicator3-0.1 (installed by install.sh).

Install

git clone https://github.com/ktex/g600-linux.git && cd g600-linux
sudo bash install.sh

install.sh installs the dependencies with your package manager, copies the program to /opt/g600, adds the g600 and g600-gui commands, a menu entry, a tray autostart entry and the systemd service.

Distribution Packages installed
Debian, Ubuntu, Linux Mint (apt) python3-evdev python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-gdkpixbuf-2.0 librsvg2-common libnotify-bin
Fedora (dnf) python3-evdev python3-gobject python3-cairo gtk3 gdk-pixbuf2 librsvg2 libnotify
Arch, openSUSE supported but untested
Anything else install the equivalents yourself, then sudo bash install.sh --no-deps

For a tray icon, also install an AppIndicator library (gir1.2-ayatanaappindicator3-0.1 on Debian-based systems, libayatana-appindicator-gtk3 on Fedora); Cinnamon uses XApp instead. The installer tries both.

If Piper/libratbag (ratbagd) is installed, stop it so it does not write to the mouse at the same time:

sudo systemctl mask --now ratbagd        # undo with: sudo systemctl unmask ratbagd

Stopping and restarting

g600-gui --quit                      # or: pkill -f 'g600[-_]gui'   (the process is called g600-gui)
sudo systemctl stop g600             # stop the daemon (the mouse's programmed buttons then do nothing)
sudo systemctl start g600; g600-gui --tray &      # start everything again

The version is shown under the window title; it must match the daemon's (sudo bash install.sh updates both).

First-time setup

  1. (Optional) import an LGS profile: g600 import-xml MyProfile.xml (or later from the GUI).
  2. sudo g600 apply — programs the mouse. It saves the original configuration, writes each of the three profiles, verifies them, then asks you to test left/right click on each profile. Answer n (or press Ctrl+C) at any time to roll back automatically.
  3. sudo g600 calibrate — press each of the 17 buttons once, in any order. It prints the Logitech name of each button (G3, G9…).
  4. sudo systemctl enable --now g600 — starts the daemon now and at every boot.
  5. Start the interface: g600-gui (also in the application menu). A tray icon starts at login.

Button names

Names follow Logitech's numbering: G1 left, G2 right, G6 wheel click (these three are never remapped), G3 the button next to the right click (the old "G-Shift"), G4/G5 wheel tilt left/right, G7/G8 the two buttons behind the wheel, G9–G20 the thumb grid. Note that LGS XML files number them differently (Button3 = wheel, Button6 = G-Shift button); the importer converts this for you.

Using the interface

  • Pick a set at the top, a profile in the left list (rename, add, remove, choose its LED colour).
  • Click a button label next to the mouse picture to open the Command Editor: Mouse function, Keystroke (click the box and press your keys, or choose a preset), Multikey macro (record), Text.
  • Use the Layer switch to edit the Base or G-Shift layer.
  • Use this set on the mouse makes a set active; Apply LED colours writes the colours of the first three profiles of the active set to the mouse (one solid colour each, black = off). This writes to the mouse memory, so do not do it in a loop.

Shortcuts such as Alt+F4 or Super+D are intercepted by the window manager while you record them; use the presets for those.

Configuration file

~/.config/g600/config.json — edited by the GUI, but plain JSON:

{
  "layout": "azerty",
  "calibration": {"KEY_F13": "G4"},
  "active_set": "Games",
  "sets": {
    "Games": {
      "profiles": [
        {"name": "FPS", "color": [255, 0, 0],
         "buttons": {
           "G9":  {"normal": {"type": "keys", "keys": ["KEY_LEFTCTRL", "KEY_C"]}},
           "G3":  {"normal": {"type": "layer"}},
           "G7":  {"normal": {"type": "dual", "single": ["KEY_LEFTCTRL"], "double": ["KEY_LEFTSHIFT"]}}
         }}
      ]
    }
  }
}

Action types: keys, dual, mouse, scroll, dpi (up/down/cycle/default/shift), layer, profile (next/prev/n), set (next/prev), macro (down KEY_X, up KEY_X, tap KEY_X, wait MS, text ...), text. Keys are physical key positions (evdev names), so a shortcut recorded on your layout works on that layout. layout (azerty or qwerty) is only used for typed text.

Safety

apply only rewrites the button table (bytes 31–90 of each profile). LED colours, DPI and the mouse's own G-Shift layer are left untouched. During development the mouse was found to ignore or garble writes to the end of its profile memory, so the tool verifies every write and refuses to continue (restoring the original) when the read-back differs. sudo g600 restore puts the original configuration back at any time (it is saved in ~/.config/g600/original_backup.json). sudo g600 probe runs a step-by-step write test on an inactive profile if you want to check your unit.

Troubleshooting

  • Clicks dead after apply: run sudo g600 restore, then open an issue with the output of sudo g600 probe.
  • calibrate says "unexpected key": your kernel maps the unused keys differently; please report the key name.
  • The window cannot save / changes come back after a reboot: ~/.config/g600 was owned by root (a bug of version 0.2.0). Run sudo chown -R $USER ~/.config/g600 or re-run sudo bash install.sh. Errors of the interface are logged in ~/.config/g600/gui.log.
  • A key combination (for example Ctrl+X) does not work anywhere, even with g600 stopped: it is not g600. Check desktop shortcuts and remapping tools: grep -rn "Ctrl+X" ~/.config/kglobalshortcutsrc ~/.config/khotkeysrc and pgrep -a 'xbindkeys|sxhkd|autokey|espanso|keyd|kmonad|xremap|input-remapper'. To see what the kernel receives from your keyboard: sudo g600 keytest.
  • Tray icon missing / disappears when the terminal is closed: start it with g600-gui --tray (it detaches itself) or log out and in (autostart entry in ~/.config/autostart).
  • Tray icon missing: the GUI falls back to a window; install gir1.2-ayatanaappindicator3-0.1 or, on GNOME, the AppIndicator extension.
  • No notice when switching profile: the notice is sent by g600-gui; make sure it is running (g600-gui --tray &). Without it the daemon falls back to notify-send. The style (system, overlay, off) is in the menu next to the set selector. The overlay popup is X11 only.
  • "Daemon not reachable" / the buttons do nothing: the service is installed but not started. Run sudo systemctl enable --now g600 (the interface also tells you this in a yellow bar).
  • calibrate finds fewer than 17 buttons: run g600 status to see which ones are missing and which key each should send; press the missing buttons again with sudo g600 calibrate.
  • Check the daemon: sudo systemctl status g600, journalctl -u g600 -f.
  • Fedora / SELinux: if the daemon starts but sees nothing, look for denials with sudo ausearch -m avc -ts recent and report them.
  • New home folder, mouse already programmed: apply will warn that no original backup exists; just run sudo g600 calibrate again (the mouse keeps its programming).

Limitations

  • Only the G600 (046d:c24a) is supported.
  • Wheel click, left click and right click cannot be remapped (they stay native on purpose).
  • Only three LED colours exist in the mouse; sets with more than three profiles reuse them.
  • The mouse stops running actions when the daemon is stopped (the programmed buttons send unused keys).
  • Not implemented: LED animations, per-application profile switching, DPI value editing.

Credits and license

  • Code: GPL-2.0-or-later, see LICENSE.
  • data/logitech-g600.svg (the mouse picture) comes from the Piper project, which is licensed under the GPL v2; it is included unmodified and keeps that license.
  • Hardware protocol knowledge from the libratbag G600 driver (MIT).
  • Not affiliated with or endorsed by Logitech. "Logitech" and "G600" are trademarks of their owners and are used here only to describe the supported hardware.

About

Advanced driver for G600 Logitech's mouse on linux, with profiles and advanced mapping

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages