# Hardware Lab 本机后端说明

更新时间：2026-07-24

## 作用边界

Cloudflare Pages 上的静态站可以做图鉴、planner、接线表、导出和设置保存，但不能直接访问本机 USB、串口、文件系统或编译器。

`scripts/hardware_lab_backend.js` 是 Hardware Lab 的本机桥接服务，默认监听：

```powershell
http://127.0.0.1:8765
```

当前端设置里的“后端地址”保持为这个地址时，页面会请求：

- `POST /api/health`
- `POST /api/scan`
- `POST /api/build`
- `POST /api/flash`
- `POST /api/uart`

这些接口都统一返回：

```json
{
  "ok": true,
  "message": "...",
  "data": {},
  "logs": [],
  "error": null
}
```

`/api/scan` 会同时读取 pyOCD、STM32CubeProgrammer/st-info、Windows PnP USB 设备和串口，并在 `data.diagnostics` 里给出分层 readiness 结论。它用于区分“Windows 已看到 DAPLink/STLink”与“pyOCD/STM32 工具链已经能接管探针”，扫描不会执行烧录。

同时，`/api/scan` 会在 `data.project.entry` 里返回项目构建入口摘要。当前真实构建执行范围是 CMake 和 Makefile；Keil `.uvprojx`、CCS `.ccsproject/.project`、SysConfig `.syscfg` 会被识别并展示，但在配置好命令行构建前不会烧录旧产物。

## 启动

在一个终端里运行：

```powershell
cd /d "E:\Learning\嵌入式\电赛备赛\元器件资料"
node scripts\hardware_lab_backend.js
```

看到类似输出就说明后端已启动：

```text
Hardware Lab backend HL-G001-0.5.1 listening on http://127.0.0.1:8765
```

然后打开 Hardware Lab：

```powershell
python -m http.server 8788 --bind 127.0.0.1
```

浏览器访问：

```text
https://nuedc-components-atlas-public.pages.dev/hardware-lab.html
```

如果只看本地开发页，也可以访问：

```text
http://127.0.0.1:8788/hardware-lab-prototype.html?variant=dashboard#
```

## 真实 Build + Flash 门禁

前端主按钮只有 `Build + Flash`，内部按顺序执行：

1. `health`
2. `scan`
3. `build`
4. fresh artifact 检查
5. `flash`
6. 写入 evidence

真实烧录不会默认放行。设置页必须填写：

```text
允许真实烧录 = true
确认短语 = I_UNDERSTAND_FLASH_RISK
```

DAPLink/MSPM0G3507 同时必须满足：

- `targetProbe` 是精确 probe UID，不能模糊选择。
- `targetChip` 能映射到已支持目标，例如 `MSPM0G3507`。
- `/api/build` 刚生成了 fresh `.hex/.elf/.axf/.bin`。
- `pyocd list --probes` 能看到该 UID。

MSPM0G3507 + DAPLink 默认走：

```text
pyOCD target = mspm0g3507
probe UID = 031305620164
```

STLink/STM32 走 STM32CubeProgrammer，必须满足：

- `programmerType` 包含 `STLink`。
- `targetChip` 是 STM32，例如 `STM32F103` / `STM32F407`。
- `targetProbe` 是精确 STLink SN/UID。
- 本机能找到 `STM32_Programmer_CLI`。
- fresh artifact 是 `.hex/.elf/.axf`；如果是 `.bin`，还需要 `flashAddress`，例如 `0x08000000`。

当前端提示 `Flash blocked by safety gate` 时，说明后端没有碰硬件，原因会写在页面 evidence 和 `output/hardware-lab-evidence/*.json`。

## 停止

如果后端是在前台运行的，回到启动后端的终端按：

```text
Ctrl+C
```

如果静态页服务也是前台运行的，也在对应终端按：

```text
Ctrl+C
```

## 当前端点状态

- `/api/health`：真功能，返回后端版本、工作目录、Node 版本、工具链可见性。
- `/api/scan`：真功能，尝试扫描 `pyocd list --probes`、STLink（`STM32_Programmer_CLI -l` / `st-info --probe`）和 Windows 串口；工具缺失时返回结构化结果，不崩溃。
- `/api/build`：真功能入口，支持已配置的 CMake build 目录和 Makefile 工程；路径或工具缺失时返回 `ok:false`。
- `/api/flash`：真实烧录入口，但有安全门禁；门禁不满足时返回 blocked，不会碰硬件。DAPLink/MSPM0G3507 使用 pyOCD，STLink/STM32 使用 STM32CubeProgrammer。
- `/api/uart`：真功能入口；未配置 `serialPort`/`uartPort`/`logPort` 时返回结构化失败，配置 COM 口后尝试短时读取。

## 当前实测状态

2026-07-24 本轮验证时，`pyocd list --probes` 返回：

```text
No available debug probes are connected
```

因此软件链路已经跑到 fresh artifact + flash gate，但当前机器没有可见 DAPLink，不能宣称真实板卡已烧录成功。接上 DAPLink 后重新扫描，看到 UID 后再点 `Build + Flash`。
