P4-USB-transfer/README.md

# P4 USB 传输

ESP32-P4 工程，仓库里有两套程序。

- 根目录是设备主固件。界面、蓝牙、Wi-Fi、表情包和外置 SPI NAND 都在这里。外置盘挂载点是 `/extflash`，表情文件放在 `/extflash/eaf/`。
- `nand_xfer/` 是单独的 NAND 传输固件。电脑通过板载 USB Serial/JTAG 把文件写到同一块外置 NAND，设备侧路径同样以 `/extflash` 开头。

分区表在 `partitions.csv`，与 IntegratedV1 相同。传输固件只覆盖 `ota_0`（偏移 `0x70000`，大小 10MB），不改 bootloader、分区表和 NVS。串口协议见 `nand_xfer/README.md`。

## 构建 USB 传输固件

传输固件的目录是 `E:\PET\lab\kabao_usb\nand_xfer`。打开 PowerShell，在这个目录里编译：

```powershell
cd E:\PET\lab\kabao_usb\nand_xfer
.\build_app.ps1
```

`build_app.ps1` 使用本机 ESP-IDF 5.5.4，目标芯片是 ESP32-P4。编译完成后的固件是：

`E:\PET\lab\kabao_usb\nand_xfer\build_release\nand_xfer.bin`

烧录前关掉「NAND 传输」窗口和串口监视器。把下面的 `COM3` 换成设备管理器里 USB Serial/JTAG 的端口：

```powershell
cd E:\PET\lab\kabao_usb\nand_xfer
.\flash_app.ps1 -Port COM3 -AppBin .\build_release\nand_xfer.bin
```

`flash_app.ps1` 只把 `nand_xfer.bin` 写到 `0x70000`。仓库根目录 `E:\PET\lab\kabao_usb` 是设备主固件，传文件时留在 `nand_xfer` 里用上面两条脚本，不要在根目录执行 `idf.py build` 或 `idf.py flash`。

## 上位机

Windows 程序：`nand_xfer/NAND_Xfer.exe`。双击打开，窗口标题是「NAND 传输」。它把本机一个目录批量写到设备的 FLASH 目录。

使用前先让板子跑着 `nand_xfer` 固件，USB 接到 P4 的 USB Serial/JTAG，并关掉占用该 COM 口的其它程序，包括 `idf.py monitor`。

1. **端口**：下拉选择串口。描述里带 `303A` 或 `Serial/JTAG` 的口排在前面。没有口时点「刷新」，并确认线已插上。
2. **本地目录**：要上传的文件夹。默认是 `E:\PET\EAF`，点「浏览」可以换。上传的是这个目录里面的内容，子目录会保留。
3. **FLASH目录**：设备上的目标路径。默认是 `/extflash/eaf`。

按钮：

- **查询**：显示 NAND 容量、是否已挂载、FAT 总空间和剩余空间。日志里出现「未挂载」时，新盘要先格式化，再列目录或写入。
- **列目录**：列出 FLASH 目录。目录显示为 `DIR`，文件显示为 `FILE` 加字节数。
- **批量写入**：按本地目录逐个写入。每个文件在设备上关闭、同步、回读并做 CRC 校验后才算成功。进度按文件个数走。某个文件失败时，日志里会记下名字，其余文件继续。再传一次会覆盖未完成的文件。
- **停止**：当前这个文件结束后不再继续。已经写完的文件保留。
- **格式化**：清空整块外置 NAND 上的文件。新盘第一次使用时做这一步。确认框里输入 `FORMAT /extflash` 才会执行，大约一两分钟。盘上已有表情文件时不要格式化。格式化由设备按 16KB 簇完成；不要在 Windows 资源管理器里格式化这块盘。

写入结束后，窗口会再列一次目标目录。

## 命令行

同一套传输也可以用 Python 脚本，工作目录是 `nand_xfer`：

```powershell
py -3 -m pip install pyserial
py -3 nand_put.py COM3 "C:\files\demo.eaf" "/extflash/eaf/demo.eaf"
py -3 nand_put.py COM3 "C:\files\eaf" "/extflash/eaf" --recursive
py -3 nand_put.py COM3 --info
py -3 nand_put.py COM3 --list "/extflash/eaf"
```

`--format` 会清空 NAND，执行前要在提示里输入确认文字。完整命令、烧录脚本和协议见 `nand_xfer/README.md`。

## 重新打包上位机

在 `nand_xfer` 目录执行：

```powershell
.\build_gui.ps1
```

脚本用本目录的虚拟环境调用 PyInstaller，产物是 `nand_xfer\dist\NAND_Xfer.exe`。要更新仓库里的发布文件时，用这个新文件覆盖 `nand_xfer\NAND_Xfer.exe`。