# Hardware Lab 编译烧录环境安装说明

适用对象：Windows 10/11，同学拿到本压缩包后，希望通过 Hardware Lab 网页完成 MCU 项目的扫描、编译、烧录和证据记录。

重要边界：线上网页本身不能直接访问 USB、串口、文件系统或编译器。真实编译烧录必须先在本机运行本包里的 `backend\hardware_lab_backend.js`，网页再通过 `http://127.0.0.1:8765` 调用本机后端。

## 1. 包内已经包含的文件

解压后目录大致如下：

```text
hardware-lab-compile-flash-kit-20260725/
  Hardware_Lab_编译烧录环境安装说明.md
  start-hardware-lab-backend.cmd
  install-pyocd-offline.cmd
  check-environment.ps1
  open-hardware-lab-online.url
  backend/
    hardware_lab_backend.js
  files/
    packs/
      TexasInstruments.MSPM0G1X0X_G3X0X_DFP.1.3.1.pack
    pyocd-wheelhouse/
      pyocd-0.43.1 和依赖 wheel 文件
    sample-project-config/
      project.json
    docs/
      10_Hardware_Lab本机后端说明.md
```

包内已带：

- 本机后端脚本：`backend\hardware_lab_backend.js`
- pyOCD 0.43.1 离线 wheelhouse：`files\pyocd-wheelhouse`
- TI MSPM0 DFP pack：`files\packs\TexasInstruments.MSPM0G1X0X_G3X0X_DFP.1.3.1.pack`
- 示例项目配置：`files\sample-project-config\project.json`
- 后端说明文档：`files\docs\10_Hardware_Lab本机后端说明.md`

说明：网站上架包需要小于 Cloudflare Pages 单文件大小限制，因此不内置 Node、Arm GCC、TI SDK、Keil、STM32CubeProgrammer 或完整本地前端资源。这些大文件请按第 2 节安装。

## 2. 仍需要在电脑上安装的环境

### 必装：DAPLink/MSPM0G3507/Makefile 项目

1. Python 3.10 或更新版本，安装时勾选 `Add python.exe to PATH`。
2. Node.js 20 或更新版本，确保命令行能运行 `node --version`。
3. pyOCD：可以用本包离线安装。
4. Arm GNU Toolchain，确保命令行能运行 `arm-none-eabi-gcc`。
5. Make 工具，确保命令行能运行 `mingw32-make`。
6. TI MSPM0 SDK。推荐安装在类似 `C:\ti\mspm0_sdk_2_07_00_05` 的路径，后端也会自动扫描 `C:\ti\mspm0_sdk_*`。
7. DAPLink/CMSIS-DAP 硬件，SWDIO、SWCLK、GND、RST/NRST 必须接好，目标板需要供电。

### 按项目类型选装

- CMake 项目：安装 CMake；使用 Ninja 时还要安装 Ninja。
- Keil 工程：安装 Keil MDK，后端需要能调用 `UV4.exe`。
- STLink/STM32：安装 STM32CubeProgrammer，确保命令行能运行 `STM32_Programmer_CLI`。
- CCS/TI M0：安装对应 TI 工具链和项目需要的 SysConfig/SDK。

官方下载入口：

- Python：<https://www.python.org/downloads/>
- Node.js：<https://nodejs.org/>
- Arm GNU Toolchain：<https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>
- TI MSPM0 SDK：<https://www.ti.com/tool/MSPM0-SDK>
- STM32CubeProgrammer：<https://www.st.com/en/development-tools/stm32cubeprog.html>

## 3. 第一次安装步骤

1. 解压本压缩包到英文路径或短路径，例如 `D:\HardwareLabKit`。
2. 安装 Python，并确认：

```powershell
python --version
```

3. 离线安装 pyOCD：

```powershell
install-pyocd-offline.cmd
```

4. 安装 Node.js、Arm GNU Toolchain 和 `mingw32-make`，确认：

```powershell
node --version
arm-none-eabi-gcc --version
mingw32-make --version
```

5. 安装 TI MSPM0 SDK，并确认 SDK 目录里有 `imports.mak`。
6. 运行环境检查：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\check-environment.ps1
```

7. 启动本机后端：

```cmd
start-hardware-lab-backend.cmd
```

看到类似下面输出表示后端已启动：

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

8. 打开 Hardware Lab：

- 在线入口：<https://nuedc-components-atlas-public.pages.dev/hardware-lab>
- 本机入口：如果你拿到的是完整离线包，可打开 <http://127.0.0.1:8765/hardware-lab.html>；网站上架轻量包默认使用在线入口。

## 4. 在网页里编译烧录

1. 进入 `编译烧录` 模块。
2. 点击选择项目文件夹，选择 MCU 工程根目录。
3. 点击扫描，选择目标 DAPLink 或 STLink。不要手填别人的 UID，UID 必须来自当前电脑扫描结果。
4. 选择目标芯片，例如 `MSPM0G3507`。
5. 选择 SWD 速率。DAPLink/MSPM0 建议先用 `500 kHz`，稳定后再提高。
6. 点击 `编译`、`烧录` 或 `编录`。
7. 观察实时日志。成功后 output 目录会生成 evidence JSON。

## 5. 配置文件说明

每个工程可以有自己的配置文件：

```text
<你的 MCU 工程目录>\.mcu-tool\project.json
```

这个文件用于记录 build profile、flash profile、芯片、烧录器类型、确认状态和 artifact 规则。包内的 `files\sample-project-config\project.json` 只是参考模板，里面的 UID 不能直接照抄给别人用；每台电脑都应该在网页里扫描并选择自己的 DAPLink/STLink。

## 6. 常见问题

### 网页提示后端离线

先运行 `start-hardware-lab-backend.cmd`。线上网页只是界面，不能自己启动本机后端。

### 扫描不到 DAPLink

检查 USB、目标板供电、GND、SWDIO、SWCLK、RST/NRST。关闭 Keil、pyOCD、OpenOCD、串口助手等可能占用探针的程序，然后重新插拔 DAPLink。

### MSPM0G3507 提示 pack missing

本包已经带了 TI DFP pack。正常从 `start-hardware-lab-backend.cmd` 启动时，会设置 `HARDWARE_LAB_MSPM0_PACK` 指向包内 pack。如果你手动启动后端，请加上：

```cmd
set HARDWARE_LAB_MSPM0_PACK=%CD%\files\packs\TexasInstruments.MSPM0G1X0X_G3X0X_DFP.1.3.1.pack
```

### 编译失败，提示 SDK 找不到

确认 TI MSPM0 SDK 安装在 `C:\ti\mspm0_sdk_*`，或者在项目/网页设置里指定 SDK 路径。Makefile 项目通常依赖 `MSPM0_SDK_INSTALL_DIR`。

### 烧录失败但扫描能看到探针

不要连续乱试高频率。先降到 `500 kHz` 或 `100 kHz`，确认 RST/NRST 已连接、目标板供电稳定，并关闭其他 SWD 占用者。

## 7. 给同学发包时的最短说明

把整个 ZIP 发给对方。对方解压后按顺序执行：

```cmd
install-pyocd-offline.cmd
start-hardware-lab-backend.cmd
```

然后打开：

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

如果对方电脑还没有 Python、Arm GCC、mingw32-make 或 MSPM0 SDK，需要先按第 2 节安装。
如果对方电脑还没有 Node.js，也需要先安装 Node.js。
