HttpKiwi/GameGent

# GameGent — GameSir Tarantula Pro CLI 原生 Linux 工具，通过 USB HID 配置 GameSir Tarantula Pro 控制器。 无需 Windows VM，无需专有 DLL。 核心 HID I/O 使用 Python 3。Web UI / 桌面应用还需要 Flask、 React (Node) 以及可选的 pywebview（见下文桌面应用）。 ## 快速开始 ``` ./install.sh # ~/.local/bin/gamegent + .desktop entry python3 -m venv venv && ./venv/bin/pip install -r requirements.txt gamegent status # Read current controller state gamegent read-mappings # Read onboard button remaps gamegent rumble --fire 100 --duration 500 ``` ### Udev 规则（避免使用 sudo） `/etc/udev/rules.d/99-gamesir.rules`： ``` KERNEL=="hidraw*", ATTRS{idVendor}=="3537", ATTRS{idProduct}=="103e", MODE="0666" ``` 然后执行：`sudo udevadm control --reload-rules && sudo udevadm trigger` ## 命令 ### 状态 ``` python3 main.py status # Human-readable state python3 main.py status --json # JSON export python3 main.py status --raw # Include raw register dumps ``` ### 震动 ``` python3 main.py rumble --set 80 --right 60 # Set grip rumble level python3 main.py rumble --fire 100 # Burst both motors python3 main.py rumble --fire 100 --fire-right 50 --duration 1000 ``` ### 灯光 ``` # 模式 python3 main.py light off|static|breathing|colorful|rainbow|radar \ --brightness 80 --speed 50 # 面板 LED python3 main.py color 0 # Red (hue 0-360°) python3 main.py led panel 240 # Blue panel python3 main.py led home 120 # Green home button # ABXY 布局 python3 main.py layout xbox python3 main.py layout switch ``` ### 面键 LED ``` # 4 个同时 python3 main.py face all --a-hue 0 --b-hue 120 --x-hue 240 --y-hue 60 # 单个按键（通过 config cache 保持其他按键） python3 main.py face a 0 python3 main.py face b 120 python3 main.py face x 240 python3 main.py face y 60 # Home 按钮 LED python3 main.py face home 200 python3 main.py led home 200 # same thing ``` ### 摇杆 ``` # 模式 python3 main.py stick left native --circle --deadzone-min 5 --curve linear python3 main.py stick right mouse --x-sens 60 --mouse-dpi 75 # 带 WASD 的 Keyboard mode python3 main.py stick left keyboard --overlap 65 \ --kbd-up 26 --kbd-down 22 --kbd-left 4 --kbd-right 7 # Clone mode python3 main.py stick left clone # 曲线 python3 main.py stick left native --curve expo --curve-intensity 60 python3 main.py stick left native --curve s-curve --deadzone-min 10 --deadzone-max 80 ``` 模式：`native | mouse | keyboard | clone` 曲线：`linear | expo | s-curve` ### 陀螺仪 / 体感瞄准 ``` # Mouse aim，长按激活 python3 main.py gyro mouse --motion aim --method hold --button c1 --axis yaw # Tilt wheel，常开 python3 main.py gyro mouse --motion tilt --method always --button rb # 带自定义方向键的键盘输出 python3 main.py gyro keyboard --motion aim --method hold --button lt \ --overlap 70 --kb-up key:w --kb-down key:s \ --kb-left key:a --kb-right key:d # 灵敏度、死区、曲线、反转 python3 main.py gyro mouse --x-sens 75 --y-sens 60 \ --deadzone-min 10 --deadzone-max 80 \ --antideadzone-min 5 --antideadzone-max 90 \ --curve expo --curve-intensity 60 \ --invert-x --invert-y ``` 输出模式：`mouse | left_stick | right_stick | keyboard` 体感模式：`aim | tilt` 触发方式：`off | hold | press | always` 轴：`yaw | roll | global` 激活按键：`c1 c2 c3 c4 t1 t2 t3 l4 r4 a b x y lb lt l3 rb rt r3 back start` 键盘方向目标：`key:X`（scancode）、`mouse:scroll_up`、`controller:lt`、`unbind` ### 按键重映射 ``` gamegent map c1 key:enter # C1 → Enter key gamegent map l4 controller:a # L4 → A button gamegent map r4 mouse:left_click # R4 → left click gamegent map t1 unbind # T1 → disabled # 读取当前存储在控制器上的 remaps gamegent read-mappings # Human-readable gamegent read-mappings --json # JSON {source: target} gamegent read-mappings --raw # Include raw HID response packets ``` 源按键：`c1 c2 c3 c4 t1 t2 t3 l4 r4`（读取时包含面键/肩键 ID） 目标：`key:X`、`controller:X`、`mouse:X`、`unbind` 板载重映射可通过 `07 05 05 02 00 [button_index]` 读取（参见 [`doc/remapping.md`](doc/remapping.md) 和 [`doc/hex_protocol.md`](doc/hex_protocol.md))。 面键的身份映射 (`a→a`) 以及原生报告 `14 01` 将被视为未映射。 ### 配置 ``` python3 main.py config --show # Show full config python3 main.py config --set stick_left.mode=keyboard python3 main.py config --get stick_left.deadzone_min ``` ## 按键参考 **可重映射的源按键**（额外的背部按键）： | 名称 | Hex | 名称 | Hex | |------|------|------|------| | l4 | 0x24 | r4 | 0x25 | | t1 | 0x26 | t2 | 0x27 | | t3 | 0x28 | c1 | 0x29 | | c2 | 0x2a | c3 | 0x2b | | c4 | 0x2c | | | **目标控制器按键**（面键、肩键等）： | 名称 | Hex | 名称 | Hex | |--------|------|----------|------| | a | 0x01 | b | 0x00 | | x | 0x03 | y | 0x02 | | lb | 0x04 | rb | 0x07 | | lt | 0x05 | rt | 0x08 | | l3 | 0x06 | r3 | 0x09 | | back | 0x0a | start | 0x0b | | dpad_up | 0x0e | dpad_down | 0x0f | | dpad_left | 0x0c | dpad_right | 0x0d | | screenshot | 0x2d | ## 软件配置文件 命名的配置文件位于 `~/.config/gamegent/profiles/`（不是 GameSir 的板载插槽）。 当前生效的配置始终为 `~/.config/gamegent/config.json`；激活某个配置文件时会将其复制到此处，并可将设置推送到控制器。 ``` gamegent profile list gamegent profile save FPS gamegent profile load FPS # load + apply to hardware gamegent profile load FPS --no-apply # config file only gamegent profile apply # push working config gamegent profile delete FPS ``` 在 UI 中：**Profiles** 选项卡，当您至少保存过一个配置文件后，标题栏会出现一个配置文件切换器。 ## 已知限制 - 板载重映射的更改只能通过轮询查看（无 USB 推送通知） - 未实现 GameSir 板载配置文件插槽（仅支持软件配置文件） - 面键 LED 颜色需要 4 个同时发送（单键模式下通过配置进行缓存） - 使用前必须将设备从 VM passthrough 取消绑定 - `gamegent` 必须通过项目的 venv (`./venv/bin/…`) 运行；启动器会重新进入其中（在 Arch 上请勿使用系统 `pip`） ## 桌面应用 ``` ./install.sh # Symlink + .desktop launcher ./venv/bin/pip install -r requirements.txt gamegent app # Opens native desktop window ``` 功能说明： - 在 `127.0.0.1:5000` 上启动 Flask，并在该 URL 上打开一个 pywebview 窗口 - 当 React 源码新于构建版本时，自动重新构建 `web/react-app/dist` - 轮询 `GET /api/status`（约 2 秒）以获取连接状态指示 - 连接时，轮询 `POST /api/mappings/read`（约 4 秒），并在配置未处于脏数据状态时将重映射同步到 UI 应用菜单项：**GameGent**。浏览器 UI：`gamegent serve`（添加 `--prod` 以仅构建和提供 dist）。 ### Arch Linux 注意事项 pywebview 需要系统 GUI 后端，且 venv 必须能够识别系统站点包： ``` sudo pacman -S python-gobject webkit2gtk-4.1 # or: python-pyqt6 # venv/pyvenv.cfg 必须包含： # include-system-site-packages = true ./venv/bin/pip install -r requirements.txt gamegent app ``` **请勿**对系统 Python 运行 `pip install pywebview`（PEP 668 / 外部管理环境）。 用于重映射的配置流量位于 HID 端点 **0x01 OUT / 0x82 IN**（在 Wireshark 中为 `usbhid.data`），而不是 0x81 上的手柄数据流。 ## 项目结构 ``` core/ __init__.py # Public API transport.py # HID I/O (device discovery, read/write) hid_keycodes.py # USB HID usage tables + remap packet builders config.py # JSON config persistence (~/.config/gamegent/) lighting.py # Lighting modes, color, layout, LEDs remap.py # Button remap logic read_remap.py # Read onboard remaps from hardware stick.py # Stick config + curve presets rumble.py # Grip rumble gyro.py # Gyro/motion aim read_state.py # Full controller state read desktop/ app.py # pywebview desktop launcher web/ app.py # Flask API + React dist serving react-app/ # React + TypeScript UI main.py # CLI entry point install.sh # PATH symlink + .desktop install doc/remapping.md # Packet protocol reference pcapng/ # Reference USB captures ```

标签：MITM代理, Python, USB HID, 外设管理, 无后门, 游戏手柄