Welcome to the hsflash command line tool!
This tool burns firmware images onto a chip's Flash over the serial port (UART)
or USB DFU, and also supports erasing the Flash and reading data back from the
board.

Supported chips: ws63, Hi3322/3322, Brandy, the bs family (bs20/bs21/bs22/bs25/
bs26 ...), dfu (generic DFU device), etc. The bs family and 3322 support both
serial and USB DFU.

==================================================================
1. Command format
==================================================================
Windows     : hsflash.exe <write | erase | read | list> [options...]
Linux/macOS : ./hsflash    <write | erase | read | list> [options...]
(The examples below use hsflash.exe on Windows and ./hsflash on Linux/macOS; only
the executable name differs. The macOS build is a universal binary that runs
natively on both Intel and Apple Silicon.)

Commands:
  write        Burn an image / firmware package to Flash (fwpkg image by image)
  erase        Erase the Flash (serial, or USB on bs25 / bs21 / Hi3322)
  read         Read flash data back into a file
  list <hid|serial>
               hid: attached HID devices (how chips appear in normal mode,
               printing Name/PID/VID/Usage/UsagePage) and USB DFU devices,
               optionally filtered by -d;
               serial: available serial ports;
               the type is mandatory -- without it the supported types are printed
  -h, --help   Show help
  -v, --version Show version

==================================================================
2. Options
==================================================================
[Connection / target]
  -c, --chip <chipName>        Chip name, e.g. ws63
  -p, --port <port>            Serial port, e.g. COM10 (implies serial transport)
  -b, --baud <rate>            Baud rate, default 115200
  -s, --stop-bits <n>          Stop bits
      --parity <n>             Parity
  -d, --device [<vid>:<pid>]   USB DFU device (implies USB transport, excludes -p;
                               hex ids, bare -d auto-detects a single device)
  -S, --serial-number <sn>     Pick one of several identical USB devices
  -f, --file <path>            Burn file / partition table (.fwpkg / .bin / .xml)
      --config <path>          Path to burn.config

[USB DFU control]
      --transfer-size <n>      DFU chunk size 64-65535 (device value wins)
      --timeout <ms>           DFU control-transfer timeout, default 5000

[Burn control]
  -r, --after-reset[=N]              Reset after finishing (bare -r/--after-reset = reset, --after-reset=0 = no)
      --only-burn <partition>  Burn only the given partition (repeatable)
      --erasemode <0-3>        Erase mode: 0 normal / 1 erase-all / 2 no-erase / 3 maintenance (NV flag=2)
                               Applies to ws63 serial, Hi3322 serial and SE-boot USB
      --burn-interval <ms>     Inter-frame interval (control period)
      --packet-size <n>        Transfer packet size, only 1024 / 2048 / 4096 / 8192
      --switch-after-loader    Switch baud after loader
      --before-reset           Reset before burning

[Erase control]
  -e, --erase-size <size>      Erase size

[Export control]
  -a, --address <addr>         Read start address
  -z, --size <size>            Read size

==================================================================
3. Examples
==================================================================
The transport is implied by the locator: -p <port> uses serial, -d [vid:pid]
uses USB DFU (the two are mutually exclusive). The same chip (e.g. bs21, 3322)
switches transport just by using -p or -d. Serial ports look like COM10 on
Windows, /dev/ttyUSB0 on Linux and /dev/cu.usbserial-0001 on macOS. USB DFU
flashing needs "Run as Administrator" on Windows and sudo on Linux / macOS.

------- Windows -------
# serial: burn a firmware package
hsflash.exe write -c ws63 -p COM10 -b 115200 -f C:\fw\ws63-liteos-app_all.fwpkg
# serial: burn and then reset
hsflash.exe write -c ws63 -p COM10 -f C:\fw\ws63-liteos-app_all.fwpkg --after-reset
# serial: burn specific partitions only (repeatable)
hsflash.exe write -c ws63 -p COM10 -f C:\fw\ws63-liteos-app_all.fwpkg --only-burn app --only-burn nv
# serial: erase the whole chip (image given with -f)
hsflash.exe erase -c ws63 -p COM10 -f C:\fw\ws63-liteos-app_all.fwpkg
# serial: read back a Flash range to a file
hsflash.exe read  -c ws63 -p COM10 -a 0x0 -z 0x200000 -f dump.bin
# list available serial ports / HID devices
hsflash.exe list serial
hsflash.exe list hid
# USB DFU (Administrator; put the device in DFU/boot mode first): 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                   # bare -d auto-detects one device
hsflash.exe write -c bs21 -d 3361:3322 -S ABC123 -f C:\fw\fw.fwpkg  # pick by serial number
hsflash.exe write -d -f C:\fw\app.bin                           # no -c: generic dfu chip
hsflash.exe read  -c hi3322 -d -z 0x10000 -f dump.bin           # read back over DFU

------- Linux -------
# serial: burn a firmware package
./hsflash write -c ws63 -p /dev/ttyUSB0 -b 115200 -f ~/fw/ws63-liteos-app_all.fwpkg
# serial: burn-and-reset / only-burn / erase / read back
./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
# list available serial ports / HID devices
./hsflash list serial
./hsflash list hid
# USB DFU (sudo or a udev rule; put the device in DFU/boot mode first)
sudo ./hsflash write -c hi3322 -d 3361:3322 -f ~/fw/3322-diting-ft.fwpkg
sudo ./hsflash write -c bs21 -d -f ~/fw/fw.fwpkg                # bare -d auto-detects one device
sudo ./hsflash write -d -f ~/fw/app.bin                         # no -c: generic dfu chip
sudo ./hsflash read  -c hi3322 -d -z 0x10000 -f dump.bin        # read back over DFU

------- macOS -------
# The macOS build is a universal binary (x86_64 + arm64), native on both Intel
# and Apple Silicon. Serial ports look like /dev/cu.usbserial-0001,
# /dev/cu.SLAB_USBtoUART or /dev/cu.wchusbserial*.
# serial: burn a firmware package
./hsflash write -c ws63 -p /dev/cu.usbserial-0001 -b 115200 -f ~/fw/ws63-liteos-app_all.fwpkg
# serial: burn-and-reset / only-burn / erase / read back
./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
# list available serial ports / HID devices
./hsflash list serial
./hsflash list hid
# USB DFU (sudo; put the device in DFU/boot mode first; no driver needed on 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                # bare -d auto-detects one device
sudo ./hsflash write -d -f ~/fw/app.bin                         # no -c: generic dfu chip
sudo ./hsflash read  -c hi3322 -d -z 0x10000 -f dump.bin        # read back over DFU

When "SerialPort has been connected, Please power off, then power on the device."
is shown, manually power-cycle the device to start serial burning.

For USB the device must be in DFU/boot mode first. On Windows install the WinUSB
driver (e.g. with Zadig) if Device Manager shows a driver problem; on Linux run
with sudo or add a udev rule; on macOS no driver is needed -- just run with sudo.
Note: on Windows, USB DFU flashing must be run as Administrator -- after the
loader stage the USB port is power-cycled to force re-enumeration, which needs
admin rights; otherwise it stalls at the post-loader reconnect.

==================================================================
4. Configuration file burn.config
==================================================================
Without options, settings are read from config/burn.config (# = comment):
  chipName=ws63          Chip name
  filePath=xxx.fwpkg     Burn file / partition table
  mode=serial            Transport mode
  serialPort=COM1        Serial port
  baudRate=115200        Baud rate
  stopBit=0
  parity=0
  reboot=0               Reset or not
  openDebug=false        Debug printing
USB DFU keys (used with mode=usb, all optional):
  usbVid=0x0483          USB vendor id filter
  usbPid=0xdf11          USB product id filter
  usbSerialNumber=       USB serial-number filter
  usbTransferSize=4096   DFU chunk size
  usbTimeout=5000        DFU control-transfer timeout (ms)
Command-line options and burn.config affect the same fields; the command line
overrides the config file. (Config keys are kept unchanged; they need not match
the CLI option names.)

==================================================================
5. Known limitations
==================================================================
- export now accepts -a (address) / -z (size), but the output file is shared
  with -f; a dedicated output path is recommended later.
- -e/--erase-size is not wired into the burning flow yet (no effect).
