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

支持芯片：ws63、Hi3322/3322/Hi3372、Brandy、bs 系列
（bs20/bs20c/bs20h/bs21/bs21a/bs21e/bs22/bs25/bs26/bs27a 等）、
dfu（通用 DFU 设备）等。USB 能力按 ChipProperties 逐型号配置，并非同一协议族成员都自动支持。

==================================================================
一、命令格式
==================================================================
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（串口 / 支持 SE-boot 的 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（隐含串口传输方式）
      --reset-at-port <port>   USB AutoDFU 烧写前持续发送 AT 的辅助串口（仅 autodfu）
  -b, --baud <rate>            波特率，默认 115200
  -s, --stop-bits <n>          停止位
      --parity <n>             奇偶校验
  -d, --device [<vid>:<pid>]   USB DFU 设备（隐含 USB 传输方式，与 -p 互斥；
                               十六进制 id，裸写 -d 自动探测唯一设备）
      --usb-dfu-mode <mode>    USB 模式：dfu / autodfu（默认）/ hiddfu；
                               别名：--dfu、--autodfu、--hiddfu
  -S, --serial-number <sn>     按 USB 序列号区分多台同型号设备
      --usage <hex>            按 HID 顶层 Usage 筛选 dfu / hiddfu 接口
      --usage-page <hex>       按 HID 顶层 UsagePage 筛选（兼容 --usagepage）
  -f, --file <path>            烧写文件 / 分区表（.fwpkg / .bin / .xml）
  -o, --output <path>          回读输出文件（read 命令必填）
      --config <path>          指定 burn.config 配置文件路径

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

[烧写控制]
  -r, --after-reset[=N]              完成后复位（默认复位；=0 表示不复位，旧形式保持兼容）
      --only-burn <分区名>     仅烧写指定分区（可多次出现，累加）
      --erasemode <0-3>        擦除模式：0 常规(各擦各的) / 1 全片擦 / 2 不擦 / 3 维保(NV flag=2)
                               对支持的串口芯片和 SE-boot USB 生效
      --burn-interval <ms>     烧写帧间隔，1-30 毫秒（控制周期）
      --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
# 串口：仅烧写指定分区（可多次累加）
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
# Brandy：从 fwpkg 提取并下载 SSB 后执行全片擦除（-e/--erase-size 不生效）
hsflash.exe erase -c Brandy -p COM10 -f C:\fw\brandy.fwpkg
# 串口：回读一段 Flash 到文件
hsflash.exe read  -c ws63 -p COM10 -a 0x0 -z 0x200000 -f ws63-liteos-app_all.fwpkg -o 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 hi3322 -d 3361:3322 --usb-dfu-mode hiddfu -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 hi3322.fwpkg -o 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
./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 ws63-liteos-app_all.fwpkg -o 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 hi3322 -d 3361:3322 --hiddfu -f ~/fw/3322-diting-ft.fwpkg  # HID DFU
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 hi3322.fwpkg -o 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
./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 ws63-liteos-app_all.fwpkg -o 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 hi3322 -d 3361:3322 --hiddfu -f ~/fw/3322-diting-ft.fwpkg  # HID DFU
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 hi3322.fwpkg -o 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
  reset=1                是否复位（默认复位；命令行可用 --after-reset=0 禁用）
  openDebug=false        统一调试日志总开关（默认关闭）
  debugLogPath=          可选日志文件路径；留空时为当前目录 hsflash-debug.log
开启 openDebug=true 后，日志以追加方式记录并包含时间戳/线程号、串口打开参数、原始
SERIAL_TX/RX 十六进制数据（单条最多 256 字节）、协议帧、Brandy 握手与 SSB 擦除、DFU
状态、USB 控制传输及错误结果；同时显示现有控制台调试信息。旧的 HSFLASH_SERIAL_TRACE
环境变量已移除，不再生效。日志可能包含设备输出和烧写数据，反馈前请按需脱敏。
USB DFU 相关（mode=usb 时生效，均可选）：
  usbVid=0x0483          USB Vendor ID 过滤
  usbPid=0xdf11          USB Product ID 过滤
  usbSerialNumber=       USB 序列号过滤
  usbTransferSize=4096   DFU 传输块大小
  usbTimeout=5000        DFU 控制传输超时(ms)
  usbDfuMode=autodfu     dfu / autodfu / hiddfu（默认 autodfu）
  usbHidUsage=0x2        可选：HID 顶层 Usage 过滤
  usbHidUsagePage=0xff00 可选：HID 顶层 UsagePage 过滤
芯片属性文件还可配置：
  UsbNeedsLoader=true    ROM 需先下载 loader 并等待 USB 重枚举（Hi3322/Hi3372 按 ChipType 默认启用）
                         ResetAtPort 仅 autodfu 可用；ResetAtCommand 配置后也可用于串口 before-reset；
                         hiddfu 每个 HID report 写后立即读 ACK，末包再校验整镜像 CRC。
                         hiddfu 必须指定支持 SE-boot 命令的具体芯片，不支持通用 -c dfu。
                         --transfer-size/--timeout 仅影响标准 libusb DFU；
                         hiddfu 使用固定 HID 报文长度和 HID 超时策略。
命令行参数与配置文件作用于同一组字段，命令行可覆盖配置文件。
注：配置文件键名保持不变，不要求与命令行参数名一致。

==================================================================
五、已知限制
==================================================================
- read 使用 -f 指定 loader 固件包，使用 -o 指定回读输出文件。
- -e/--erase-size 暂未接入烧录流程（无效果）。
