P4-USB-transfer/USB传输操作步骤.md

# USB 传输操作步骤

本流程先把独立的 SPI NAND 传输固件烧进 ESP32-P4 的主应用分区，再用同一个 USB-Serial/JTAG 虚拟串口上传文件。文件保存在板上另一颗 GD5F1GM7 SPI NAND 中；最后烧回正式 APP 时，不会因覆盖主应用分区而删除 NAND 文件。

## 1. 准备电脑和连接板子

1. 用数据线连接板子的 Type-C 下载口（P4 的 USB_DM/USB_DP，USB-Serial/JTAG），在 Windows「设备管理器」的「端口 (COM 和 LPT)」中确认其 COM 编号。以下示例用 `COM3`，实际操作时统一替换成自己的编号。当前电脑没有检测到 COM 口，文档示例不代表已经在板上验证。
2. 关闭 `idf.py monitor`、串口调试助手等占用该 COM 口的程序。**烧录和上传先后使用同一个 COM 口，不需要第二个串口程序。**
3. 打开 Windows PowerShell，切换到传输工具目录：

   ```powershell
   cd E:\PET\lab\kabao_usb\nand_xfer
   ```

4. 检查 Python 3 和串口库。这里必须用 `py -3`，不能用裸 `python`（本机的 `python` 可能是 2.7）：

   ```powershell
   py -3 --version
   py -3 -m pip show pyserial
   ```

   如果第二条显示未安装，再执行 `py -3 -m pip install pyserial`。上传脚本以 115200 波特率打开串口；USB-Serial/JTAG 可能忽略该波特率。

## 2. 烧录传输固件

**只烧这一个文件：**`E:\PET\lab\kabao_usb\nand_xfer\build_release\nand_xfer.bin`。它是独立传输 app，不是根工程的业务 APP，也不是 `bootloader.bin` 或 `partition-table.bin`。需要重新生成时，在当前目录运行：

```powershell
.\build_app.ps1
```

构建依赖 ESP-IDF 5.5.4 和对应的 ESP32-P4 工具链。

确认已找到上一节的 COM 口后，执行：

```powershell
.\flash_app.ps1 -Port COM3 -AppBin .\build_release\nand_xfer.bin
```

脚本核对本工程 `partitions.csv` 中 `ota_0` 为 `0x70000`、大小 `10M`，检查镜像，然后**只**执行一次 `write_flash 0x70000`。本流程以板子实际从该分区启动为前提，不修改启动选择。不要运行 `idf.py flash`、`erase-flash`，也不要使用 IDF 生成的 `flash_args`：那些命令可能包含 bootloader、分区表及 otadata。切勿整片擦除或改写 NVS、资源和其他数据分区。

烧录结束后板子重新启动。NAND 初始化成功时，这个 USB 虚拟串口会先输出 NAND 容量及挂载状态，随后输出单独一行 `NAND-XFER READY`；之后只有二进制传输帧，不要再开 monitor 来观察传输。没看到 READY 时不要上传，先检查端口、接线和启动状态。如果烧录后才打开端口而错过 READY，下一节的 `--info` 仍可直接握手查询。

## 3. 查询 NAND 状态

```powershell
py -3 nand_put.py COM3 --info
```

输出中的 `NAND` 是容量，`mounted=True` 表示已有 FAT 卷可写，`free` 是剩余空间。`mounted=False` 时普通上传会拒绝执行，**不会自动格式化**。如果这是确认没有需保留文件的空白 NAND，才单独运行：

```powershell
py -3 nand_put.py COM3 --format
```

脚本会要求手动输入 `FORMAT /extflash`；确认后设备才会格式化整个外置 NAND FAT 卷并重新挂载。**格式化会清空 NAND 中已有文件，不是上传的常规步骤。**完成后再次运行 `--info`，确认 `mounted=True`。如果 Windows 弹出“需要格式化磁盘”，选取消；不要用资源管理器格式化 NAND。Windows 不能直接按本卷的 NAND 逻辑页扇区布局浏览这些文件。

## 4. 上传单个文件

例如把电脑上的 `C:\files\demo.eaf` 放入设备卷的 `eaf` 目录，并在设备上命名为 `demo.eaf`：

```powershell
py -3 nand_put.py COM3 "C:\files\demo.eaf" "/extflash/eaf/demo.eaf"
```

命令结构是 `py -3 nand_put.py <COM口> "<电脑本地文件>" "<设备目标完整路径>"`。**最后一个参数就是设备上的目标路径**：这条命令创建或覆盖卷内 `eaf/demo.eaf`；`/extflash` 只是传输固件的挂载前缀，不是在 NAND 中额外创建的目录。中间目录不存在时由设备创建。文件名可用中文，带空格的路径用引号括住。

命令成功会输出 `OK`、设备目标路径、文件字节数及 `CRC32`；设备已关闭并同步文件，重新打开回读大小与 CRC 后才会报告成功。再独立查询一次：

```powershell
py -3 nand_put.py COM3 --verify "/extflash/eaf/demo.eaf"
py -3 nand_put.py COM3 --list "/extflash/eaf"
```

`--verify` 显示设备实际读到的大小和 CRC；`--list` 显示该目录里的文件名及大小。看到 `FILE demo.eaf` 就能确认文件位于卷内 `eaf` 目录。上传中断只可能影响正在写的那个文件；重新运行原上传命令会覆盖并校验该文件，之前成功完成的文件无需重新上传。

## 5. 上传整棵目录树

假设电脑目录 `C:\files\eaf` 中有 `dog.eaf`、`sub\cat.eaf` 和空目录 `empty`，要将**该目录的内容**放到设备的 `eaf` 目录：

```powershell
py -3 nand_put.py COM3 "C:\files\eaf" "/extflash/eaf" --recursive
```

对应关系如下；本地目录名本身不会在目标下再重复添加一层：

| 电脑本地位置 | 传输固件中的设备路径 | NAND 卷内相对路径 |
| --- | --- | --- |
| `C:\files\eaf\dog.eaf` | `/extflash/eaf/dog.eaf` | `eaf/dog.eaf` |
| `C:\files\eaf\sub\cat.eaf` | `/extflash/eaf/sub/cat.eaf` | `eaf/sub/cat.eaf` |
| `C:\files\eaf\empty` | `/extflash/eaf/empty` | `eaf/empty` |

脚本按相对路径上传文件并保留空目录；每个文件分别显示 `OK` 和 CRC。查询各层位置：

```powershell
py -3 nand_put.py COM3 --list "/extflash"
py -3 nand_put.py COM3 --list "/extflash/eaf"
py -3 nand_put.py COM3 --list "/extflash/eaf/sub"
```

列表中的 `DIR` 是子目录、`FILE` 是文件。也可以单独创建目录：`py -3 nand_put.py COM3 --mkdir "/extflash/eaf/newdir"`。再次运行目录上传会覆盖同名文件，但不会删除 NAND 上其他未包含在本地目录中的文件。

## 6. 复位后确认文件仍在

复位板子，等待其重新初始化；不要加 `--format`。再执行 `py -3 nand_put.py COM3 --info`，确认 `mounted=True`，然后运行上一节的 `--list` 和第四节的 `--verify`。已完成文件应继续存在且大小、CRC 一致。若不一致，停止恢复正式 APP，检查 NAND 接线、挂载和传输错误。

## 7. 烧回正式 APP

上传并验证完毕后，先确认正式 APP 的**实际 app bin 文件名与路径**，然后关闭所有占用 COM 口的程序，用同一脚本将正式 APP 烧回同一个偏移：

```powershell
.\flash_app.ps1 -Port COM3 -AppBin "E:\PET\fin_1\branch_main\IntegratedV1\build\<实际正式APP文件名>.bin"
```

请将尖括号部分替换为已构建的正式 APP 镜像名；不要直接照抄占位符。脚本仍只写内部 flash 的 `0x70000` 主应用分区，不碰另一颗 NAND 上的文件。正式 APP 把同一 NAND 卷挂载为 `/nandflash` 后，之前的 `/extflash/eaf/demo.eaf` 就对应它的 `/nandflash/eaf/demo.eaf`；卷内始终只有 `eaf/demo.eaf` 这一条相对路径。

**正式 APP 的 `fopen` 验收仍待板上验证。**当前 IntegratedV1 的 NAND GPIO 定义仍是旧引脚；本传输工具不会修改它，烧回未经引脚修正的正式 APP 后不能保证挂载成功。先完成正式 APP 的板级引脚适配与验证，再以它实际使用的 `/nandflash/...` 路径检查文件。