K1Guitar/tools/k1_harness/README.md

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

命令

cd tools

# 无硬件自检
python -m k1_harness selftest

# App 协议（BLE 通道，默认）
python -m k1_harness run --suite app --transport ble

# App 协议（串口通道）
python -m k1_harness run --suite app --transport com --port COM5

# BLE 链路 smoke
python -m k1_harness run --suite ble

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

# 全量（nightly）
python -m k1_harness run --suite all --profile nightly

# 含关机用例（破坏性，跑完设备软关机）
python -m k1_harness 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 并在详情中提示重烧。