CouchTurtle/sc2-research
GitHub: CouchTurtle/sc2-research
该项目逆向工程并文档化 Steam Controller 2 的固件更新协议、HID 输入布局及硬件架构，同时提供配套的 Python 分析与抓包工具。
Stars: 3 | Forks: 0
# sc2 研究
关于 Steam Controller 2 (Triton) 的笔记和工具：HID 输入布局、固件更新协议、feature-report 路由，以及固件 blob 的静态分析。
这些内容大多来自提取的 `hardwareupdater.x86_64` —— 即 Steam 客户端附带的 PyInstaller 打包文件 —— 并且是在 Steam Deck (SteamOS) 上通过实际的 SC2 + Puck（控制器固件为 `bcdDevice 0.02`）进行验证的。这是一个在大量 AI 辅助下完成的业余项目 —— 请参阅[免责声明](#disclaimer)。
涵盖内容：SC2（USB `28DE:1302/1303`）、Proteus puck（`28DE:1304`）以及并行的 Nereid dongle（`28DE:1305`）。基于 SDL3 的提交时间，以及 Steam 面向用户的更新程序中缺失 Nereid bootloader 路径这一事实，Nereid 很可能是集成到 Steam Machine 中的 dongle。
## 文档
| 路径 | 内容 |
|---|---|
| [`docs/FIRMWARE_PROTOCOL.md`](docs/FIRMWARE_PROTOCOL.md) | 更新协议：HDLC 帧、消息 ID、固件文件格式、bootloader 模式切换、实时 feature-report 属性查询、ARM Cortex-M 静态分析。 |
| [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) | 逆向工程笔记：PyInstaller bundle 提取、无需反编译器的字节码反汇编、InHand 标志的证伪、抓包时序陷阱、SteamOS ACL 特性、多设备 `fr_id` 路由。 |
| [`docs/CONTROLLER_CAPABILITIES.md`](docs/CONTROLLER_CAPABILITIES.md) | 硬件笔记 —— 芯片识别、USB 拓扑、触觉执行器 ID、通过固件字符串分析发现的组件。 |
| [`docs/HID_REPORT_FORMAT.md`](docs/HID_REPORT_FORMAT.md) | 54 字节的 Report-0x42 布局（来自 SDL3，已针对约 9k 帧进行验证）、puck USB 拓扑、Lizard 模式时序、子报告 `0x43`（电池）和 `0x7b`（SDL3 中未包含的唯一一个 Triton 输入报告 ID）、SteamOS 访问笔记。 |
| [`docs/SDL3_REFERENCE.md`](docs/SDL3_REFERENCE.md) | 交叉参考 SDL3 开源代码中关于 Triton 的说明 —— 报告 ID、输出触觉消息类型、设置、音频提示、充电状态、IMU 轴映射与缩放、触摸板变换、时序常数。 |
## 工具
Python 3.10+，仅使用标准库。在 SteamOS 上以 `deck` 用户身份运行（不要用 `sudo` —— root 被 hidraw ACL 拦截）。
固件分析与提取：
| 工具 | 功能 |
|---|---|
| `tools/extract_pyinst.py` | 极简的 PyInstaller bundle 提取器 —— MEI cookie + TOC 遍历器。 |
| `tools/walk_pyc.py` | 遍历 marshaled 的 Python 代码对象，列出嵌套的函数和常量。 |
| `tools/analyze_fw.py` | 解析 ARM Cortex-M 固件 blob（头部、向量表、IRQ 处理程序、字符串）。 |
| `tools/attr_query.py` | 通过 `ioctl` 发送 HID Feature-Report 以查询设备属性。 |
实时抓包与观察：
| 工具 | 功能 |
|---|---|
| `tools/live_monitor.py` | 流式读取 `/dev/hidraw9`，打印按键状态切换和模拟量偏转。 |
| `tools/one_capture.py NAME [NAME...]` | 针对每个指定的动作抓取 3 秒的 hidraw9 数据流；并与基准线进行差异对比。 |
| `tools/event_logger.py [seconds]` | 跨 hidraw9–13 的并行记录器；为每个接口生成 report-ID 直方图。 |
## 快速开始
```
git clone
cd sc2-research
# 通过 HID Feature-Reports 探测 puck + controller
python3 tools/attr_query.py
# 提取 Steam 的固件更新程序
python3 tools/extract_pyinst.py
python3 tools/walk_pyc.py
# 分析固件 blob
python3 tools/analyze_fw.py ~/.local/share/Steam/bin/hardwareupdater/IBEX_FW_69FA5889.fw
```
## 背景
Valve 自身发布的、作为本项目基础的公开资源：
- [SDL3 `SDL_hidapi_steam_triton.c`](https://github.com/libsdl-org/SDL/blob/main/src/joystick/hidapi/SDL_hidapi_steam_triton.c) —— 由 Sam Lantinga 在提交 `1998b6504`（2025 年 11 月 12 日）中上游的驱动
- [SDL3 `controller_structs.h`](https://github.com/libsdl-org/SDL/blob/main/src/joystick/hidapi/steam/controller_structs.h)
- [SDL3 `controller_constants.h`](https://github.com/libsdl-org/SDL/blob/main/src/joystick/hidapi/steam/controller_constants.h)
- `~/.local/share/Steam/bin/hardwareupdater/` 中的 `hardwareupdater.x86_64` —— Steam 客户端附带的 PyInstaller bundle。
其他 SC2 时代的工作：
- [`OpenSteamController/Ibex-Firmware`](https://github.com/OpenSteamController/Ibex-Firmware) —— 从 Valve 的 CDN 镜像了 `.fw` blob 并提供了带版本号的目录。记录了 32 字节的头部信息（校验和字段 = 偏移量 `0x08` 处的 CRC32）。
- [SteamHapticsSinger](https://github.com/CrazyCritic89/SteamHapticsSinger) —— 触觉输出端。根据 SDL3，他们的“Note-On `0x83`”对应 `HAPTIC_LFO_TONE`；“Note-Off `0x81`”对应 `HAPTIC_PULSE`。
- [SteamlessController](https://github.com/ddeverill/SteamlessController) —— 一个禁用 Lizard 模式并将 Report 0x42 桥接到虚拟 Xbox 360 手柄的 Windows 工具。
- [OpenSteamController](https://github.com/greggersaurus/OpenSteamController) (greggersaurus) —— 针对 2015 款 Steam Controller (LPC11U37F + nRF51822) 的逆向工程；在架构上与 SC2 无关。
硬件识别：
- [iFixit Steam Controller (第二代)](https://www.ifixit.com/Device/Steam_Controller_%282nd_Generation%29) —— 读出的芯片丝印为 nRF52833（“疑似”）。本仓库中的固件设备树（DT）地址分析将其识别为 nRF52840。
- [PC Gamer 2026 拆解](https://www.pcgamer.com/hardware/game-pads/steam-controller-2026-review/)，[GamersNexus 评测](https://gamersnexus.net/handheld-pcs-peripherals/valve-steam-controller-review-latency-benchmarks-battery-life)，[PCGamingWiki](https://www.pcgamingwiki.com/wiki/Controller:Steam_Controller_(2nd_generation))。
在本项工作之前就已经公开的代号：
- [Brad Lynch 在 X 上，2024 年 11 月 19 日](https://x.com/SadlyItsBradley/status/1858925211363553316) —— “Ibex”。
- [Tom's Hardware 2025 年第四季度](https://www.tomshardware.com/video-games/pc-gaming/valve-seemingly-preps-steam-controller-2-and-vr-controller-ibex-and-roy-controller-renders-spotted-in-steamvr-data-mine) —— “Ibex” + “Roy”。
- [NeoGAF 2025 年第四季度](https://www.neogaf.com/threads/new-triton-steam-controller-icon-datamined.1689607/) —— “Triton”。
- [Phoronix 2025 年 11 月 12 日](https://www.phoronix.com/news/New-Steam-Controller-SDL) —— “Proteus”和“Nereid”。
## 许可证
MIT —— 请参阅 [LICENSE](LICENSE)。部分模式在文中内联标明了来源于 BSD-3-Clause 的 SteamHapticsSinger。
## 免责声明
业余项目，在大量 AI 辅助（Claude）下完成，用于假设检验、交叉参考和起草。硬件测试、固件提取和数据包抓取均在我自己的 Steam Deck (SteamOS) 上通过 SC2 + Puck（USB `bcdDevice 0.02`）进行。在可能的情况下已与 SDL3 源代码进行了交叉核对；我可能会遗漏一些具备更深厚逆向工程背景的人所能发现的惯例 —— 欢迎通过 issue / PR 进行指正。
基线：此处分析的固件 blob 为 **`IBEX_FW_69FA5889` + `69FE17FF`** (Triton) 和 **`PROTEUS_FW_69FA587F` + `69FBD45D`** (Proteus)，均来自 2026 年 5 月初。两对文件在 [`OpenSteamController/Ibex-Firmware`](https://github.com/OpenSteamController/Ibex-Firmware) 中都有字节级完全一致的镜像，因此任何人都无需自己的 Steam 安装即可重现该分析：
```
curl -O https://opensteamcontroller.github.io/Ibex-Firmware/Controller/IBEX_FW_69FE17FF.fw
curl -O https://opensteamcontroller.github.io/Ibex-Firmware/Puck/PROTEUS_FW_69FBD45D.fw
python3 tools/analyze_fw.py IBEX_FW_69FE17FF.fw
```
此后 Valve 又发布了进一步的更新（2026 年 6 月版本在设置中增加了 LED 调光 + 扳机死区微调）。预期这些更新中的协议层将保持稳定；静态分析的偏移量则与上述特定的固件版本绑定。
此处不重新分发任何专有代码或固件 blob —— 有关 blob 的信息，请参阅 [`OpenSteamController/Ibex-Firmware`](https://github.com/OpenSteamController/Ibex-Firmware)。与 Valve 没有任何隶属关系。
标签：HID协议, Python, 云资产清单, 固件分析, 嵌入式系统, 无后门, 游戏外设, 漏洞挖掘, 逆向工具, 逆向工程