# k1_harness — K1 吉他统一 HIL 自动化测试

覆盖 K1 电吉他（YNGJ-GT1-M）的 **UI、按键、资源包、BLE、App 协议** 验证。
复用现有脚本，不重写用例：

- App SysEx 协议：`test_protocol_app_sim.run_tests`（COM）/ `test_protocol_ble.py`（BLE）
- RTT 注入/日志：`rtt_pitch_reg_test` 的 J-Link 连接与 `RttSession`

## 前置条件

| 套件 | 硬件 |
|------|------|
| `app`（com） | USB 转串口接 UART4（BLE 桥），115200 8N1 |
| `app`（ble）/ `ble` | 笔记本蓝牙，设备广播名 `Smart Guitar MIDI` |
| `keys` / `keys1617` / `packs` / `ui` | J-Link + SWD，固件含 `app_log` 注入命令 |

依赖：`pip install pyserial bleak pylink-square pillow`

## 命令

在仓库根目录（推荐）：

```bash
python run_k1_harness.py selftest
python run_k1_harness.py run --suite all --profile nightly
# 或
run_k1_harness.bat run --suite all --profile nightly
```

也可进入 `tools` 后：

```bash
cd tools
python -m k1_harness selftest
python -m k1_harness run --suite all --profile nightly
```

> 注意：不要在仓库根目录直接执行 `python -m k1_harness`（会报 `No module named k1_harness`）。
> 包位于 `tools/k1_harness/`。

```bash
# App 协议（BLE 通道，默认）
python run_k1_harness.py run --suite app --transport ble

# App 协议（串口通道）
python run_k1_harness.py run --suite app --transport com --port COM5

# BLE 链路 smoke
python run_k1_harness.py run --suite ble

# 按键 / 资源包 / UI（J-Link RTT）
python run_k1_harness.py run --suite keys,keys1617,packs,ui

# 含关机用例（破坏性，跑完设备软关机）
python run_k1_harness.py run --suite all --allow-poweroff
```

报告默认写到 `Doc/reports/k1_hil_<时间戳>.md`，可用 `--report` 指定。
退出码：有 FAIL 为 1，否则 0。

## 套件说明

| 套件 | 覆盖 | 判定 |
|------|------|------|
| `app` | SysEx 组 01~06（设备信息/和弦映射/参数/LED/段落/电源） | ACK 帧头+长度+回读一致；04/06 无 ACK 记 SENT |
| `ble` | BLE 连接 + BLE-MIDI framing + smoke 往返 | 子进程 `test_protocol_ble.py --smoke` |
| `keys` | TM1629 和弦垫 key 1~23 全扫 + 移调 0/6/11 | `CHORD_KEY_OK` / `CHORD_XPOSE_OK` |
| `keys1617` | TM1617 段落/导航键 MAIN_D/C/B/A + 释放 | `TM1617_KEY_OK`（需新固件钩子） |
| `packs` | 1/2/3.bin 加载（地址 OK + ret=0）、拨片起奏、3.bin 尾奏回归 | `TONE_*` 行 + `[PITCH]` 活动 |
| `ui` | `log status` 页名、`TAP` 触摸注入、`ui boot/charge` 绘制、可选截屏 | 页名/ACK；TAP 需 `DEBUG_LCD_DUMP` 固件 |

## 固件测试钩子（RTT 下行命令，见 `APP/app_log.c`）

| 命令 | 说明 |
|------|------|
| `chord key N` / `chord key N hold` | TM1629 注入；`hold` 保持不被物理空扫释放（`chord key 0` 解除） |
| `chord xpose N` | 移调 0~11 |
| `tm1617 key N` | TM1617 注入（0~3=MAIN_D/C/B/A，4=释放） |
| `adc key N on\|off` | ADC 键注入（1=独立尾奏键，与万能第4键同路径） |
| `tone bin1/bin2/bin3 [idx]` | 资源包加载校验 |
| `tone start` / `tone pick [uni]` | 拨片起奏 |
| `log status` / `log dump` / `sys reset` | 状态/日志/复位 |
| `TAP x y` / `DUMP` | 触摸注入/截屏（需 `DEBUG_LCD_DUMP`） |

## 备注

- 手机 App 源码不在本仓；**App 功能验证 = BLE SysEx 端到端**（与真机 App 同协议）。
- 3.bin 尾奏回归对应音师需求 `Doc/音师需求_万能3.bin尾奏_20260914.md`：
  尾奏触发后 4s 内应仍有 `[PITCH] on`，否则判定「一按立刻静音」FAIL。
- 老固件缺少新命令时相关用例记 SKIP 并在详情中提示重烧。