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，切换到传输工具目录：

   cd E:\PET\lab\kabao_usb\nand_xfer
   

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

   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。需要重新生成时，在当前目录运行：

.\build_app.ps1

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

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

.\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 状态

py -3 nand_put.py COM3 --info

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

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：

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 后才会报告成功。再独立查询一次：

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 目录：

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。查询各层位置：

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 烧回同一个偏移：

.\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/... 路径检查文件。