Deadband — a Linux configuration app for controllers and mice

A Linux GUI for gaming input devices, driven over each device's vendor (hidraw) interface (or vendor-class USB for the G7 Pro, G7 SE and Kaleid). Currently supports the GameSir Cyclone 2, G7 Pro, G7 Pro 8K PC, G7 SE and Tarantula Pro 8K controllers, the GameSir Kaleid (lighting only) and the Logitech G502 X LIGHTSPEED mouse (see Tested hardware); the protocol modules are per-vendor (vendors/gamesir, vendors/logitech), so other manufacturers can be added alongside.

The configurable models offer:

• Live input view — sticks, triggers, all buttons (incl. the L4/R4/M/Home/ Share extras), D-pad, battery + charging, firmware version, and a mode warning.
• Profiles — pick the profile you're editing (three on G7 SE, four on other models); a dot marks the one the controller is actually running. Reset a profile to its defaults.
• Lighting — on the Cyclone 2 and Kaleid: per-light RGB, captured effect presets, brightness/speed and a custom keyframe animation editor (add/remove keyframes, randomize; play/pause on the Cyclone 2), with four lights on the Cyclone 2 and two (left/right) on the Kaleid. The Cyclone 2 adds audio-reactive / pick-up-to-wake / sleep timeout. On the G7 Pro 8K: ring effect and brightness, home-ring quadrant colours, sleep timer and dock light. Lighting edits wait for Save; picking a lighting profile and Restore default lighting act straight away.
• Config editor — deadzones and anti-deadzones (drag, or type exact values), stick trajectory, sensitivity curves (presets and a draggable custom-curve editor), trigger tuning (hair-trigger + response curve), vibration with per-motor tests, poll rate, and button remap — plus Continuous Trigger (tap to hold, tap to release) on the Cyclone 2. Edits wait in a pending bar until Save to Profile, which reads every change back to confirm it landed.
• Gamepad macros — a per-button sequence editor with per-step hold/delay timing: L4/R4, plus L5/R5 on the 8K and all nine programmable buttons on the Tarantula.
• Motion / gyro (G7 Pro, G7 Pro 8K PC, Cyclone 2, Tarantula Pro 8K) — activation, axis setup, deadzones, output routing and response curves; controls adapt to each model's register layout.
• Backup / Restore — snapshot all 4 profiles + lighting to a JSON file and write it back later.
• Mouse-mode toggle — turn KDE/KWin's gamepad-drives-the-cursor behaviour off (normal gamepad) or on (sticks-as-cursor "couch mode") from the app, plus a non-KDE EVIOCGRAB fallback (Wayland; see Status).
• Logitech G502 X mouse — button remaps and keyboard bindings (with the G-Shift second layer and an assignable G-Shift trigger), 5-stage DPI + polling-rate editor, and an onboard-macro editor (build sequences or record them from your keyboard with live timing) — edits stage into a queue and apply in one verified write.
• Mouse profiles — all five onboard profiles: pick which one you're editing, name them, switch which one the mouse runs, and restore any of them to the mouse's own factory copy.
• Demo mode — preview one of each supported controller in software, no hardware connected.
• Diagnostics — a built-in doctor that pinpoints permission, udev, and hidapi-backend problems, and shows each controller's USB link speed and vendor channel, with a copy-paste report for bug reports (see Something not working?).

Every page wears your palette — six built-in theme presets (and full custom colors). The gallery below rotates through five pages, each in a different theme; click it (or the caption link) to step through them one at a time:

Browse the screenshot tour ▶

Version: 0.7.0-dev — Deadband: multi-device (Cyclone 2 + G7 Pro + G7 SE + G7 Pro 8K PC + Tarantula Pro 8K + Kaleid controllers, G502 X mouse), the full Qt/QML app (lighting + keyframe editor, config editor, remaps, macros, backup/restore), built-in diagnostics, one-command install, an AUR package, and a community NixOS flake. Tracks main (the AUR -git package builds from the latest commit); last tagged snapshot is v0.6.0. Going deeper? The Manual is the user guide — how to use each feature, troubleshooting & recovery, and an FAQ. RESEARCH.md is the developer side — protocol, architecture, the diagnostic tools, and per-controller findings. RELEASING.md is the release checklist. See also CONTROLLER_MAP.md (what each control reports to Linux) and TODO.md (roadmap + open questions).

This is a spare-time project. I am one person, so fixes land when they land. It isn't careless with your hardware, though: every config write is backed up first and read back to verify, and the app refuses to write to a device it can't positively identify. Fork it and customize it however you like.

⚠️ Tested hardware

Everything here has been developed and verified on a GameSir Cyclone 2, a GameSir G7 Pro (Amazon edition), a GameSir G7 Pro 8K PC, a GameSir Tarantula Pro 8K, and a Logitech G502 X LIGHTSPEED mouse. Other editions listed below were verified by their owners.

The G7 Pro 8K PC comes in several editions that are the same controller under different USB ids: Nioh (3537:10c7 wired, 3537:10c8 dongle — my own pad), Royal2 (1032/1033, added by its owner @kakxem), Championship (10b7 wired, 10b9 dongle, verified by its owner), Aimlabs (10c5/10c6, recognised from a user report) and the newer plain black units (1034 wired, 1035 receiver, from owners' reports; earlier thought to be the Phantom Blade 0 edition). Those need a kernel setting on Linux to stay in XInput mode; see the Manual.

The G7 SE (3537:1010, firmware descriptor 6.30) supports L4/R4 gamepad remapping in three profiles and controller-wide 250/500/1000 Hz report-rate settings, with staged Save, verified readback and rollback. On firmware 6.64 (3537:1069, its Xbox GIP identity) it is configured like a G7 Pro without gyro: every button's remap, sticks, triggers, hair trigger, grip and trigger vibration, report rate and Backup & Restore. 6.64 only reaches 1069 when the PC firmware enumerates it first (plug it in at the boot menu); a hot-plugged pad falls back to 3537:1082. See G7 SE support.

The Tarantula Pro 8K is configured in its PC mode, 3537:103d: rebinds for all nine extra buttons (L4, R4, C1–C4, T1–T3), macros, sticks, triggers, gyro and poll rate. Lighting isn't supported yet. If it shows up as 3537:103c instead, it has auto-detected a different platform; GameSir's manual switches it to PC mode with Home + X held for 2 seconds.

G7 Pro support was contributed by @brcly and verified on their hardware rather than mine. It covers the Shadow Ember edition (3537:109b wired, 3537:109c dongle), the Amazon edition (3537:10ba wired, 3537:10bb dongle — my own pad, write-tested on both) and the White Trimode (3537:1003 wired, 3537:1004 on its charging dock — confirmed by an owner whose settings read back exactly as set on Windows). The Wuchang Edition (3537:10a7 wired, firmware 5.41) was contributed and hardware-tested by its owner, @sinchrotron: configuration reads, saved paddle remaps, Aim/Tilt register round-trips, live gyro/accel readings, gyro aiming through the right stick, input-range sensitivity, and independent tests of all four vibration motors. The separate 3537:10a8 identity remains input-only: no configuration response was confirmed. Wireless configuration is not enabled for this edition. Deadband moves the transitional 3537:100a identity to a configuration one automatically; if the pad is showing 3537:1022 instead, hold SHARE + MENU (☰) together — note this also resets the active profile's remaps and the Shift layer.

The Kaleid is an Xbox-licensed pad, and it is lighting only. It does not answer the GameSir hidraw vendor protocol the other models use — that collection is present on it but vestigial — so Deadband reaches it the way its own Windows app does: the same GameSir register protocol tunnelled through Xbox GIP. Lighting turned out to be the Cyclone 2's engine, byte for byte: the pad's four stored records hold palettes identical to this project's captured Cyclone presets, matching on keyframe count and speed too. So the Kaleid gets the full keyframe editor, without the slot selector, power block or play/pause, which it doesn't have.

It has three USB identities, cycled with M + Xbox: 3537:1082 (DirectInput), 3537:1086 (XInput) and 3537:1012 (Xbox/GIP). Only 1012 is configurable; in the other two the app names the pad and asks for the chord rather than reporting a protocol error. One thing worth knowing: editing lighting claims the pad, so it leaves games for the duration (there's a Release button, as on the G7 Pro). Releasing hands it straight back to games; it stays in its Xbox mode.

Its profile banks are deliberately not editable. They read cleanly and decode against the G7 Pro's register map, but no write to them has ever been confirmed on the hardware, and resembling a mapped device isn't evidence about this one. Picking a profile stays an on-pad job (M + Y/B/A/X) — the vendor's profile-select command turned out to corrupt this pad's profile-to-lighting link, so Deadband refuses to send it.

Not the T4 Kaleid (3537:1004), which is a different, older product; see the note below.

The G7 Pro ships in editions that differ only by USB product ID. The Zenless Zone Zero edition (3537:105e) is recognised but not configured yet; input works and the app says so rather than failing silently.

White Trimode on its dock shows up as a "T4 Kaleid". 3537:1004 is also the T4 Kaleid's ID in the Linux kernel's xpad driver, so the kernel names the pad "GameSir T4 Kaleid" and talks to it with the wrong protocol, and games get no input from it in that mode (#14). Nothing about the pad itself has changed. On the cable (3537:1003) it should work normally, since the kernel only mislabels 1004. Deadband only treats 1004 as a G7 Pro when the device names itself one, so a real T4 Kaleid is never touched. Other GameSir controllers, other Logitech mice, other dongles, and firmware revisions I haven't seen are unsupported and untested and may misbehave. The app won't send config writes to a device it can't positively recognize, but please don't treat it as proven-safe on hardware it has never seen. Use it at your own risk.

The app

deadband.py — the Qt/QML app (PySide6): a polished, KDE-native UI over the reverse-engineered core, with a live controller render, per-zone RGB + keyframes, stick/trigger curves, button remap, macros, vibration, backup/restore, and a mouse-mode toggle. A device picker in the header switches between your controllers and the G502 X, which gets its own Buttons / DPI / Macros tabs.

Install

Deadband needs Python 3 with PySide6 and hidapi — built with its hidraw backend. G7 Pro configuration uses Deadband's native system libusb-1.0 transport and needs no additional Python package. Each route below takes care of the dependencies unless noted.

Arch Linux

Install deadband-git from the AUR:

yay -S deadband-git      # or: paru -S deadband-git

It's a -git package, so it always builds the latest commit. To build without an AUR helper, use the included packaging/PKGBUILD:

cd packaging && makepkg -si

NixOS

Use the community flake by Epaphroditus — gamesir-linux-tools-nix. Its NixOS module sets up the udev permissions declaratively and builds hidapi with the hidraw backend. To try it without installing:

nix run codeberg:Epaphroditus/gamesir-linux-tools-nix

Any distro (installer script)

SteamOS / Steam Deck: skip step 1 and go straight to step 2 — don't use pacman or pip here. install.sh detects SteamOS and sets Deadband up in a private Python environment in your home folder (it survives SteamOS updates and changes no system package). It reuses the HID library SteamOS already ships, so nothing needs compiling; the only download is the PySide6 UI toolkit.

1. Install the dependencies. On Arch: sudo pacman -S --needed python pyside6 python-hidapi libusb. Elsewhere, install your distribution's libusb-1.0 runtime, then:

   pip install --user PySide6
   HIDAPI_WITH_HIDRAW=1 pip install --user --no-binary :all: hidapi

   HIDAPI_WITH_HIDRAW=1 matters: pip's source build otherwise selects the libusb backend, which can't open the devices. Building needs gcc, the Python headers, and libudev (Fedora/Bazzite: systemd-devel; Debian/Ubuntu: build-essential python3-dev libudev-dev). If your distro packages pyhidapi (python-hid on Arch, PyPI hid) instead, that works too and needs no build.

2. Clone and install:

   git clone https://github.com/broroeror/gamesir-linux-tools.git
   cd gamesir-linux-tools
   ./install.sh

install.sh installs to your home directory (~/.local) and verifies your hidapi backend. The only privileged step is the optional one-time udev rule — the script shows the exact commands and asks first; declining still installs the app, it just can't reach the controller until the rule is in place. Afterwards Deadband is in your app launcher (or run deadband). To remove it, run ./uninstall.sh. Upgrading from the old gamesir-cyclone2 install? install.sh cleans it up, and your settings carry over on first run.

macOS (early)

Deadband now runs on macOS too, from source for the moment. It's been tested on Apple Silicon with a Cyclone 2, a Tarantula Pro 8K and a G502 X. The three-command setup and what differs from Linux are in docs/macos.md.

Running

Put the controller in Xbox / XInput mode (on the Tarantula Pro 8K, PC mode: Home + X for 2 seconds). A G7 Pro at 3537:100a is switched automatically to its configuration identity. If it is at 3537:1022, hold SHARE + MENU (☰) together — note this also resets the active profile's remaps and the Shift layer. The app's header warns when it detects an unsupported mode, and the diagnostics report says which mode a controller is in.

Grant device access (recommended, once):

1. From the repo directory, install the udev rule — it's scoped to GameSir's USB vendor id, nothing else:

   sudo cp 70-gamesir.rules /etc/udev/rules.d/
   sudo udevadm control --reload-rules && sudo udevadm trigger

2. Unplug and replug the controller once, then start the app:

   python3 deadband.py

To configure the G502 X mouse, install its rule the same way (the app's mouse page also shows these commands):

sudo cp packaging/udev/70-deadband-g502x.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

To verify access: getfacl /dev/hidraw0 should show a user:<you>:rw- line.

How the rule works:

• It uses TAG+="uaccess", which grants access to the user logged in at the local desktop.
• The 70- filename prefix matters: udev applies the uaccess ACL in 73-seat-late.rules, so a rule numbered 73 or higher sets the tag too late and access is silently never granted.
• On a headless box with no local seat, uaccess doesn't apply — use MODE="0660", GROUP="input" instead and add yourself to that group.

Fallback — run as root. Without the rule, the hidraw nodes are root-owned:

sudo python3 deadband.py

Under sudo, ~ resolves to /root, so backups land there — another reason to prefer the udev rule.

Something not working?

Open Settings → Help & Diagnostics in the app, or run deadband --doctor in a terminal (works over SSH). The doctor checks whether the app can actually open your devices — the classic failure is a controller that's detected but never connects — and names the exact problem: a missing or un-applied udev rule, a Python hidapi built with the libusb backend, and so on, with fix commands for your distro (NixOS included). Use Copy report to paste the result into a GitHub issue. The app shows the same guidance in a banner whenever it finds a device it can't open.

If an issue asks for it, deadband --doctor --probe adds a few read-only questions to the devices themselves (close Deadband first): a G502 X's firmware and profile checksums, and whether an unsupported GameSir controller answers the protocol the supported ones use. It never changes a setting.

Safety

Short version: this app changes controller settings, not firmware, and everything it does is reversible and stays on your machine. The specifics:

• What it writes. Edits go to the controller's config registers — deadzones, curves, button remaps, vibration, poll rate, and lighting — over the vendor channel, the same settings the official app changes. They're ordinary config, not firmware — nothing here touches the bootloader.
• Nothing is written until you Save. Edits wait in the pending bar; Discard throws them away. On the Cyclone 2, G7 Pro 8K, Tarantula and Kaleid, Save first records the current values in a recovery file, then writes, reads every change back, and puts the old values back automatically if any write fails. Lighting goes through the same Save. (Macros are the exception: they're written as you edit them, and the page says so.)
• Back up before you experiment. Backup / Restore → Export snapshots all four profiles + lighting to a JSON file; Restore writes it back. Take one before you start changing things and you can always return to a known-good state. Restore is write-verify-retry and reports a clear pass/fail. Imported backups are validated against the controller's known register map before any write, so a hand-edited or corrupt file can't drive writes to arbitrary registers.
• Reversibility. Every setting the editor exposes can be set back the same way it was changed. The worst realistic outcome of experimenting is a profile that feels wrong — fixed by Restore, re-editing, or the controller's own factory-default reset.
• Xbox / XInput mode only. The vendor protocol is inert in PS4/DS4 and Switch modes — there the app can't reach the controller, so it can't change anything. Use the Start / pause buttons for Xbox mode (the header warns you when you're not in it).
• No network. No telemetry, no account, no phone-home — it's all local USB. Even the firmware version is read straight from the USB descriptor, not fetched online.
• Permissions. Prefer the udev rule (per-user uaccess) over running as root — see Running. Under sudo, ~ is /root, so backups land there.
• Tested hardware. Cyclone 2, G7 Pro (Amazon edition, wired 3537:10ba and dongle 3537:10bb), G7 Pro 8K PC (Nioh edition), Tarantula Pro 8K (3537:103d) and the G502 X are verified here. Other G7 Pro editions were verified by their owners: Shadow Ember (109b/109c, @brcly), Wuchang (10a7, @sinchrotron) and White Trimode (1003/1004). The G7 Pro 8K PC Royal2 and Championship editions were added by their owners. Zenless Zone Zero (105e) is recognised but not configured. Treat anything not listed as unproven and use it at your own risk.

How it works

Most supported controllers expose a vendor HID interface (USB VID 0x3537) with a 64-byte command channel. The G7 Pro's wired and dongle configuration identities instead use a vendor-class USB interface that Deadband temporarily claims from xpad; use Release to games when configuration is finished. While claimed, its report 0x10 carries live sticks, triggers, buttons and battery alongside chunked configuration replies. The hidraw controllers use their enhanced report 0x12. Firmware information is read locally from either the USB descriptor or the G7's documented device-info query — never from the network.

For what each control reports to Linux as a normal gamepad, see CONTROLLER_MAP.md. The full command set, the lighting/keyframe register encoding, the app's architecture, and the per-controller findings (including the G7 Pro) live in RESEARCH.md.

File layout

The app is split into focused modules — the connect/read loop, the shared state, the command channel, and the lighting/config/backup domains. That structure and the research/ diagnostic scripts are documented in RESEARCH.md (Architecture + Methodology & tools). One-off probes and the pre-refactor monolith live in archive/.

Status

Working: live input, battery, firmware readout, Xbox-mode warning, profile read/switch, rumble, full per-light RGB + effect presets + lighting power settings, a custom keyframe animation editor (1–8 frames, play/pause), a config editor (deadzones, anti-deadzones, stick trajectory + sensitivity curves incl. a draggable custom-curve editor, trigger tuning, vibration, poll rate), button remap, per-paddle gamepad macros (read-back-verified writes), motion/gyro, Continuous Trigger, and backup / restore — all verified end-to-end on hardware. Restore is write-verify-retry. A profile only accepts writes while it's the active one, so Save switches to the profile you're editing and back, and Export / Restore walk each profile in turn, confirming every switch; all four are writable.

Tarantula Pro 8K: rebinds for all nine programmable buttons, macros, sticks, triggers, gyro and poll rate up to 8000 Hz, in its PC mode (3537:103d). Decoded from USB captures and verified on my own pad. Lighting isn't supported yet.

G7 Pro: contributed by @brcly, with the Wuchang edition and gyro support from @sinchrotron, and verified on my own Amazon edition too (see Tested hardware). Configuration identities per edition, with automatic transition from 3537:100a; four editable profiles, 21 default-layer remap sources, stick/trigger shaping, resolution/inversion/sensitivity, four-motor vibration, report rate, D-pad options, dock settings, and semantic backup/restore. The Vibration tab can test the big left grip motor, small right grip motor, left trigger and right trigger individually at their slider strengths. Tests run for 400 ms, stop explicitly and never save profile settings. The G7 Pro's standard GIP motor packet addresses all four channels; trigger tests require configuration access. Aim/Tilt gyro configuration includes hold/press/always-on activation, rotation axes, inversion, stick/mouse/button output, X/Y balance, deadzones, button bindings and overlap area. For stick output, Sensitivity (input range) compresses the input span by lowering the upper deadzone endpoint: higher values give stronger response and reach maximum stick output sooner. The displayed multiplier is relative to the full input span with the same lower deadzone, not a separate sensor gain. It preserves the lower deadzone, curve, anti-deadzone and X/Y balance, and stays in sync with the Deadzone range control. Edits wait for Save to Profile; Discard restores the previous range. No independent overall gyro-gain register has been confirmed for this model. Endpoint geometry follows the captured Nexus protocol; the exact motion-to-aim response still depends on the firmware and game. The Motion tab also displays live gyroscope and accelerometer X/Y/Z readings as signed raw counts while the controller is claimed for configuration. The display clears when reports stop or the controller is released to games. Gyro writes were read-back verified locally on wired 3537:10a7 (firmware 5.41), using an inactive profile and then restoring every profile and dock byte. Named curves use G7 Pro's captured presets; Custom selects the shape already stored in the controller. Custom gyro point editing is not implemented. Backups include gyro settings; restoring a Custom gyro curve with different stored points is refused before any settings are written. If a profile's gyro settings block is blank (seen on an Amazon edition), the first gyro edit fills in the whole block with defaults, since the firmware ignores single settings written into a blank block. The shared Shift layer, Continuous Trigger, advanced directional/mouse stick output, Bluetooth, and the native 3537:1022 protocol are not yet exposed.

Mouse (G502 X): remaps, keyboard bindings, the G-Shift layer + trigger, DPI stages, report rate, and the onboard-macro editor are verified on hardware — including keystroke recording with live timing, macros long enough to chain across several flash sectors, and the scroll / media / F13–F24 step types. Because flash can't be rewritten in place, re-assigning a macro strands its old sector; an apply now sweeps stranded sectors automatically, so editing a button's macro costs no net slots (there's a manual sweep on the Macros tab too). Macro playback runs slightly slower than recorded — the mouse's macro engine spends a little time per step, which the per-macro speed control offsets.

Mouse profiles: all five onboard profiles are verified on hardware — picking which one you're editing (which costs no device write, so you can edit a profile you aren't currently using), renaming, switching the profile the mouse runs, and restoring one to the mouse's own factory copy in ROM. A restore is around a hundred device reads and writes, so it takes a few seconds with the controls disabled while it runs; the toast says what it's doing.

Mouse-mode gotcha (KDE Plasma 6.7): after a dongle replug, the sticks may start driving the desktop cursor — that's KWin's Game Controller plugin reading the joystick node directly, not the controller emulating a mouse. Turn it off:

kwriteconfig6 --file kwinrc --group Plugins --key gamecontrollerEnabled false
qdbus6 org.kde.KWin /KWin reconfigure   # or log out/in

The app also has an in-app Stop mouse mode toggle (desktop-agnostic fallback); see Troubleshooting for the full picture.

The config register map (banks, offsets, remap records, the inferred RT block) and the open items — verifying the RT block, some remap target codes, profile-switch sync, PS4/Switch input parsing — live in RESEARCH.md and TODO.md.

Support

Deadband is free and will stay that way. If it's been useful to you, you can buy me a coffee on Ko-fi. Entirely optional, and bug reports and controller details help just as much.

License & disclaimer

Released under the MIT License — use, modify, and redistribute freely.

The G7 Pro integration was informed by the hardware-tested protocol research in questionablesyntax/g7ctl, whose standalone pyg7 protocol package is Apache-2.0 licensed. Deadband's Qt/QML UI and transport integration are independent; no GPL GUI code is included.

This is an independent, hobby reverse-engineering project. It is not affiliated with, endorsed by, or supported by GameSir, and "GameSir" and "Cyclone 2" are trademarks of their respective owners. The protocol was reverse-engineered for interoperability, and the repository contains no vendor firmware or USB captures. Provided as is, without warranty — you use it, and poke at your controller, at your own risk.