Altureus/Windows-Switch2-Pro-Controller

# Switch 2 Pro Controller → Xbox 手柄桥接器 (Windows) 这是一个原生 Windows 应用程序，它能让 **Nintendo Switch 2 Pro Controller**（USB `057E:2069`）作为标准的 Xbox 360 手柄工作 —— 支持 **Dolphin** 以及任何游戏/模拟器 —— 具备**震动**、**自动重连/自动唤醒**循环，并且**无需任何第三方 Python 包**（纯 `ctypes` 实现）。 Switch 2 Pro 是一款 Windows 无法开箱即用的新款手柄：它会作为原始 HID 设备（`If_Hid`）枚举，启动时处于**休眠状态**（在唤醒前不会传输任何数据），并使用模拟器无法解析的自定义 report 布局。现有工具要么基于浏览器（当标签页失去焦点时就会断开连接），要么是不稳定的蓝牙连接。据我所知，这是唯一一款将其作为真正的驱动级 Xbox 手柄呈现的**原生、USB 有线、自动唤醒**工具。 ## 功能 - 通过其 WinUSB 厂商接口**唤醒**手柄。 - **读取**其 64 字节的 HID report，并**解析**自定义的按键/摇杆布局。 - 通过 **ViGEmBus** **发布**一个虚拟 Xbox 360 手柄 → Dolphin 将其视为普通的 XInput 设备。 - 双向**震动**：模拟器 → 手柄触觉反馈。 - **永不掉线**：保持虚拟手柄在线，并在任何小故障中自动重连/重新唤醒。 ``` Switch 2 Pro (asleep) -> WinUSB bulk wake (winusb.py) -> read HID reports (hid.py) -> parse custom layout (mapping.py) -> virtual Xbox 360 pad (vigem.py / ViGEmBus) -> Dolphin (XInput) <- rumble: HID report 0x02 (haptics.py) ``` ## 环境要求 - **Windows 10/11 (x64)** - **Python 3**（任何现代版本，包括 3.14 —— **无需 `pip install`**） - 已安装 **ViGEmBus 驱动** —— （附带的 `ViGEmClient.dll` 只是用户模式客户端；内核驱动是独立的） - 通过 USB 连接的 **Switch 2 Pro Controller** ## 快速开始 1. **安装 Python 3** —— 。在安装程序中，勾选 **“Add python.exe to PATH”**。（无需 `pip install` —— 此应用具有*零* Python 依赖。） 2. **安装 ViGEmBus 驱动** —— （一键安装；它是无法被捆绑的内核模式组件）。 3. **获取本仓库** —— 下载[最新发行版](../../releases/latest)的 zip 文件（或 `git clone`）并解压。 4. *（推荐）* 双击 **`Setup Check.bat`** —— 它会验证 Python + ViGEmBus 是否准备就绪，并标记出任何缺失的内容。 5. 运行 **`Start Bridge.bat`** 并保持窗口打开。在 Dolphin 中，将手柄端口设置为 **Standard Controller → Configure**，选择它打印出的 **`XInput/N/Gamepad`**，然后绑定你的按键。 该桥接器会让 Dolphin 始终指向它所登陆的 XInput 插槽，在每次（重新）插入时自动唤醒手柄，并且能够在拔出后继续运行。 ## 自启动（可选） 不想每次都打开 `Start Bridge.bat` 吗？双击 **`Install Autostart.bat`** —— 之后该桥接器会在**每次登录时静默启动**（无窗口），因此手柄可以直接使用。基于当前用户运行，无需管理员权限。 - **`Stop Bridge.bat`** —— 立即停止后台运行的桥接器。 - **`Uninstall Autostart.bat`** —— 停止在登录时启动它。 它仅会在你的启动文件夹中放置一个运行 `pythonw bridge.py` 的快捷方式。你也可以直接通过命令驱动它：`python procon2\autostart.py install|uninstall|status|stop`。 ## 原理与目的（深度剖析） 请参阅 [`procon2/README.md`](procon2/README.md) 获取逆向工程笔记：report 布局、唤醒序列、触觉反馈格式，以及逐文件的代码解析。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。第三方组件：[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 *免责声明：不隶属于 Nintendo，也未获得其认可。“Nintendo Switch”是 Nintendo 的商标。使用风险自负。*

标签：HID通信, Python, ViGEmBus, Windows驱动, 外设适配, 手柄映射, 无后门, 逆向工具