Files
AndroidDeviceStreaming/docs/windows-usb.md
T

85 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 可选 Windows USB 模拟
## 原理与范围
```text
本机原版 ADB / WinUSB
↕ USB 请求
已签名 USBip UDE 虚拟控制器
↕ 本机回环 USB/IP
ads-usb(本项目的虚拟 ADB USB 设备)
↕ 本机原始 adbd 流
ads-client → P2P / WSS 中继 → ads-agent → 手机 TCP adbd
```
这是 USB 枚举与端点适配,不会执行 adb connect 来冒充 USB 设备。已有远程手机仍可保持 LAN ADB 接入,远程电脑、控制中心和中继无需为此更改程序或开放 USB/IP 端口。网络 ADB 是默认模式,USB 模拟为可选开关。
本项目没有新增内核驱动,而是使用上游 [usbip-win2](https://github.com/vadimgrn/usbip-win2) 已签名的 UDE 控制器。虚拟 ADB 接口为 FF/42/01,bulk IN 0x81 / OUT 0x02,512 字节最大包,提供 Microsoft OS 1.0 的 WinUSB 兼容 ID 与 Android ADB 接口 GUID。当前兼容设备身份为 18D1:4EE7,序列号 ADS-设备ID(超长 ID 使用哈希),用于本机软件模拟,不能把它作为自有硬件 VID 分配。
只模拟 ADB,不包含 MTP、fastboot、音视频 USB 接口。P2P/中继和网络延迟仍然存在。Linux/macOS 后端未实现;当前驱动安装脚本固定支持 Windows x64。
## 安装
以 PowerShell 7 从项目根目录运行:
```powershell
# 只下载、验证,不更改系统
.\scripts\install-windows-usb.ps1
# 启动上游安装器;管理员 UAC 确认后完成安装
.\scripts\install-windows-usb.ps1 -Install
```
固定上游 USBip 0.9.8.1 x64,脚本同时核对 SHA256 和有效 Authenticode 发布者证书:
- SHA256:38CAD6D4432B52D5BB9409D9AD03B72FDFFC4ADA4CD3A48FBECA1A2752A8518A
- 发布者:Cloudyne Systems (Scheibling Consulting AB)
- 证书指纹:9AC56B6C76141395D74FFF6652818376E80B9C95
安装会短暂重启 USB 集线器;安装器可能要求随后重启 Windows。脚本不会强制重启、打开测试签名或关闭 Secure Boot。升级版本时需重新核验发布资产、签名及驱动兼容性。第三方安装包不进入 Git;Windows 客户端分发包附带经固定哈希及签名校验的原版安装器,由用户选择安装。
2026-11-12 已在当前 Windows 安装驱动,usbip2_ude 与 usbip2_filter 均运行。安装器报告需要重启,但未自动重启;重启前的虚拟 USB 枚举、远程 shell 已通过。
## 桌面使用
1. 构建后端和工作台(scripts/build.ps1、scripts/build-desktop.ps1)。
2. 进入“连接配置 → 可选 USB 模拟 · Windows”。勾选 USB 模拟,指定 usbip.exe(默认 C:\Program Files\USBip\usbip.exe)。
3. USB/IP 端口默认 3240,仅回环,必须与本地 ADB 隧道端口不同且未占用。
4. 连接设备。桌面支持同时挂载多台设备,每台自动分配独立 ADB、USB/IP 与投屏端口;工作台先启动 ads-client 并等待设备租约,再启动虚拟设备并调用 usbip 挂载。
5. 本机 ADB 显示 ADS-home-phone,使用 `adb -s ADS-home-phone shell` 或桌面投屏。无需 adb connect。
6. 断开连接时关闭本次虚拟设备和本次网络客户端,释放远端租约,不卸载控制器驱动,不操作其他 USB 设备。
同机有其他 USB 手机时,`adb -d` 会报告 more than one USB device,这是原版 ADB 的行为;使用 -s 指定模拟设备。只连接这一个 USB ADB 设备时才能用 -d 唯一选择。
移除可选组件可通过 Windows“已安装的应用”卸载 USBip;先断开本项目 USB 模式。卸载涉及系统驱动,应遵循其卸载器提示。取消桌面开关即可继续使用网络模式。
## 协议与验证
USB/IP import/list、独占导入、设备/配置/字符串/WinUSB 描述符、端点 STALL、bulk IN/OUT、UNLINK、零长度包、断开与资源回收均在本项目实现。按 ADB 24 字节包头和载荷重建传输边界,避免把 TCP 分段误当 USB 短包;最大 ADB 载荷和单 URB 为 1 MiB,接收队列与待处理 URB 有界。USB/IP 无公网认证层,因此严格限制为回环;跨公网只走已有认证、加密的 ADS 通道。
```powershell
cargo test -p ads-usb --locked
python tests/usb_e2e.py
cd desktop
dotnet run --project Ads.Desktop.Smoke -c Debug -- --live --screen --usb
```
2026-11-12:协议集成测试通过,包含任意 TCP 分段下的 ADB 包头/载荷还原、512 字节载荷后的 ZLP、取消无多余完成包、畸形/超大 URB 拒绝。真实已签名 Windows 控制器导入后,原版 ADB 枚举 ADS-home-phone 并执行远端 echo / getprop;本机已有物理 USB 手机未被移除,adb -d 正确报告多 USB 设备。
参考:[USB/IP 协议](https://www.kernel.org/doc/html/latest/usb/usbip_protocol.html)、[Microsoft UDE](https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/developing-windows-drivers-for-emulated-usb-host-controllers-and-devices)、[AOSP Windows USB transport](https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/main/client/usb_windows.cpp)。
桌面 USB 模式实测通过:P2P 路线状态、USB 序列号选择、设备型号、真实 scrcpy 视频、重新连接、断开后释放租约、清理本机隧道端口时一并移除虚拟 USB,以及凭据不写入配置/日志。结束后 USBip 控制器导入数量为 0,物理 USB 手机保持在线。
多设备工作台中,切换当前设备不会断开其他 USB 设备;清理所选设备的隧道端口只释放该设备。退出和“断开全部”释放本工作台的全部虚拟 USB 设备,不卸载驱动或操作物理 USB 手机。
## Flutter Windows
“连接配置”勾选“挂载为 USB 设备 · Windows”,先检测 USBip 控制器、usbip.exe 和 ads-usb。未安装控制器时弹出安装提示;选择安装后验证随包安装器的 SHA-256 和发布者签名,启动交互安装器请求 UAC,不静默安装、不重启 Windows。安装完成后重新检测并勾选、保存配置,再连接设备。
Flutter 连接会等待租约状态为 true,禁用网络 adb connect,分配独立回环 USB/IP 端口并挂载;设备列表和投屏使用 ADS- 序列号。断开/退出停止本次 ads-usb,借助 --once 与 TCP EOF 移除本设备,不按可能复用的控制器端口 detach。
Windows 包在 drivers/ 下附带原版 USBip-0.9.8.1-x64.exe 及来源说明;ADS 主安装器只复制该文件,不自动安装驱动。
## 安装 APK 时的双向流控
USB/IP bulk OUT 写入由独立有界任务处理,不再阻塞控制请求和 bulk IN 完成;仅在远端实际接收写入后确认 OUT 完成。避免 APK 安装等双向高负载下主事件循环等待网络写入、无法处理返回数据而触发断线。`tests/usb_e2e.py` 包含远端停止读取且上行堆积 12 MiB 时的控制请求回归测试。更新 ads-usb 后需要重新连接虚拟 USB 才能使用新进程。