Files
NESLite/docs/controller-x5lite.md
T

61 lines
4.0 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.
# X5 Lite 实测键位与模式
本文档只登记真实设备结果,不根据按钮字母、外观或网络资料推断 Android 键码。2026-09-12 已收到
用户提供的手柄正面和肩部照片;照片确认这是直连 USB-C 的伸缩式布局,并可见十字键、双摇杆、
ABXY、视图/菜单键及左右肩键。随后在荣耀 Magic8 页面取得了 Android 设备身份和静态轴范围;
实际 KeyEvent、动态轴采样、手柄模式及拔出重连仍待诊断 JSON 回填。
在 0.9.15-debug 中可从“设置 → 交换 X/Y、A/B 按键与手动映射”进入编辑页。可选择“开始逐项手动
设置全部按键”,按页面顺序操作 X5 Lite;也可点击任一动作单独修改或清除。轴方向捕获后先松回中位,
冲突时确认是否替换,最后点击“保存”。配置按下表设备指纹保存,不依赖临时 deviceId。
“设置 → 屏幕方向键与手柄摇杆”可选择四方向或八方向。八方向允许摇杆同时上报一个横向和一个纵向;
四方向会保留最近明确输入的主轴,降低斜推误触。
## 固定测试条件
- 手柄模式:原生安卓模式,实际切换方法待随设备说明和实测确认。
- 硬件连发:测试前关闭;实际指示状态待实测记录。
- 厂商保留组合:待实测;不得占用“视图+菜单长按”。
- 照片观察:USB-C 直连、伸缩夹持;可见十字键、双摇杆、ABXY、视图/菜单及肩键。
- 应用版本:M1 采集页基线 `0.1.3-debug`;M4 映射页 `0.4.4-debug`。
- 事件上限:最近 512 条;页面显示最近 30 条。
## 连贯验收步骤
1. 连接目标手机,启用 USB 调试,运行 `pwsh -NoProfile -File tools/check-m1-device.ps1`。
2. 连接 X5 Lite,确认页面出现名称、descriptor、VID/PID、sources 和轴范围。
3. 分别操作十字键、左右摇杆、扳机和所有正面/肩键,观察按下、重复、松开与轴值。
4. 同时按住一个方向和 A/B,确认组合状态同时存在;全部松开后确认状态为“无”。
5. 按住方向及 A/B 时拔出手柄,确认出现 `device_removed` 且状态清空。
6. 重新连接,确认分配新的会话编号并可继续记录。
7. 点击“导出诊断 JSON”,保存文件并在本报告登记文件名和 SHA-256。
## 设备身份
| 项目 | 实测值 |
| --- | --- |
| 手机型号/系统 | 荣耀 Magic8;系统上报 `HONOR BKQ-AN00`、Android 16(MagicOS 小版本未从截图读取) |
| API/ABI/页大小 | API 36/arm64-v8a/4096 bytes |
| 屏幕/当前及可用刷新率 | 1256×2760;当前 120 Hz,可用 60/90/120 Hz |
| 手柄名称/descriptor | `GameSir-X5 Lite`/`b1a6c9b8b9d3859962c394e40e343794a489ddb5` |
| VID/PID/sources | `0x3537`/`0x1116`/`0x1000511` |
| 安卓模式切换方法 | 待实测 |
| 硬件连发关闭方式/状态 | 待实测 |
| 厂商保留组合 | 待实测 |
| 诊断 JSON/SHA-256 | 待实测 |
外观照片只作为“物理控件存在”的证据,不作为设备身份或 Android 事件映射证据。M4 在未取得上述
身份字段时使用标准 Android 通用映射,并允许在应用内逐项捕获;X5 Lite 专属签名不会按名称猜测。
## 键位与轴
| 物理控件 | Android KeyEvent/MotionEvent | sources/范围 | 重复上报 | 备注 |
| --- | --- | --- | --- | --- |
| 十字键上/下/左/右 | 动态事件待实测 | HAT_X/HAT_Y,-1..1,flat 0 | 待实测 | 记录按键与 HAT 是否同时上报 |
| A/B/X/Y | 待实测 | 待实测 | 待实测 | 不按字母推断 NES 映射 |
| LB/RB/LT/RT | 动态事件待实测 | LT: LTRIGGER/BRAKE 0..1;RT: RTRIGGER/GAS 0..1;flat 0.059 | 待实测 | 记录肩键及扳机按键/轴双重上报 |
| 左摇杆/按下 | 动态事件待实测 | X/Y,-1..1,flat 0.118 | 待实测 | 摇杆按下键码待测 |
| 右摇杆/按下 | 动态事件待实测 | Z/RZ,-1..1,flat 0.118 | 待实测 | 摇杆按下键码待测 |
| 视图/菜单 | 待实测 | 待实测 | 待实测 | 保留厂商组合说明 |