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/Hi3372, Brandy, the bs family
(bs20/bs20c/bs20h/bs21/bs21a/bs21e/bs22/bs25/bs26/bs27a ...), and dfu
(generic DFU device). USB support is configured per chip in ChipProperties;
not every protocol-family member has USB enabled.

==================================================================
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 SE-boot-capable chips)
  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)
      --reset-at-port <port>   Auxiliary AT port used before USB burning (autodfu only)
  -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)
      --usb-dfu-mode <mode>    USB mode: dfu / autodfu (default) / hiddfu;
                               aliases: --dfu, --autodfu, --hiddfu
  -S, --serial-number <sn>     Pick one of several identical USB devices
      --usage <hex>            Filter dfu / hiddfu by top-level HID Usage
      --usage-page <hex>       Filter by top-level HID UsagePage (--usagepage alias)
  -f, --file <path>            Burn file / partition table (.fwpkg / .bin / .xml)
  -o, --output <path>          Read output file (required by read)
      --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 (enabled by default; =0 disables, legacy forms remain compatible)
      --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 supported serial chips and SE-boot USB
      --burn-interval <ms>     Inter-frame interval, 1-30 ms (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
# 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
# Brandy: extract/download the SSB from fwpkg, then erase the whole chip
# (-e/--erase-size does not apply)
hsflash.exe erase -c Brandy -p COM10 -f C:\fw\brandy.fwpkg
# serial: read back a Flash range to a file
hsflash.exe read  -c ws63 -p COM10 -a 0x0 -z 0x200000 -f ws63-liteos-app_all.fwpkg -o 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 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                   # 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 hi3322.fwpkg -o 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
./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
# 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 hi3322 -d 3361:3322 --hiddfu -f ~/fw/3322-diting-ft.fwpkg  # HID DFU
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 hi3322.fwpkg -o 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
./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
# 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 hi3322 -d 3361:3322 --hiddfu -f ~/fw/3322-diting-ft.fwpkg  # HID DFU
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 hi3322.fwpkg -o 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
  reset=1                Reset by default; use --after-reset=0 to disable
  openDebug=false        Unified diagnostic log switch (off by default)
  debugLogPath=          Optional log path; defaults to hsflash-debug.log in the cwd
With openDebug=true, hsflash appends timestamped/thread-tagged diagnostics covering
serial open/configuration, raw SERIAL_TX/RX hex data (up to 256 bytes per event),
protocol frames, Brandy handshake/SSB erase, DFU state, USB control transfers and
errors. Existing console debug output is enabled by the same switch. The former
HSFLASH_SERIAL_TRACE environment variable has been removed and is no longer supported.
Logs may contain device output and firmware data; redact them before sharing.
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)
  usbDfuMode=autodfu     dfu / autodfu / hiddfu (default autodfu)
  usbHidUsage=0x2        Optional top-level HID Usage filter
  usbHidUsagePage=0xff00 Optional top-level HID UsagePage filter
Chip property files may also contain:
  UsbNeedsLoader=true    Download a ROM loader and wait for USB re-enumeration
                         (Hi3322/Hi3372 are enabled automatically by ChipType)
                         ResetAtPort is allowed only in autodfu; ResetAtCommand is
                         also used by serial before-reset when configured;
                         hiddfu reads an ACK after every report and validates
                         the whole-image CRC only on the final data report.
                         hiddfu requires a concrete SE-boot chip; generic -c dfu
                         is rejected because it has no image-command context.
  --transfer-size/--timeout affect standard libusb DFU; hiddfu uses fixed
                         HID report sizes and HID timeout handling.
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
==================================================================
- read uses -f for the loader firmware package and -o for the output file.
- -e/--erase-size is not wired into the burning flow yet (no effect).
