Steam Controller Auto-Charge – pilot to magnetic charging puck using CV

{
"category": "编程开发",
"title_cn": "Steam Controller 自动充电：基于计算机视觉的磁吸底座自主归位系统",
"content": "> 通过光流追踪和 WebHID 遥测，实现 Steam 手柄自主导航至磁吸充电底座并自动充电。\n\n## 概述\n\nSteam Controller Auto-Charge 是一个开源 Web 应用程序，利用光流计算机视觉和 WebHID 遥测技术，让 Steam 手柄能够自动导航并插入磁吸充电底座。该项目由 FossPrime 开发，灵感来源于 Very Lazy Pixel 的相关视频，代码托管在 GitHub 上，采用 MIT 许可证开源。\n\n## 核心功能\n\n### 1. 光流追踪（Optical Flow Tracking）\n\n使用 OpenCV.js 实现的 Lucas-Kanade 光流算法，通过头顶摄像头追踪用户选定的手柄和充电底座上的特征点。具体来说，calcOpticalFlowPyrLK 函数负责计算前后帧之间的特征点位移，从而实时获取手柄和底座的位置信息。\n\n### 2. WebHID 遥测与触觉导航（WebHID Telemetry & Haptic Navigation）\n\n通过 WebHID API 直接与 Triton 控制器（即 Steam Controller 的变体）建立原生通信，流式传输输入和遥测数据（Report 67）。核心机制是：通过内部双线性谐振致动器（LRAs）发射 70Hz 的非对称触觉脉冲，驱动手柄向充电底座移动。 触觉脉冲的强度和方向通过软件闭环控制，相当于用振动“推”着手柄走。\n\n### 3. 接近蠕变模式（Proximity Creep Mode）\n\n当手柄距离充电底座小于 150 像素时，系统自动将触觉脉冲频率降低 50%，使手柄以更慢、更柔和的“蠕动”方式完成最后的磁吸对接，避免因速度过快导致碰撞或对接失败。\n\n### 4. 电池状态轮询（Battery Status Polling）\n\n- 拦截 Report ID 121（0x79） 以确认磁吸充电是否成功（即底座与手柄的电气连接是否导通）。\n- 解析 Report ID 67（0x43） 以获取实时电池百分比和电池单元电压（mV），并在界面上显示。\n\n## 系统架构\n\n项目采用前端全栈方案，主要技术栈包括：\n\n- App.vue：Vue 3 应用逻辑，负责摄像头流处理、UI 响应、PID 追踪循环，以及 OpenCV.js 的 Lucas-Kanade 光流计算。\n- steamController.ts：WebHID 抽象类，将标准 API 调用映射为 Steam Controller 特定的字节载荷，用于发送 LRA 脉冲和轮询电池状态。\n- objectDetector.ts 与 objectWorker.ts：将目标检测任务卸载到 Web Worker 中，确保主追踪循环不因繁重的视觉计算而卡顿。\n- wasm-object-detect/：用 Rust 编写并编译为 WebAssembly 的视觉处理模块，提供高性能的卷积神经网络（CNN）推理能力，用于物体避障与识别。\n\n## 运行环境与依赖\n\n- Nix 包管理器：唯一的构建依赖，可在 Windows、Mac 和 Linux 上无缝工作。\n- 基于 Chromium 的浏览器：必须支持 WebHID API（Chrome、Edge 等）。\n- 头顶摄像头：从正上方俯拍桌面，用于捕捉手柄和底座的实时画面。\n\n## 使用步骤\n\n1. 安装 Nix 包管理器。\n2. 将摄像头固定在正上方，对准桌面。\n3. 将 Steam Controller 充电底座放在桌面上。\n4. 将 Steam Controller 直立放在桌面上（手柄朝上，触摸板朝前）。\n5. 运行命令 nix-shell --run \"npm install && npm run dev\"，系统会自动拉取依赖并构建 WASM 模块。\n6. 在浏览器中打开 Web 界面，点击 "Connect Steam Controller" 通过 WebHID 配对。\n7. 点击 "✨ Auto-Track" 启用自动追踪（按钮高亮表示激活，页面刷新后会自动恢复追踪状态；再次点击可关闭）。\n8. 手柄将自动导航至充电底座，整个过程依赖 Lucas-Kanade 光流循环 + 浏览器内 Rust/WASM CNN 物体避障。\n\n> 注：用户也可以手动追踪——依次点击充电底座、手柄顶部、手柄底部即可。\n\n## 技术深度解析\n\n### 光流与 PID 控制\n\n系统的核心是一个 视觉伺服（Visual Servoing）闭环：\n- 摄像头采集图像 → OpenCV.js 计算光流 → 得到手柄与底座的相对位姿 → PID 控制器计算所需的驱动力（即触觉脉冲的方向与强度） → 通过 WebHID 发送至手柄 LRA 致动器 → 手柄物理移动 → 摄像头再次采集。\n\nLucas-Kanade 光流算法假设特征点邻域内的运动一致，通过求解最小二乘问题得到运动向量。在项目中，用户选定的特征点（如手柄顶部、底部、充电底座中心）被持续追踪，从而获得亚像素级的定位精度。\n\n### WebHID 通信细节\n\n- Report 67（0x43）：包含电池百分比、电压以及触觉反馈状态。项目通过轮询此报告实时更新 UI 中的电池信息。\n- Report 121（0x79）：充电状态报告，当手柄与底座磁吸接触并建立电气连接时，此报告会返回成功标志。\n- LRA 脉冲：通过写入特定字节载荷到 HID 输出报告，以 70Hz 的频率驱动双线性谐振致动器。左/右致动器的振幅差决定了手柄的转向，相当于差速驱动。\n\n### Web Worker 与 WASM 的协同\n\n- objectDetector.ts 和 objectWorker.ts 将 CNN 推理（物体检测、避障）放到后台线程执行，主线程只负责光流追踪和 PID 计算，保证了 60fps 的实时性。\n- Rust 编译的 WASM 模块（wasm-object-detect/）负责高性能的卷积计算，用于识别桌面上的障碍物（如杯子、线缆）并规划避让路径。\n\n## 项目文件结构\n\n\n├── .github/workflows/ # CI/CD 配置\n├── data/ # 训练数据或静态资源\n├── public/ # 静态文件\n├── scripts/ # 辅助脚本\n├── src/ # 源代码\n│ ├── App.vue # 主 Vue 组件\n│ ├── steamController.ts # WebHID 抽象\n│ ├── objectDetector.ts # 目标检测主逻辑\n│ ├── objectWorker.ts # Web Worker 入口\n│ └── ...\n├── tests/ # 测试文件\n├── wasm-object-detect/ # Rust WASM 源码\n├── index.html\n├── package.json\n├── vite.config.ts\n└── README.md\n\n\n## 局限性\n\n- 需要稳定的光照条件和无遮挡的桌面环境。\n- 头顶摄像头的分辨率与帧率直接影响追踪精度。\n- WebHID 目前仅 Chromium 系浏览器支持，且需要用户手动授权设备访问。\n- 手柄在充电过程中不能被人为移动，否则追踪会丢失。\n\n## 未来改进方向\n\n- 支持多手柄同时充电。\n- 使用深度摄像头（如 Intel RealSense）实现 3D 空间定位，避免 2D 光流在倾斜角度下的误差。\n- 将触觉导航算法移植到嵌入式微控制器上，实现离线独立运行。\n\n## 致谢\n\n项目灵感来源于 Very Lazy Pixel 的视频，其展示了类似概念的早期原型。\n\n## 原文链接\n\nhttps://github.com/FossPrime/Steam-Controller-Auto-Charge"
}