{"id":48817304,"url":"https://github.com/packerlschupfer/pulsar-mouse-linux","last_synced_at":"2026-06-14T05:00:59.773Z","repository":{"id":347584021,"uuid":"1193155761","full_name":"packerlschupfer/pulsar-mouse-linux","owner":"packerlschupfer","description":"Linux configuration tool for Pulsar gaming mice (X2A, X2H, Xlite, and more)","archived":false,"fork":false,"pushed_at":"2026-06-13T02:14:32.000Z","size":320,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T04:12:40.359Z","etag":null,"topics":["cli","gaming-mouse","gtk4","hid","libadwaita","linux","pulsar","pulsar-mouse","pulsar-x2a","pulsar-x2h","pulsar-xlite","python","reverse-engineering"],"latest_commit_sha":null,"homepage":"https://discord.gg/vbNaQRQ4cs","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/packerlschupfer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T23:43:49.000Z","updated_at":"2026-06-13T02:14:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/packerlschupfer/pulsar-mouse-linux","commit_stats":null,"previous_names":["packerlschupfer/pulsar-mouse-linux"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/packerlschupfer/pulsar-mouse-linux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Fpulsar-mouse-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Fpulsar-mouse-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Fpulsar-mouse-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Fpulsar-mouse-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/packerlschupfer","download_url":"https://codeload.github.com/packerlschupfer/pulsar-mouse-linux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Fpulsar-mouse-linux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34309655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","gaming-mouse","gtk4","hid","libadwaita","linux","pulsar","pulsar-mouse","pulsar-x2a","pulsar-x2h","pulsar-xlite","python","reverse-engineering"],"created_at":"2026-04-14T12:03:21.068Z","updated_at":"2026-06-14T05:00:59.767Z","avatar_url":"https://github.com/packerlschupfer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"data/pulsar-mouse.svg\" alt=\"Pulsar Mouse Linux\" width=\"128\"\u003e\n\u003c/p\u003e\n\n# pulsar-mouse-linux\n\nLinux configuration tool for **Pulsar gaming mice**.\n\nPlugin architecture — each mouse model has its own protocol driver.\nCurrently supports the **Pulsar X2A Medium Wired**, **Pulsar X2H Wired Medium**, and **Pulsar X2A Wireless**.\n\nReverse-engineered from USB HID captures of Pulsar Fusion on Windows 11.\nWireless (Nordic) protocol based on [python-pulsar-mouse-tool](https://github.com/andrewrabert/python-pulsar-mouse-tool) by andrewrabert.\n\n## Screenshots\n\n| Global \u0026 Profile Settings | DPI Stages \u0026 Button Bindings |\n|:---:|:---:|\n| ![Global Settings](screenshots/01-global-settings.png) | ![DPI \u0026 Buttons](screenshots/02-dpi-buttons.png) |\n\n| Desktop Settings \u0026 Test | Input Test Dialog | System Tray |\n|:---:|:---:|:---:|\n| ![Desktop Settings](screenshots/03-desktop-settings.png) | ![Input Test](screenshots/04-input-test.png) | ![Tray](screenshots/05-tray.png) |\n\n## Supported Mice\n\n| Model | Driver | VID:PID | Status |\n|---|---|---|---|\n| Pulsar X2A Medium Wired | `x2a` | `3710:1404` | Fully supported |\n| Pulsar X2H Wired Medium | `x2h` | `3710:1403` | Fully supported |\n| Pulsar Xlite v4 | `xlite_v4` | `3710:3401` | Untested (same Sonix protocol as X2A) |\n| Pulsar X2A Wireless / X2 V2 Mini | `nordic` | `3554:f507` `3554:f508` | Supported (Nordic chipset, battery status) |\n\nWant to add support for your mouse? See [Adding a new driver](#adding-a-new-driver) below.\n\n## Requirements\n\n**Debian / Ubuntu:**\n```bash\nsudo apt install python3-usb python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 gir1.2-dbusmenu-glib-0.4\n```\n\n**Fedora:**\n```bash\nsudo dnf install python3-pyusb python3-gobject gtk4 libadwaita libdbusmenu\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S python-pyusb python-gobject gtk4 libadwaita libdbusmenu-glib\n```\n\nOn GNOME you also need the AppIndicator shell extension for the tray icon to appear:\n```bash\nsudo apt install gnome-shell-extension-appindicator   # Debian/Ubuntu\n# then enable it (Ubuntu):\ngnome-extensions enable ubuntu-appindicators@ubuntu.com\n# or on other distros:\ngnome-extensions enable appindicatorsupport@rgcjonas.gmail.com\n```\nThen restart GNOME Shell (log out/in, or Alt+F2 → r → Enter on X11).\n\nKDE Plasma supports the system tray natively — no extra extensions needed.\n\n## Installation\n\n### Option 1: Package (.deb / .rpm)\n\nDownload from the [latest release](https://github.com/packerlschupfer/pulsar-mouse-linux/releases):\n\n```bash\n# Debian / Ubuntu\nsudo dpkg -i pulsar-mouse-linux_*.deb\n\n# Fedora\nsudo dnf install ./pulsar-mouse-linux-*.noarch.rpm\n```\n\n### Option 2: AppImage (any distro, no install)\n\n```bash\nchmod +x pulsar-mouse-linux-*-x86_64.AppImage\n./pulsar-mouse-linux-*-x86_64.AppImage          # GUI\n./pulsar-mouse-linux-*-x86_64.AppImage --cli     # CLI\n```\n\nBundles Python + pyusb. The GUI still needs system GTK4/libadwaita installed.\nudev rules must be installed separately (see below).\n\n### Option 3: Tarball (any distro)\n\n```bash\ntar xzf pulsar-mouse-linux-*.tar.gz\ncd pulsar-mouse-linux-*\nsudo ./install.sh\n```\n\n### Option 4: From git\n\n```bash\ngit clone https://github.com/packerlschupfer/pulsar-mouse-linux\ncd pulsar-mouse-linux\npip install --user -e .\n```\n\n### udev rules (run without sudo)\n\nPackages install udev rules automatically. For git installs:\n\n```bash\nsudo cp udev/50-pulsar-mouse.rules /etc/udev/rules.d/\nsudo udevadm control --reload-rules \u0026\u0026 sudo udevadm trigger\nsudo groupadd -f plugdev \u0026\u0026 sudo usermod -aG plugdev $USER   # re-login after this\n```\n\n## GUI + System Tray\n\n```bash\npulsar-mouse-gui    # if installed via .deb\n# or: PYTHONPATH=src python3 -m pulsar_mouse.gui\n```\n\nGTK4 + libadwaita settings window with integrated system tray:\n- Auto-detects connected Pulsar mouse and adapts UI to its capabilities\n- Reads all settings from the mouse on startup, writes on **Apply**\n- System tray via D-Bus StatusNotifierItem (no GTK3 conflict)\n- Tray shows DPI/polling rate on change, quick DPI presets, polling rate radio buttons\n- **X** hides the window (tray stays alive), **Quit** from tray menu exits\n- \"Start on Login\" toggle in the tray menu for autostart\n- Input test dialog with mouse diagram and event log\n- Desktop mouse settings (GNOME acceleration profile, pointer speed)\n\n## CLI usage\n\n```\n# Show all settings (auto-detects mouse)\nsudo pulsar-mouse\n\n# Show one profile\nsudo pulsar-mouse --profile 1\n\n# Polling rate (global)\nsudo pulsar-mouse --poll 1000      # 125 / 250 / 500 / 1000\n\n# Debounce (global, ms)\nsudo pulsar-mouse --debounce 3\n\n# Switches (global: on/off)\nsudo pulsar-mouse --angle-snap off\nsudo pulsar-mouse --ripple off\nsudo pulsar-mouse --motion-sync off\n\n# DPI stages for profile 1 (up to 6 stages)\nsudo pulsar-mouse --profile 1 --dpi 400,800,1600,3200\nsudo pulsar-mouse --profile 1 --dpi 400,800,1600,3200 --active-stage 2\n\n# Lift-off distance (per-profile)\nsudo pulsar-mouse --profile 1 --lod 1    # 1 mm or 2 mm\n\n# LED brightness and effect (per-profile)\nsudo pulsar-mouse --profile 1 --brightness 200\nsudo pulsar-mouse --profile 1 --led steady\nsudo pulsar-mouse --profile 1 --led breath --breath-speed 50\n\n# Per-stage LED colour (per-profile, RGB 0-255)\nsudo pulsar-mouse --profile 1 --stage-color 1 255 0 0    # stage 1 = red\n\n# Button remapping (per-profile)\nsudo pulsar-mouse --profile 1 --button thumb1 dpi+\nsudo pulsar-mouse --profile 1 --button thumb1 ctrl+c\n```\n\n## Adding a new driver\n\nEach Pulsar mouse model uses a different USB protocol. To add support for a new model:\n\n1. Create `src/pulsar_mouse/drivers/yourmodel.py`\n2. Subclass `PulsarDevice` from `pulsar_mouse.base`\n3. Define `capabilities` as a class variable (a `DeviceCapabilities` dataclass)\n4. Implement the protocol methods (`open`, `close`, `get/set_polling_rate`, `get/set_dpi_stages`, etc.)\n5. Add an entry point in `pyproject.toml`:\n   ```toml\n   [project.entry-points.\"pulsar_mouse.drivers\"]\n   yourmodel = \"pulsar_mouse.drivers.yourmodel:YourClass\"\n   ```\n6. Add udev rules for the new VID/PID in `udev/50-pulsar-mouse.rules`\n\nThe CLI and GUI will automatically detect the new driver and adapt their UI.\n\nExternal driver packages can also register via entry points without modifying this repo.\n\n## OS Tweaks for Gaming\n\nThe GUI has a \"Desktop Mouse Settings\" section for GNOME, but you can also\napply these from the command line or set them at the OS level.\n\n### Disable mouse acceleration (recommended for FPS gaming)\n\n```bash\n# GNOME / Wayland / X11\ngsettings set org.gnome.desktop.peripherals.mouse accel-profile 'flat'\n\n# Reset pointer speed to neutral (0 = no modification)\ngsettings set org.gnome.desktop.peripherals.mouse speed 0\n```\n\n### Kernel boot options (advanced)\n\nFor lowest possible input latency, add to `/etc/default/grub` in\n`GRUB_CMDLINE_LINUX_DEFAULT`:\n\n```\nusbhid.mousepoll=1    # 1ms USB polling (default is 10ms for non-gaming mice)\n```\n\nThen run `sudo update-grub \u0026\u0026 reboot`.\n\n\u003e **Note:** The mouse already reports `bInterval=1` so the kernel should\n\u003e honour 1ms polling by default with most USB controllers. This option is\n\u003e only needed if you suspect the kernel is overriding the interval.\n\n## Protocol notes (X2A)\n\n| Setting | Scope | cat | reg (write/read) | sub |\n|---|---|---|---|---|\n| Polling rate | global | 0x01 | 0x09 / 0x89 | 0x02 |\n| Debounce | global | 0x04 | 0x03 / 0x83 | 0x03 |\n| Angle snap | global | 0x07 | 0x04 / 0x84 | 0x02 |\n| Ripple control | global | 0x07 | 0x03 / 0x83 | 0x02 |\n| Motion sync | global | 0x07 | 0x05 / 0x85 | 0x02 |\n| LOD | per-profile | 0x07 | 0x02 / 0x82 | 0x03 |\n| DPI stages (bulk) | per-profile | 0x05 | 0x04 / 0x84 | 0x21 / 0x15 |\n| DPI active stage | per-profile | 0x05 | 0x01 / 0x81 | 0x02 |\n| Stage LED colour | per-profile | 0x05 | 0x05 / 0x85 | 0x05 |\n| Brightness | per-profile | 0x03 | 0x03 / 0x83 | 0x03 |\n| LED effect | per-profile | 0x03 | 0x04 / 0x84 | 0x0F |\n\nPacket: 64 bytes, Interface 3, HID Feature report (wValue=0x0300).\nChecksum: bytes[62:64] = LE uint16(sum(bytes[0:62])).\n\n## Credits\n\n- [@Scout339](https://github.com/Scout339) — Logo design, wireless mouse testing\n- [andrewrabert](https://github.com/andrewrabert) — [python-pulsar-mouse-tool](https://github.com/andrewrabert/python-pulsar-mouse-tool), reference implementation for the Nordic wireless protocol\n\n## Related Projects\n\n- [python-pulsar-mouse-tool](https://github.com/andrewrabert/python-pulsar-mouse-tool) — Linux tool for the Pulsar X2 V2 Mini (wireless, battery support)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpackerlschupfer%2Fpulsar-mouse-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpackerlschupfer%2Fpulsar-mouse-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpackerlschupfer%2Fpulsar-mouse-linux/lists"}