nearlink-vipfbb — HiSpark fbb framework CLI

fbb across platforms — Windows / WSL / Linux / macOS

Guiding principle: build where the filesystem is fast; do hardware I/O (flash / monitor / debug) wherever the serial device is reachable — natively, or bridged into WSL with usbipd.

At a glance

Step	Windows	Linux / macOS (native)	WSL (on Windows)
`fbb setup`	Windows	native	WSL
`fbb build`	Windows	native	WSL (fast ext4)
`fbb flash`	Windows	native	WSL (usbipd) or Windows
`fbb monitor`	Windows	native	WSL (usbipd) or Windows

Serial ownership is exclusive. A USB‑serial adapter belongs to exactly one OS at a time. usbipd attach --wsl hands the board to WSL (the Windows COMx disappears) until you usbipd detach. Both WSL‑native and Windows‑side flashing are supported — pick one per session.

Windows (native — full flow)

Everything runs natively; the flasher (BurnToolCmd) + COM ports are owned by Windows.

irm https://dl.hispark.hisilicon.com/bootstrap.ps1 | iex    # uv + fbb + build env
fbb sdk install ws63                                         # clone SDK + provision toolchain
cd %USERPROFILE%\hispark\fbb_ws63\src
fbb build   ws63-liteos-app
fbb flash   ws63-liteos-app --port COM6 --then-monitor --reset --until "device_module_init:: succ!"

fbb flash ... --then-monitor chains flash straight into a monitor session.

Linux / macOS (native — full flow)

Same commands; the serial port is native (/dev/ttyUSB0 on Linux, /dev/tty.usbserial-* on macOS) — no usbip needed, the board is plugged into the Linux/macOS machine directly.

curl -fsSL https://dl.hispark.hisilicon.com/bootstrap.sh | sh
fbb sdk install ws63
cd ~/hispark/fbb_ws63/src
fbb build   ws63-liteos-app
fbb flash   ws63-liteos-app --port /dev/ttyUSB0 --then-monitor --reset --until "device_module_init:: succ!"

Notes:

Build on a native filesystem (~/...), not a slow network mount.
Linux flashing uses the Linux BurnToolCmd (provisioned by fbb setup). macOS flashing needs a macOS build of the flasher (pending).

WSL — two supported paths

WSL's main win is fast builds (ext4). For flash/monitor you can either keep the board in WSL (bridge it with usbipd) or hand it back to Windows — both work.

One‑time (in WSL)

# SDK on the ext4 filesystem (NOT under /mnt/, which is slow + drops exec bits).
curl -fsSL https://dl.hispark.hisilicon.com/bootstrap.sh | sh
fbb sdk install ws63               # -> ~/hispark/fbb_ws63

Path A — full loop in WSL, via `usbipd` ✅ (validated on real hardware)

Bridge the board into WSL once per session, then everything runs in one shell:

# Windows, admin PowerShell — install once, attach each session:
winget install dorssel.usbipd-win
usbipd list                                   # find the CH340 BUSID (e.g. 4-1)
usbipd bind   --busid <BUSID>                 # one-time
usbipd attach --wsl --busid <BUSID>           # board -> /dev/ttyUSB0 in WSL

# WSL — board is now /dev/ttyUSB0 (one-time: sudo chmod 666 /dev/ttyUSB0, or join the dialout group)
cd ~/hispark/fbb_ws63/src
fbb build   ws63-liteos-app
fbb flash   ws63-liteos-app --port /dev/ttyUSB0 --then-monitor --reset --until "device_module_init:: succ!"

usbipd attach --wsl needs a running WSL2 distro (keep a WSL shell open). Detaching (usbipd detach --busid <BUSID>) returns the COMx to Windows.

Path B — build in WSL, flash on Windows (no usbip)

If you'd rather not bridge the serial, build in WSL and flash from Windows pointing at the WSL artifact:

wsl$  cd ~/hispark/fbb_ws63/src && fbb build ws63-liteos-app

PS>  fbb flash ws63-liteos-app --port COM6 \
        --sdk-dir \\wsl.localhost\<distro>\home\<user>\hispark\fbb_ws63\src

The *_all.fwpkg is only ~1.4 MB; reading it once over \\wsl.localhost is fine. If you prefer, copy it out instead of using the UNC path.

Why this split (rationale)

Build → WSL/ext4: clean first build ≈ 1.8× faster than Windows NTFS (~73 s vs ~132 s on the same 8‑core box); /mnt/* (9p/DrvFs) is slow and strips exec bits — always build on ext4.
Flash/monitor → WSL (usbipd) or Windows: both validated. usbipd keeps the whole loop in a single WSL shell; the Windows split skips the bind/attach step and keeps the COMx on Windows. Pick per preference.

Implementation status (2026‑06‑09, real ws63 board)

Platform	build	flash / monitor
Windows	✅	✅ `fbb flash --then-monitor` full auto
WSL	✅	✅ via `usbipd` (Linux `BurnToolCmd`) — full loop validated
Linux (native)	✅ (+ auto ccache)	✅ same Linux `BurnToolCmd` path (validated via WSL/usbipd); native‑board run not separately tested
macOS (native)	✅ (via uv)	depends on a macOS `BurnToolCmd` (pending)

The full developer loop (env → fbb sdk install → fbb build → fbb flash → fbb monitor) was validated end‑to‑end on both Windows and WSL with a real ws63 board: fbb flash … --then-monitor auto‑resets, burns all 7 partitions, and the app boots to device_module_init:: succ!.