欢迎使用 hsflash 命令行工具！
本工具通过串口（UART）或 USB DFU 把固件镜像烧写到芯片 Flash，并支持擦除 Flash、
从板端回读数据。

支持芯片：ws63、Hi3322/3322、Brandy、bs 系列（bs20/bs21/bs22/bs25/bs26 等）、
dfu（通用 DFU 设备）等。其中 bs 系列与 3322 串口、USB DFU 都支持。

==================================================================
一、命令格式
==================================================================
Windows    ：hsflash.exe <write | erase | read | list> [参数...]
Linux/macOS：./hsflash    <write | erase | read | list> [参数...]
（下文示例 Windows 用 hsflash.exe，Linux/macOS 用 ./hsflash，仅可执行文件名不同；
  macOS 版为通用二进制，Intel 与 Apple Silicon 均原生运行）

子命令：
  write        烧写镜像 / 固件包到 Flash（fwpkg 按镜像逐个下发）
  erase        擦除 Flash（串口 / bs25、bs21、Hi3322 的 USB）
  read         从板端读取数据写入文件
  list <hid|serial>
               hid：枚举已连接的 HID 设备（芯片正常模式下的形态，输出
               Name/PID/VID/Usage/UsagePage）及 USB DFU 设备（可用 -d
               过滤）；serial：枚举可用串口；类型必填，缺省时打印支持的类型
  -h, --help   显示帮助
  -v, --version 显示版本号

==================================================================
二、参数说明
==================================================================
[连接 / 目标]
  -c, --chip <chipName>        芯片名，如 ws63
  -p, --port <port>            串口号，如 COM10（隐含串口传输方式）
  -b, --baud <rate>            波特率，默认 115200
  -s, --stop-bits <n>          停止位
      --parity <n>             奇偶校验
  -d, --device [<vid>:<pid>]   USB DFU 设备（隐含 USB 传输方式，与 -p 互斥；
                               十六进制 id，裸写 -d 自动探测唯一设备）
  -S, --serial-number <sn>     按 USB 序列号区分多台同型号设备
  -f, --file <path>            烧写文件 / 分区表（.fwpkg / .bin / .xml）
      --config <path>          指定 burn.config 配置文件路径

[USB DFU 控制]
      --transfer-size <n>      DFU 传输块大小 64-65535（设备上报值优先）
      --timeout <ms>           DFU 控制传输超时，默认 5000

[烧写控制]
  -r, --after-reset[=N]              完成后复位（裸写 -r/--after-reset 即复位，--after-reset=0 表示不复位）
      --only-burn <分区名>     仅烧写指定分区（可多次出现，累加）
      --erasemode <0-3>        擦除模式：0 常规(各擦各的) / 1 全片擦 / 2 不擦 / 3 维保(NV flag=2)
                               仅对 ws63 串口、Hi3322 串口、SE-boot USB 生效
      --burn-interval <ms>     烧写帧间隔（控制周期）
      --packet-size <n>        传输分包大小，仅允许 1024 / 2048 / 4096 / 8192
      --switch-after-loader    loader 之后切换波特率
      --before-reset           烧写前复位

[擦除控制]
  -e, --erase-size <size>      擦除大小

[读回 / export 控制]
  -a, --address <addr>         读取起始地址
  -z, --size <size>            读取大小

==================================================================
三、使用示例
==================================================================
说明：传输方式由定位参数隐含——-p 串口号 走串口，-d [vid:pid] 走 USB DFU，二者
互斥；同一颗芯片（如 bs21、3322）换 -p / -d 即切换通道。串口号 Windows 形如 COM10，
Linux 形如 /dev/ttyUSB0，macOS 形如 /dev/cu.usbserial-0001。USB DFU 烧写 Windows 需
“以管理员身份运行”，Linux / macOS 需 sudo。

------- Windows -------
# 串口：烧写固件包
hsflash.exe write -c ws63 -p COM10 -b 115200 -f C:\fw\ws63-liteos-app_all.fwpkg
# 串口：烧写后复位
hsflash.exe write -c ws63 -p COM10 -f C:\fw\ws63-liteos-app_all.fwpkg --after-reset
# 串口：仅烧写指定分区（可多次累加）
hsflash.exe write -c ws63 -p COM10 -f C:\fw\ws63-liteos-app_all.fwpkg --only-burn app --only-burn nv
# 串口：全片擦除（烧录文件用 -f 指定）
hsflash.exe erase -c ws63 -p COM10 -f C:\fw\ws63-liteos-app_all.fwpkg
# 串口：回读一段 Flash 到文件
hsflash.exe read  -c ws63 -p COM10 -a 0x0 -z 0x200000 -f dump.bin
# 枚举可用串口 / HID 设备
hsflash.exe list serial
hsflash.exe list hid
# USB DFU（需管理员；先让设备进入 DFU/boot 模式）：Hi3322 烧写
hsflash.exe write -c hi3322 -d 3361:3322 -f C:\fw\3322-diting-ft.fwpkg
hsflash.exe write -c bs21 -d -f C:\fw\fw.fwpkg                   # 裸 -d 自动探测唯一设备
hsflash.exe write -c bs21 -d 3361:3322 -S ABC123 -f C:\fw\fw.fwpkg  # 多台用序列号区分
hsflash.exe write -d -f C:\fw\app.bin                           # 不指定 -c：通用 dfu
hsflash.exe read  -c hi3322 -d -z 0x10000 -f dump.bin           # USB DFU 回读

------- Linux -------
# 串口：烧写固件包
./hsflash write -c ws63 -p /dev/ttyUSB0 -b 115200 -f ~/fw/ws63-liteos-app_all.fwpkg
# 串口：烧写后复位 / 仅烧分区 / 擦除 / 回读
./hsflash write -c ws63 -p /dev/ttyUSB0 -f ~/fw/ws63-liteos-app_all.fwpkg --after-reset
./hsflash write -c ws63 -p /dev/ttyUSB0 -f ~/fw/ws63-liteos-app_all.fwpkg --only-burn app --only-burn nv
./hsflash erase -c ws63 -p /dev/ttyUSB0 -f ~/fw/ws63-liteos-app_all.fwpkg
./hsflash read  -c ws63 -p /dev/ttyUSB0 -a 0x0 -z 0x200000 -f dump.bin
# 枚举可用串口 / HID 设备
./hsflash list serial
./hsflash list hid
# USB DFU（需 sudo 或配置 udev 规则；先让设备进入 DFU/boot 模式）
sudo ./hsflash write -c hi3322 -d 3361:3322 -f ~/fw/3322-diting-ft.fwpkg
sudo ./hsflash write -c bs21 -d -f ~/fw/fw.fwpkg                # 裸 -d 自动探测唯一设备
sudo ./hsflash write -d -f ~/fw/app.bin                         # 不指定 -c：通用 dfu
sudo ./hsflash read  -c hi3322 -d -z 0x10000 -f dump.bin        # USB DFU 回读

------- macOS -------
# macOS 版为通用二进制（x86_64 + arm64），Intel 与 Apple Silicon 均原生运行。
# 串口设备名形如 /dev/cu.usbserial-0001、/dev/cu.SLAB_USBtoUART、/dev/cu.wchusbserial*
# 串口：烧写固件包
./hsflash write -c ws63 -p /dev/cu.usbserial-0001 -b 115200 -f ~/fw/ws63-liteos-app_all.fwpkg
# 串口：烧写后复位 / 仅烧分区 / 擦除 / 回读
./hsflash write -c ws63 -p /dev/cu.usbserial-0001 -f ~/fw/ws63-liteos-app_all.fwpkg --after-reset
./hsflash write -c ws63 -p /dev/cu.usbserial-0001 -f ~/fw/ws63-liteos-app_all.fwpkg --only-burn app --only-burn nv
./hsflash erase -c ws63 -p /dev/cu.usbserial-0001 -f ~/fw/ws63-liteos-app_all.fwpkg
./hsflash read  -c ws63 -p /dev/cu.usbserial-0001 -a 0x0 -z 0x200000 -f dump.bin
# 枚举可用串口 / HID 设备
./hsflash list serial
./hsflash list hid
# USB DFU（需 sudo；先让设备进入 DFU/boot 模式；macOS 无需装驱动）
sudo ./hsflash write -c hi3322 -d 3361:3322 -f ~/fw/3322-diting-ft.fwpkg
sudo ./hsflash write -c bs21 -d -f ~/fw/fw.fwpkg                # 裸 -d 自动探测唯一设备
sudo ./hsflash write -d -f ~/fw/app.bin                         # 不指定 -c：通用 dfu
sudo ./hsflash read  -c hi3322 -d -z 0x10000 -f dump.bin        # USB DFU 回读

出现提示 "SerialPort has been connected, Please power off, then power on the device."
后，手动给设备重新上电，即开始串口烧写。

USB 烧写前需让设备进入 DFU/boot 模式；Windows 上若设备管理器显示驱动异常，
请用 Zadig 等工具安装 WinUSB 驱动；Linux 上需 sudo 或配置 udev 规则；
macOS 无需安装驱动，sudo 运行即可。
注：Windows 上 USB DFU 烧写需以管理员身份运行（烧 loader 后要对 USB 端口做断电
重枚举，该操作需要管理员权限）；否则会卡在 loader 之后的重连阶段。

==================================================================
四、配置文件 burn.config
==================================================================
不带参数时从 config/burn.config 读取（# 为注释）。常用项：
  chipName=ws63          芯片名
  filePath=xxx.fwpkg     烧写文件 / 分区表
  mode=serial            传输方式
  serialPort=COM1        串口号
  baudRate=115200        波特率
  stopBit=0
  parity=0
  reboot=0               是否复位
  openDebug=false        调试打印
USB DFU 相关（mode=usb 时生效，均可选）：
  usbVid=0x0483          USB Vendor ID 过滤
  usbPid=0xdf11          USB Product ID 过滤
  usbSerialNumber=       USB 序列号过滤
  usbTransferSize=4096   DFU 传输块大小
  usbTimeout=5000        DFU 控制传输超时(ms)
命令行参数与配置文件作用于同一组字段，命令行可覆盖配置文件。
注：配置文件键名保持不变，不要求与命令行参数名一致。

==================================================================
五、已知限制
==================================================================
- export（回读）已支持 -a(地址)/-z(大小)，但输出文件目前与 -f 共用，建议后续单独指定输出路径。
- -e/--erase-size 暂未接入烧录流程（无效果）。
