packerlschupfer/pulsar-mouse-linux

# pulsar-mouse-linux **Pulsar 游戏鼠标**的 Linux 配置工具。 插件架构 —— 每款鼠标型号都有其独立的协议驱动。 目前支持 **Pulsar X2A Medium 有线版**、**Pulsar X2H Wired Medium** 和 **Pulsar X2A 无线版**。 通过在 Windows 11 上对 Pulsar Fusion 的 USB HID 捕获进行逆向工程获得。 无线（Nordic）协议基于 andrewrabert 开发的 [python-pulsar-mouse-tool](https://github.com/andrewrabert/python-pulsar-mouse-tool)。 ## 截图 | 全局与配置文件设置 | DPI 阶段与按键绑定 | |:---:|:---:| |  |  | | 桌面设置与测试 | 输入测试对话框 | 系统托盘 | |:---:|:---:|:---:| |  |  |  | ## 支持的鼠标 | 型号 | 驱动 | VID:PID | 状态 | |---|---|---|---| | Pulsar X2A Medium Wired | `x2a` | `3710:1404` | 完全支持 | | Pulsar X2H Wired Medium | `x2h` | `3710:1403` | 完全支持 | | Pulsar Xlite v4 | `xlite_v4` | `3710:3401` | 未经测试（与 X2A 使用相同的 Sonix 协议） | | Pulsar X2A Wireless / X2 V2 Mini | `nordic` | `3554:f507` `3554:f508` | 已支持（Nordic 芯片组，支持电池状态） | 想要为你的鼠标添加支持？请查看下方的[添加新驱动](#adding-a-new-driver)。 ## 依赖要求 **Debian / Ubuntu:** ``` sudo apt install python3-usb python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 gir1.2-dbusmenu-glib-0.4 ``` **Fedora:** ``` sudo dnf install python3-pyusb python3-gobject gtk4 libadwaita libdbusmenu ``` **Arch Linux:** ``` sudo pacman -S python-pyusb python-gobject gtk4 libadwaita libdbusmenu-glib ``` 在 GNOME 上，你还需要安装 AppIndicator Shell 扩展才能显示托盘图标： ``` sudo apt install gnome-shell-extension-appindicator # Debian/Ubuntu # 然后启用它 (Ubuntu)： gnome-extensions enable ubuntu-appindicators@ubuntu.com # 或在其他发行版上： gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com ``` 然后重启 GNOME Shell（注销/登录，或者在 X11 下按 Alt+F2 → r → 回车）。 KDE Plasma 原生支持系统托盘 —— 无需额外扩展。 ## 安装说明 ### 方式 1：软件包（.deb / .rpm） 从[最新发布版本](https://github.com/packerlschupfer/pulsar-mouse-linux/releases)下载： ``` # Debian / Ubuntu sudo dpkg -i pulsar-mouse-linux_*.deb # Fedora sudo dnf install ./pulsar-mouse-linux-*.noarch.rpm ``` ### 方式 2：AppImage（适用于任何发行版，无需安装） ``` chmod +x pulsar-mouse-linux-*-x86_64.AppImage ./pulsar-mouse-linux-*-x86_64.AppImage # GUI ./pulsar-mouse-linux-*-x86_64.AppImage --cli # CLI ``` 自带 Python + pyusb。GUI 仍然需要系统已安装 GTK4/libadwaita。 udev 规则必须单独安装（见下文）。 ### 方式 3：压缩包（适用于任何发行版） ``` tar xzf pulsar-mouse-linux-*.tar.gz cd pulsar-mouse-linux-* sudo ./install.sh ``` ### 方式 4：从 git 安装 ``` git clone https://github.com/packerlschupfer/pulsar-mouse-linux cd pulsar-mouse-linux pip install --user -e . ``` ### udev 规则（免 sudo 运行） 软件包会自动安装 udev 规则。对于 git 安装方式： ``` sudo cp udev/50-pulsar-mouse.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules && sudo udevadm trigger sudo groupadd -f plugdev && sudo usermod -aG plugdev $USER # re-login after this ``` ## GUI + 系统托盘 ``` pulsar-mouse-gui # if installed via .deb # 或者：PYTHONPATH=src python3 -m pulsar_mouse.gui ``` GTK4 + libadwaita 设置窗口，集成系统托盘： - 自动检测已连接的 Pulsar 鼠标，并根据其功能调整 UI - 启动时读取鼠标的所有设置，在点击**应用**时写入 - 通过 D-Bus StatusNotifierItem 实现系统托盘（与 GTK3 无冲突） - 托盘在设置更改时显示 DPI/回报率，并提供快速 DPI 预设和回报率单选按钮 - 点击 **X** 隐藏窗口（托盘保持运行），通过托盘菜单的**退出**可关闭程序 - 托盘菜单中提供“开机自启”开关，用于实现自动启动 - 带有鼠标示意图和事件日志的输入测试对话框 - 桌面鼠标设置（GNOME 加速配置、指针速度） ## CLI 用法 ``` # 显示所有设置（自动检测鼠标） sudo pulsar-mouse # 显示一个 profile sudo pulsar-mouse --profile 1 # 轮询率（全局） sudo pulsar-mouse --poll 1000 # 125 / 250 / 500 / 1000 # Debounce（全局，毫秒） sudo pulsar-mouse --debounce 3 # Switches（全局：开/关） sudo pulsar-mouse --angle-snap off sudo pulsar-mouse --ripple off sudo pulsar-mouse --motion-sync off # profile 1 的 DPI 阶段（最多 6 个阶段） sudo pulsar-mouse --profile 1 --dpi 400,800,1600,3200 sudo pulsar-mouse --profile 1 --dpi 400,800,1600,3200 --active-stage 2 # Lift-off 距离（按 profile） sudo pulsar-mouse --profile 1 --lod 1 # 1 mm or 2 mm # LED 亮度和效果（按 profile） sudo pulsar-mouse --profile 1 --brightness 200 sudo pulsar-mouse --profile 1 --led steady sudo pulsar-mouse --profile 1 --led breath --breath-speed 50 # 按阶段的 LED 颜色（按 profile，RGB 0-255） sudo pulsar-mouse --profile 1 --stage-color 1 255 0 0 # stage 1 = red # Button 重映射（按 profile） sudo pulsar-mouse --profile 1 --button thumb1 dpi+ sudo pulsar-mouse --profile 1 --button thumb1 ctrl+c ``` ## 添加新驱动 每款 Pulsar 鼠标型号都使用不同的 USB 协议。要为新型号添加支持： 1. 创建 `src/pulsar_mouse/drivers/yourmodel.py` 2. 继承 `pulsar_mouse.base` 中的 `PulsarDevice` 3. 将 `capabilities` 定义为类变量（一个 `DeviceCapabilities` dataclass） 4. 实现协议方法（`open`、`close`、`get/set_polling_rate`、`get/set_dpi_stages` 等） 5. 在 `pyproject.toml` 中添加 entry point： [project.entry-points."pulsar_mouse.drivers"] yourmodel = "pulsar_mouse.drivers.yourmodel:YourClass" 6. 在 `udev/50-pulsar-mouse.rules` 中为新 VID/PID 添加 udev 规则 CLI 和 GUI 将自动检测新驱动并自适应其 UI。 外部驱动包也可以通过 entry points 进行注册，而无需修改本仓库。 ## 针对游戏的系统优化 GUI 中有一个针对 GNOME 的“桌面鼠标设置”部分，但你也可以从命令行应用这些设置，或将其配置在操作系统级别。 ### 禁用鼠标加速（推荐用于 FPS 游戏） ``` # GNOME / Wayland / X11 gsettings set org.gnome.desktop.peripherals.mouse accel-profile 'flat' # 将指针速度重置为中性（0 = 不修改） gsettings set org.gnome.desktop.peripherals.mouse speed 0 ``` ### 内核启动选项（高级） 为了获得尽可能低的输入延迟，请将其添加到 `/etc/default/grub` 的 `GRUB_CMDLINE_LINUX_DEFAULT` 中： ``` usbhid.mousepoll=1 # 1ms USB polling (default is 10ms for non-gaming mice) ``` 然后运行 `sudo update-grub && reboot`。 ## 协议说明 (X2A) | 设置 | 作用域 | cat | reg (写入/读取) | sub | |---|---|---|---|---| | 回报率 | 全局 | 0x01 | 0x09 / 0x89 | 0x02 | | 消抖 | 全局 | 0x04 | 0x03 / 0x83 | 0x03 | | 角度吸附 | 全局 | 0x07 | 0x04 / 0x84 | 0x02 | | Ripple 控制 | 全局 | 0x07 | 0x03 / 0x83 | 0x02 | | 运动同步 | 全局 | 0x07 | 0x05 / 0x85 | 0x02 | | LOD | 每个配置文件 | 0x07 | 0x02 / 0x82 | 0x03 | | DPI 阶段（批量） | 每个配置文件 | 0x05 | 0x04 / 0x84 | 0x21 / 0x15 | | DPI 激活阶段 | 每个配置文件 | 0x05 | 0x01 / 0x81 | 0x02 | | 阶段 LED 颜色 | 每个配置文件 | 0x05 | 0x05 / 0x85 | 0x05 | | 亮度 | 每个配置文件 | 0x03 | 0x03 / 0x83 | 0x03 | | LED 效果 | 每个配置文件 | 0x03 | 0x04 / 0x84 | 0x0F | 数据包：64 字节，接口 3，HID Feature report (wValue=0x0300)。 校验和：bytes[62:64] = LE uint16(sum(bytes[0:62]))。 ## 鸣谢 - [@Scout339](https://github.com/Scout339) —— Logo 设计、无线鼠标测试 - [andrewrabert](https://github.com/andrewrabert) —— [python-pulsar-mouse-tool](https://github.com/andrewrabert/python-pulsar-mouse-tool)，Nordic 无线协议的参考实现 ## 相关项目 - [python-pulsar-mouse-tool](https://github.com/andrewrabert/python-pulsar-mouse-tool) —— Pulsar X2 V2 Mini 的 Linux 工具（支持无线、电池状态）

标签：GTK4, Python, USB HID, 云资产清单, 外设配置, 无后门, 游戏鼠标, 逆向工具, 逆向工程