STM32F4-Base/test/host/screenlink_bench.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""屏板链路台架激励：用 PC + USB 转 TTL **顶替屏板**，按屏板的召唤节拍发 6 B 帧 A。

做什么：
    在一个 TTL 串口上按屏板的节拍（默认 280 ms）发帧 A，模拟屏板的周期召唤；
    可穿插按键帧（屏板有键时最早 205 ms 就会再来一帧，本脚本只在周期点替换内容，
    不额外插帧——批 1 只验"收得到、长度对、CRC 过"，不验应答时序）。
    主机侧的统计由固件自己打（`[SBLINK] rx=... ok=... crc=... len=...`），
    本脚本只负责"有东西可收"，不读被测板——**收侧观测面是串口日志，不是本脚本**。

为什么不用串口助手 GUI：
    1-3 的判据含"连续 10 min 无丢帧"，手点是做不到的；而且帧内容必须逐字节对
    （CRC 低字节在前，写错一位就是 100 % CRC 错帧，与"波特率错"同形）。

接法（docs/任务规划/屏板链路.md §2 决策一）：
    适配器 TXD -> U5.B10（网络 ST_RX0，PA10）    适配器 RXD -> U5.A10（网络 ST_TX0，PA9）
    适配器 GND -> 板地
    ⚠ 必须交叉接（TX 对 RX）；USART1 的 TTL 只从 U5 出去，CN1 上没有 USART1 端子。
    串口参数 700000 8N1，与固件 `SB_LINK_BAUD` 一致。

与日志口的关系：
    日志走 RS-232 侧（默认 COM3，由 serial-assistant daemon 占用），本脚本占用的是
    **另一路 TTL 口**（台架上通常是 COM6）——两者互不相干，可同时跑。

用法（仓库根目录）：
    & '.venv\\Scripts\\python.exe' test/host/screenlink_bench.py --port COM6 --seconds 30
    & '.venv\\Scripts\\python.exe' test/host/screenlink_bench.py --port COM6 --seconds 600   # 10 min 判据
    --key N    每 N 个周期把召唤帧换成按键帧（键值在 1/2/3/4/7/8/9 里轮换；0 = 不发按键帧）

退出码：0 = 按时发完；1 = 串口打不开 / 发送失败；2 = 用法错误。

设计依据：docs/任务规划/屏板链路.md §3 批 1 的 1-3 判据、§5 台架联调步骤第 2 步。
创建日期：2026-10-29
"""
import argparse
import sys
import time

try:
    import serial
except ImportError:  # pragma: no cover - 环境缺失时给人话
    print("[ERR] 缺少 pyserial：请用项目 .venv 的 python 运行本脚本")
    sys.exit(2)

# 屏板固件里的 KEY_TYPE：7 个物理键可达 1/2/3/4/7/8/9（无 5/6，9 = RESET）
KEY_VALUES = (1, 2, 3, 4, 7, 8, 9)

CMD_KEY = 0x00
CMD_RT = 0x01
ADDR = 0x01
FUNC = 0x03


def crc16_modbus(data):
    """标准 CRC-16/MODBUS（与 sb_proto.c 同算法、同口径：写进帧里低字节在前）。"""
    crc = 0xFFFF
    for byte in data:
        crc ^= byte
        for _ in range(8):
            if crc & 1:
                crc = (crc >> 1) ^ 0xA001
            else:
                crc >>= 1
    return crc & 0xFFFF


def build_frame(cmd, key=0):
    """组一帧帧 A：01 03 <cmd> <key> <CRC_L> <CRC_H>，CRC 只覆盖前 4 字节。"""
    body = bytes((ADDR, FUNC, cmd, key))
    crc = crc16_modbus(body)
    return body + bytes((crc & 0xFF, (crc >> 8) & 0xFF))


def main():
    ap = argparse.ArgumentParser(description="屏板链路台架激励（PC 顶替屏板）")
    ap.add_argument("--port", required=True, help="USB 转 TTL 适配器的串口，如 COM6")
    ap.add_argument("--baud", type=int, default=700000, help="波特率（默认 700000，与固件一致）")
    ap.add_argument("--seconds", type=float, default=30.0, help="发多久（秒），默认 30")
    ap.add_argument("--period-ms", type=float, default=280.0,
                    help="召唤周期（ms），默认 280（屏板是 RT_count>55 -> 第 56 拍 x 5 ms）")
    ap.add_argument("--key", type=int, default=0,
                    help="每 N 个周期把帧换成按键帧（0 = 只发周期召唤）")
    ap.add_argument("--glitch-baud", type=int, default=0,
                    help="先按这个（错的）波特率灌一串垃圾再正常发，用来验 ORE/NE/FE 之后能否自愈"
                         "（0 = 不灌；建议 115200）")
    ap.add_argument("--glitch-bytes", type=int, default=32,
                    help="灌多少字节垃圾（默认 32）")
    args = ap.parse_args()

    if args.period_ms <= 0 or args.seconds <= 0:
        print("[ERR] --period-ms / --seconds 必须为正")
        return 2

    rt_frame = build_frame(CMD_RT)
    print("RT frame  : %s" % rt_frame.hex(" ").upper())

    # ---- 噪声注入（可选）：用错波特率灌垃圾，制造 NE/FE/ORE ----
    # 真实现场对应的是"拔插一次 TX 线"；错波特率产生的错误更密集，是更强的考验。
    # 关键判据不是"有没有报错"，而是**之后还能不能正常收**——ORE 一旦清不掉，
    # 接收就永久进不来，现象与"屏板没上电"完全一样（见 sb_link.c 文件头第 ② 条）。
    if args.glitch_baud > 0 and args.glitch_bytes > 0:
        try:
            gser = serial.Serial(args.port, args.glitch_baud, bytesize=8, parity="N",
                                 stopbits=1, timeout=0)
            junk = bytes((0xA5, 0x5A, 0x00, 0xFF, 0x3C, 0xC3)) * (args.glitch_bytes // 6 + 1)
            gser.write(junk[:args.glitch_bytes])
            gser.flush()
            gser.close()
            print("[GLITCH] %d B @%d（错波特率灌噪声）" % (args.glitch_bytes, args.glitch_baud))
        except Exception as exc:  # noqa: BLE001
            print("[WARN] 噪声注入失败（继续正常发）：%s" % exc)

    try:
        ser = serial.Serial(args.port, args.baud, bytesize=8, parity="N", stopbits=1, timeout=0)
    except Exception as exc:  # noqa: BLE001 - 打开失败原因要原样给人看
        print("[ERR] 打开 %s @%d 失败：%s" % (args.port, args.baud, exc))
        return 1

    sent = 0
    keys = 0
    t0 = time.monotonic()
    next_at = t0
    try:
        while True:
            now = time.monotonic()
            if now - t0 >= args.seconds:
                break
            if now < next_at:
                time.sleep(min(next_at - now, 0.02))
                continue

            if args.key > 0 and (sent % args.key) == (args.key - 1):
                key = KEY_VALUES[keys % len(KEY_VALUES)]
                frame = build_frame(CMD_KEY, key)
                keys += 1
                tag = "KEY %d" % key
            else:
                frame = rt_frame
                tag = "RT"

            ser.write(frame)
            ser.flush()
            sent += 1
            if sent <= 3 or tag != "RT":
                print("  #%d %s -> %s" % (sent, tag, frame.hex(" ").upper()))

            next_at += args.period_ms / 1000.0
            # 落后太多就别追了（PC 侧卡顿不该变成突发流量）
            if next_at < time.monotonic() - 1.0:
                next_at = time.monotonic()
    except KeyboardInterrupt:
        print("\n[INFO] 用户中断")
    finally:
        ser.close()

    elapsed = time.monotonic() - t0
    print("[DONE] 发送 %d 帧（其中按键帧 %d）用时 %.1f s，平均周期 %.1f ms"
          % (sent, keys, elapsed, (elapsed * 1000.0 / sent) if sent else 0.0))
    print("[NEXT] 回看日志口：grep '[SBLINK]' —— 期望 rx == %d、ok == rx、crc=0、len=0" % sent)
    return 0


if __name__ == "__main__":
    sys.exit(main())