无线烧录网关：Web 页面与设备识别方案

1. 目标与原则

无线烧录网关是一台带 USB、UART、SWD/JTAG 和目标控制电路的嵌入式 Linux 设备。Web 页面运行在浏览器中，用于查看工位、上传固件、选择烧录配置、启动任务和查看日志。

浏览器不直接识别目标设备。 目标设备接在烧录网关上，插拔、协议探测和烧录均由网关 Linux 后台完成；后台把标准化的状态和事件通过 HTTPS/WebSocket 发送给页面。这使 Windows、macOS、Linux、Android 和 iOS 都可使用同一套 Web 界面。

设计原则：

以“物理工位”为中心展示，而不是只罗列 USB 设备。
区分“已连接”“初步识别”“协议确认”“可烧录”，避免误判。
所有烧录工作在网关本地完成；浏览器断开不应中止已开始的烧录。
所有探测、任务、日志和结果可追溯。

2. 总体数据流

目标板 / 外部烧录器
        │ USB、UART、SWD/JTAG、RESET、BOOT、PWR
        ▼
嵌入式 Linux 网关
 ├─ udev / libusb：USB 插拔和描述符识别
 ├─ 串口、SWD/JTAG、BootROM 协议探测
 ├─ 工位控制：电源、复位、启动脚、VBUS
 ├─ flasherd：状态机、任务、适配器、日志和权限
 └─ HTTPS REST + WebSocket + mDNS
        │ Wi-Fi STA/AP 或以太网
        ▼
浏览器 Web UI / 手机 Web UI / 产线系统

3. Web 页面信息架构

3.1 首页：工位总览

首页应显示所有物理接口工位，例如 USB-1、USB-2、UART-1、SWD-1。用户进入页面后首先能判断设备是否插好、处于何种模式以及是否可烧录。

页面元素	显示内容	可执行操作
工位编号	USB-1、UART-1、SWD-1 等固定物理路径	进入工位详情
接口类型	USB Boot、UART Boot、SWD/JTAG、外接调试器	无
当前状态	空闲、已接入、待识别、可烧录、烧录中、失败	重新探测、断开/重置
已识别设备	Rockchip Maskrom、STM32 DFU、J-Link、CMSIS-DAP、未知设备	查看识别依据
目标信息	芯片系列、芯片 ID、存储介质、置信度	选择/确认 Profile
最近任务	固件版本、结果、耗时、操作者	查看日志或重新执行

推荐卡片式状态颜色：灰色为空闲，蓝色为已连接/待操作，黄色为待确认或异常，绿色为成功，红色为失败，紫色为烧录中。颜色必须辅以文字，不能仅依赖颜色表达状态。

3.2 工位详情页

工位详情用于单板操作，包含以下区域：

连接与识别：物理路径、USB VID/PID、序列号、串口参数、SWD IDCODE、最近一次探测时间和原始探测日志。
目标控制：目标电源、VBUS、RESET、BOOT/STRAP 当前状态；提供“断电重试”“进入下载模式”“重新枚举”等受权限控制的按钮。
烧录配置：可选 Profile、固件文件、镜像分区、擦除策略和验证方式。
任务执行：开始、取消、实时进度、当前步骤、耗时和结构化日志。
历史记录：该工位最近任务以及使用的 Profile/固件哈希。

3.3 其他页面

固件库：上传、SHA-256、签名状态、版本、适用芯片与删除策略。
任务中心：队列、并发状态、成功率、失败分类、日志导出。
适配器与设备：列出网关识别到的 J-Link、CMSIS-DAP、ST-Link、USB-UART 等外设及其序列号。
Profile 管理：仅管理员可发布、启用、停用或回滚烧录配置。
系统设置：Wi-Fi STA/AP、以太网、账号、证书、时间同步、网关升级和诊断包导出。

4. 设备识别实现思路

识别应分为“物理设备识别”和“目标芯片协议确认”两层。前者快速、无侵入；后者可能需要切换 BOOT/RESET 或发送探测命令，应由用户授权或 Profile 控制。

4.1 USB 设备与烧录器识别

Linux 后台用 udev 订阅 add/remove/change 事件，并以 libusb 或 sysfs 读取：

USB VID/PID、bcdDevice、厂商名、产品名、序列号；
USB 接口类别、端点、已绑定驱动；
总线号与端口拓扑路径；
设备节点，例如 /dev/ttyACM*、/dev/ttyUSB*、/dev/bus/usb/*。

识别库维护一份签名表：VID/PID + 接口类 + 可选产品字符串 映射为设备类型，如 Rockchip Maskrom/Loader、Allwinner FEL、NXP SDP、STM32 DFU、J-Link、CMSIS-DAP、ST-Link 或 USB-UART。

不能仅使用 /dev/ttyUSB0 这类动态名称。应以 USB 物理路径或 udev 规则建立稳定别名，例如：

USB 根端口 1-2.3  →  usb-slot-1
USB 根端口 1-2.4  →  usb-slot-2
/dev/serial/by-slot/uart-1  →  uart-slot-1

这样设备重新枚举后，页面仍能对应正确工位。

4.2 USB BootROM 目标识别

当 RK、Allwinner、NXP i.MX 或 MCU 进入 USB BootROM/DFU 模式时，通常会以特定 VID/PID 枚举。后台按识别规则匹配后显示“初步识别”，并可调用对应 adapter 执行只读探测：

Rockchip：确认 Maskrom/Loader 状态和目标信息；
Allwinner：确认 FEL 握手与芯片信息；
NXP i.MX：确认 SDP/UUU 可连接状态；
DFU：读取 DFU 接口能力和设备描述符。

只有探测成功且匹配已发布的 Profile 时，状态才变为“可烧录”。若仅发现普通 USB 枚举，页面应显示“未知 USB 设备”，不能声称已识别出芯片型号。

4.3 UART 目标识别

UART 没有类似 USB 的插拔/枚举机制。网关能确认的只有“USB-UART 适配器或板载 UART 已可用”，不能天然知道线缆另一端是什么 MCU。

推荐流程：

工位配置候选 Profile，例如 ESP、STM32 UART Boot、NXP ISP。
用户选择“自动探测”或指定 Profile。
网关按受控时序控制 PWR、RESET、BOOT/STRAP。
adapter 向 BootROM 发送对应的安全握手命令。
根据响应、芯片 ID 或 ROM 版本确认目标；失败则恢复电平并显示原因。

页面状态应为“UART 已连接，目标待确认”或“STM32 UART Boot 已确认”，而非仅凭串口存在就猜测目标型号。

4.4 SWD/JTAG 目标识别

先识别探针，再识别目标：

用 USB 描述符与序列号识别 J-Link、CMSIS-DAP、ST-Link 等探针。
使用 CMSIS-DAP/OpenOCD 或合规的厂商工具读取 SWD DP IDCODE、JTAG IDCODE、芯片唯一 ID 或目标存储信息。
根据 IDCODE 映射芯片系列；存在歧义时要求用户选择精确型号/Profile。

调试扫描可能影响部分低功耗目标或需要上电，所以页面应提供“自动扫描”开关；生产工位默认只扫描已授权的目标类型。

4.5 识别置信度与手动确认

所有识别结果保存来源和置信度：

级别	含义	页面示例
未识别	仅检测到物理连接	已检测到 USB 设备，未匹配 Profile
初步识别	VID/PID 或探针类型匹配	已识别为 Rockchip Maskrom
协议确认	BootROM/SWD/UART 握手成功	RK3568 Loader 可连接
Profile 确认	芯片、接口、存储和 Profile 均匹配	可执行 `rk3568-emmc-v1`

用户可手动选择 Profile，但页面必须提示“手动覆盖识别结果”，并在任务日志中记录该操作。

5. 工位状态机

空闲
  └─ 物理设备插入 → 已接入
       ├─ 描述符/探针匹配 → 初步识别
       │    └─ 执行安全探测 → 协议确认
       │         └─ 匹配 Profile → 可烧录
       └─ 不匹配 → 未识别

可烧录 → 创建任务 → 切换下载模式 → 探测 → 擦除 → 写入 → 校验 → 复位启动
       └────────────────────────────────────────────→ 成功 / 失败 / 已断开

状态更新由后台写入数据库并通过 WebSocket 推送。网络或浏览器中断只影响显示；正在执行的本地烧录任务仍继续。任务完成后，用户重新进入页面即可查询结果。

6. 后端服务设计

建议在嵌入式 Linux 中运行一个核心服务 flasherd，负责接口访问、状态机、烧录工具调度和 API。它不应把任意用户输入直接传给 shell；adapter 必须根据 Profile 生成受白名单保护的固定参数。

6.1 模块划分

模块	责任
Slot Manager	管理物理工位、端口映射、锁和状态机
Device Monitor	接收 udev 事件，读取 USB/串口/探针信息
Probe Service	执行 USB BootROM、UART、SWD/JTAG 的安全探测
Adapter Runner	封装 rkdeveloptool、UUU、sunxi-fel、OpenOCD、dfu-util、esptool 等工具
Power/Pin Controller	控制 PWR、VBUS、RESET、BOOT/STRAP 并读取故障状态
Job Manager	任务队列、超时、取消、恢复、结果和审计
Artifact Store	固件上传、分块续传、SHA-256、签名与本地缓存
API Gateway	REST/gRPC、WebSocket、认证、权限和限流

6.2 核心 API

API	作用
`GET /api/v1/slots`	返回全部工位及当前识别状态
`GET /api/v1/slots/{id}`	返回单工位的设备信息、能力和最近任务
`POST /api/v1/slots/{id}/probe`	请求受控探测或重新枚举
`POST /api/v1/slots/{id}/boot-mode`	执行进入下载模式的电源/引脚时序
`POST /api/v1/artifacts`	分块上传固件，服务端计算 SHA-256
`GET /api/v1/profiles`	返回当前账号可用的烧录 Profile
`POST /api/v1/jobs`	创建烧录任务，包含工位、Profile 和固件
`GET /api/v1/jobs/{id}`	获取状态、进度、结果和日志索引
`WS /api/v1/events`	推送插拔、识别、进度和日志事件

7. 推荐技术栈

层	建议
前端	Vue 3 + TypeScript + Vite + Element Plus；构建后为静态文件
后端	Go 或 Rust；首版优先 Go，便于 API、并发、交叉编译和系统服务集成
实时通信	WebSocket；页面首次加载用 REST 获取快照，再消费事件流
Linux 外设	udev、libusb、udev rules、termios、libgpiod、systemd
烧录适配	OpenOCD/CMSIS-DAP、dfu-util、esptool、rkdeveloptool、UUU、sunxi-tools；逐项核对许可和 ARM Linux 支持
数据	SQLite 保存元数据/任务；eMMC 文件目录保存固件与完整日志
发现与安全	mDNS、HTTPS、设备证书、RBAC、固件 SHA-256/签名

前端静态资源可由 flasherd 直接提供，第一版无需另引入 Nginx、容器编排或云端依赖。

8. 数据模型建议

Slot
  id, type, physical_path, state, power_state, attached_device_id

DetectedDevice
  id, slot_id, transport, vid, pid, serial, manufacturer, product,
  probe_result, chip_family, chip_id, confidence, last_seen_at

Profile
  id, version, vendor, chip_models, adapter, required_slot_type,
  boot_sequence, image_layout, verify_policy, enabled

Job
  id, slot_id, device_id, profile_id, artifact_hash, status,
  operator, created_at, started_at, finished_at, result_code

9. 实施顺序

先完成单 USB 工位：udev 插拔事件 → WebSocket 推送 → 页面显示 VID/PID、产品名、物理路径。
加入单个目标的 Profile 和“进入下载模式 → 探测 → 烧录 → 校验”闭环，例如 STM32 DFU 或 RK Maskrom。
增加 UART 与 SWD/JTAG 识别，建立“适配器”和“目标”分层模型。
扩展到多工位，解决端口固定映射、独占锁、独立电源和并发任务。
完成账号权限、固件签名、任务审计、OTA 和产线 API。

10. 验收标准

插拔已支持的 USB 目标后，Web 页面在 2 秒内更新正确工位和初步识别信息。
对已建立 Profile 的目标，可一键进入下载模式并在页面显示协议确认结果。
同一工位在重插、USB 重新枚举后仍保持固定工位编号。
浏览器断开后，已开始的烧录任务继续执行并可重新查询。
每次任务记录固件哈希、Profile 版本、设备识别信息、操作者、日志、耗时和最终校验结果。
未识别设备和识别不确定设备不会被自动烧录，必须由已授权用户明确选择 Profile。

📒 笔记文档