nearlink-vipdocs: slim README to user-facing; split out CONTRIBUTING; drop unready docs

fbb — HiSpark fbb framework CLI

Language: English | 简体中文

fbb is the single command-line tool for developing on any SDK in the HiSpark fbb framework family — fbb_ws63, fbb_bs2x, and other fbb-framework SDKs. Install once, then build / flash / monitor them all with the same fbb.

Quick start
Command reference
JSON output & exit codes
For AI agents & skills
SDK auto-detection
Mirror configuration
What gets installed
Activating manually
Troubleshooting
Reinstalling and cleanup
Further reading
License

Quick start

0. One-shot bootstrap (recommended)

A single self-hosted command sets up the whole dev environment — it pulls uv from the mirror (dl.hispark.hisilicon.com), installs fbb, then runs fbb setup.

# Linux / macOS
curl -fsSL https://dl.hispark.hisilicon.com/bootstrap.sh | sh
# Windows (PowerShell)
irm https://dl.hispark.hisilicon.com/bootstrap.ps1 | iex

Then skip to step 3. To configure manually instead, follow the steps below.

1. Install `uv`

# Linux / macOS
curl -fsSL https://dl.hispark.hisilicon.com/fbb-tools/uv/uv-0.11.17-linux-x86_64.tar.gz | tar -xz -C ~/.local/bin --strip-components=1
# (or, upstream) curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

uv installs to ~/.local/bin/. Open a new terminal afterwards.

2. Install `fbb` + provision the build environment

uv tool install git+https://gitcode.com/HiSpark/hs-fbb-cli.git
fbb setup

fbb setup provisions the manager + Python 3.12.10 build venv plus chip-agnostic tools (ccache, Git). The chip-specific toolchain is downloaded on demand from the mirror, per the SDK's requirements, when you run fbb sdk install <chip> (recommended), fbb setup --targets <chip>, or fbb setup --sdk-dir <sdk>. It installs locally to ~/.hs-fbb/tools/<name>/<version>/.

3. Install an SDK, then build → flash → monitor

fbb sdk install ws63@master              # install latest master branch
cd ~/hispark/fbb_ws63/src
fbb build   ws63-liteos-app
fbb flash   ws63-liteos-app --port COM3
fbb monitor --port COM3 --reset --until "device_module_init:: succ!" --timeout 30

fbb flash ... --then-monitor chains flash directly into a monitor session on the same port.

Command reference

fbb <verb> [args]. Verbs fall into three groups.

Group A — environment

`fbb setup`

Provision the build environment.

Flag	Effect
`--force`	Wipe `~/.hs-fbb/` and re-provision everything
`--dry-run`	Print the install plan without touching the filesystem
`--skip-tools`	Provision the Python venv only; skip toolchain + Git
`--skip-python`	Provision toolchain + Git only; skip the venv
`--no-uv`	Skip uv; use embedded Python + bootstrap pip (slower fallback)
`--targets ws63[,bs2x]`	Provision only these chips' toolchains (default: all in the manifest)
`--sdk-dir PATH`	Install the matching toolchain per the `requires` in the SDK's chip-JSON (default: auto-detect)

`fbb sdk install <name>[@<ref>] [flags]`

Install the SDK source for the requested version. The SDK is installed to $FBB_SDK_ROOT/<repo> (FBB_SDK_ROOT defaults to ~/hispark).

Name → repo resolution (think in repos (recommended) or chips):

an explicit repo (hs-fbb, fbb_ws63, fbb_bs2x)
a bare chip/module (hiditing, ws63, bs2x)

Flag	Effect
`<name>`	repo/chip; specify a version with `@<tag\|branch\|sha>` (default: latest release tag)
`--dir PATH`	Install into this exact dir instead of `$FBB_SDK_ROOT/<repo>`
`--no-provision`	Install only; skip toolchain provisioning
`--force`	Overwrite an existing non-empty destination
`--json-summary`	Emit a one-line JSON summary

fbb sdk install ws63                 # legacy repo -> ~/hispark/fbb_ws63
fbb sdk install ws63@1.10.103        # specify a tag
fbb sdk install hs-fbb               # the unified trunk (many chips)
fbb sdk install hiditing             # chip in the trunk -> ~/hispark/hs-fbb

Source: ${FBB_SDK_GIT_BASE:-https://gitcode.com/HiSpark}/<repo>.git.

`fbb sdk versions <chip> [--all] [--json]`

List the versions available on the remote — release tags (newest first, latest marked) and branches (master / release/*). Discover before you install; no need to browse the repo. --all also shows pre-release / non-semver tags.

fbb sdk versions ws63                # see releases + branches
fbb sdk install ws63@1.10.103        # install a fixed release
fbb sdk install ws63@master          # install the dev trunk

`fbb sdk list [--json]`

List SDKs installed under $FBB_SDK_ROOT (chip, git ref, path).

`fbb sdk uninstall <chip> [--dry-run] [--no-gc] [--json-summary]`

Remove an SDK, then clean up unused toolchains — versions no longer used by any remaining SDK (the manifest recommended / default versions are always kept). --dry-run previews; --no-gc skips reclamation.

`fbb doctor`

Diagnose the build environment — checks venv, toolchain, key Python modules; prints the exact fix command for any failure. No flags.

`fbb describe [--json] [--sdk-dir PATH]`

One-pass snapshot of env + toolchain + detected SDK. --json emits the machine-readable form (see JSON output).

`fbb env [--print {sh|bash|ps1|bat|cmd|json}]`

Print an env-activation snippet for eval / IDE integration. No side effects. --json is shorthand for --print json.

`fbb run -- <cmd> [args...]`

Run an arbitrary command inside the activated build env (so python, ninja, cmake, etc. resolve). Example: fbb run -- python --version.

`fbb shell`

Spawn an interactive subshell with the env activated. exit to leave.

`fbb help`

Show usage.

Group B — build

`fbb build [<target>] [--clean] [--sdk-dir PATH] [extra...]`

Build a target. This is the only verb that forwards to the SDK (<SDK>/build.py).

Argument	Effect
`<target>`	Target name, e.g. `ws63-liteos-app`. Omit to make build.py print the valid list.
`--clean`	Clean before build (forwarded as build.py's `-c`). Slower.
`--sdk-dir PATH`	Override SDK auto-detection.
`extra...`	Anything after the target is forwarded verbatim to build.py (`-j 8`, `-dump`, ...).

fbb build ws63-liteos-app                # incremental, run from SDK src
fbb build --clean ws63-liteos-app        # clean rebuild
fbb build                                # no target -> build.py lists valid ones

Put fbb's own flags (--clean, --sdk-dir) before the target.

Two modes — picked automatically

fbb build walks up from the cwd looking for an fbb-project.toml. If found, it enters out-of-tree mode; otherwise in-tree mode.

Mode	Trigger	What `fbb` does	Target source
In-tree	cwd is the SDK src (no `fbb-project.toml` in cwd or any parent)	Forwards verbatim to `<SDK>/build.py <target>`. Backward-compatible.	CLI arg
Out-of-tree	An `fbb-project.toml` exists in cwd / a parent dir	Reads `chip` / `target` from the manifest, exports `FBB_PROJECT_DIR` + `FBB_PROJECT_TARGET` + `FBB_SDK_DIR`, then forwards to `<SDK>/build.py`. The SDK's cmake source dir flips to the user's project.	Manifest (or CLI arg if given)

# Out-of-tree usage
cd my_app/                     # has fbb-project.toml with chip + target
fbb build                      # no target needed — read from manifest
fbb build --clean              # clean rebuild

The SDK side must support this.

`fbb menuconfig [<target>] [--mode ...] [--sdk-dir PATH]`

Open the SDK's interactive Kconfig menu for a target (a curses TUI), editing that target's .config. Options shipped by out-of-tree components (fbb add / fbb create-component) show up automatically. --mode selects a non-interactive batch action instead of the menu: defconfig (reset to defaults), allyesconfig, allnoconfig.

fbb menuconfig ws63-liteos-app           # interactive menu (for humans, in a real terminal)
fbb menuconfig ws63-liteos-app --mode defconfig   # reset to defaults, no UI

The interactive menu needs a real terminal (and windows-curses in the build venv on Windows). Scripts / CI / AI agents must not use it — use fbb config below.

`fbb config <get|set|unset> <OPTION> [--target T] [--sdk-dir PATH]`

Read or change a single Kconfig option without any menu — scriptable and choice-safe. set/unset drive the SDK's non-interactive setconfig (kconfiglib set_value), so enabling one member of a choice block automatically de-selects its siblings — no manual "=y + unset every sibling".

fbb config get   CONFIG_SAMPLE_ENABLE
fbb config set   CONFIG_SAMPLE_SUPPORT_SLE_SAMPLE=y   # choice siblings auto-unset
fbb config unset CONFIG_FOO                           # = disable (n)

For automation / AI agents: to change config, always use fbb config set/get/unset. Do not hand-edit *.config and do not manually add # CONFIG_..._<sibling> is not set lines — fbb config set handles the choice mutex for you. fbb menuconfig is interactive-only and cannot be driven programmatically.

Group C — chip verbs (native; read `<chip>.json`)

Every verb below is implemented by fbb itself and reads chip data from <SDK>/build/config/target_config/<chip>/<chip>.json. All accept --sdk-dir PATH (override auto-detection) and --json-summary (emit a one-line JSON as the final stdout line).

`fbb flash [<target|path>] [flags]`

Burn a built target's firmware onto a board. The flasher is provisioned by fbb setup (currently BurnToolCmd); the user-facing flags below are tool-agnostic and stay the same as the backend evolves.

Flag	Effect
`<target>`	Target name (e.g. `ws63-liteos-app`) — locates the fwpkg under the SDK. May instead be a path to a `.fwpkg`.
`--port COMx`	Serial port. Auto-detected if omitted and exactly one port exists.
`--baud N`	Transfer baud (default: `<chip>.json` `flash.signalbaud`, else 921600).
`-c, --chip NAME`	Chip name (default: inferred from the target / fwpkg name).
`-f, --file PATH`	Flash this exact `.fwpkg` — out-of-tree / standalone; no SDK needed (with `--chip`).
`--manual-reset`	Don't auto-reset; press the physical RESET button once when prompted (board with no auto-reset).
`--load-only`	Burn `_load_only.fwpkg` (app only) instead of `_all.fwpkg`.
`--then-monitor [monitor args...]`	After a successful flash, chain into `monitor`; the port is propagated automatically.
`--json-summary`	Emit the flash JSON summary.

fbb flash ws63-liteos-app --port COM6 --json-summary
fbb flash ws63-liteos-app --port COM6 --then-monitor --reset --until "device_module_init:: succ!" --timeout 30
fbb flash -f ./build/ws63-liteos-app_all.fwpkg --chip ws63 --port COM6   # standalone, no SDK
fbb flash ws63-liteos-app --port COM6 --manual-reset                      # board with no auto-reset circuit

Default mode auto-resets the board into download mode (no manual RESET needed). On DEVICE_NOT_RESPONDING (a board with no auto-reset circuit, or a crashed board), retry with --manual-reset and press RESET once when prompted, or power-cycle the board first.

`fbb monitor [flags]`

Open a serial console; HIL-friendly with --until / --timeout.

Flag	Effect
`--port COMx`	Serial port (auto-detect if omitted).
`--baud N`	Baud (default: `<chip>.json` `monitor.default_baud`, typ. 115200).
`--chip NAME`	Chip name (single-chip SDK auto-picks).
`--until REGEX`	Exit 0 on first match; exit 4 on timeout with no match.
`--timeout SECONDS`	Wall-clock limit. Required with `--until` for scripted use.
`--reset`	Send the reset command from `<chip>.json` before reading.
`--log FILE`	Tee captured bytes to FILE as well as stdout.
`--json-summary`	Emit the monitor JSON summary.

# scripted boot check
fbb monitor --port COM3 --reset --until "device_module_init:: succ!" --timeout 30 --json-summary
# interactive console (Ctrl+C to exit)
fbb monitor --port COM3

`fbb create-project <name> [flags]`

Scaffold a new project from <SDK>/tools/templates/sample_project/.

Flag	Effect
`-p, --path DIR`	Parent directory (default: current dir).
`--template NAME`	Use a different template / example as the source.
`--json-summary`	Emit the create JSON summary.

`fbb create-component <name> [-p DIR] [--json-summary]`

Scaffold a new component from <SDK>/tools/templates/sample_component/.

`fbb create-project-from-example <example> [flags]`

Clone an example declared in a chip's examples.roots (in <chip>.json).

Flag	Effect
`--name NAME`	Project directory name (default: same as the example).
`-p, --path DIR`	Parent directory (default: current dir).
`--json-summary`	Emit the create JSON summary.

fbb create-project        myapp
fbb create-component      mywidget
fbb create-project-from-example helloworld --name my_hello

`fbb set-target <target> [--json-summary]`

Save a default target into <project>/.fbb-target (a per-project state file; the project root is FBB_BUILD_ROOT_PATH or the current dir). The target is validated against the SDK's buildable target list.

`fbb get-target [--json-summary]`

Print the target saved by set-target. Exit 3 if no state file exists.

`fbb list-targets [--json] [--json-summary]`

Enumerate buildable targets, grouped by chip. --json emits the full structured form.

`fbb list-examples [--json] [--json-summary]`

Enumerate clonable examples from each chip's examples.roots (in <chip>.json).

JSON output & exit codes

This is the stable interface for scripts and skills. Code against it, not against human-readable text.

Exit codes

Code	Meaning
`0`	success
`1`	command failed (build error, flash failed, ...)
`2`	usage error (bad arguments, unknown verb)
`3`	resource missing (no serial port, no fwpkg, no SDK, no flasher)
`4`	configuration error (chip JSON missing a section, `--until` timed out, ...)

`--json-summary` convention

Verbs in Group C accept --json-summary. When passed, the last line of stdout is a single-line JSON object. Earlier lines may carry human-readable progress — a consumer parses only the last line.

Every summary has: verb, schema_version (currently 1), success (bool), duration_seconds, and error (null, or an object).

`error` object

"error": { "code": "DEVICE_NOT_RESPONDING", "message": "...", "recoverable": true }

recoverable is present on flash errors; true means a retry (e.g. with --manual-reset) may succeed.

`error.code` enum (branch on this)

Verb	Codes
flash	`FWPKG_NOT_FOUND` · `FWPKG_OPEN_FAILED` · `PORT_NOT_FOUND` · `PORT_BUSY` · `BURNTOOL_NOT_FOUND` · `CHIP_UNKNOWN` · `CHIP_FLASH_CONFIG_MISSING` · `DEVICE_NOT_RESPONDING` (recoverable) · `FLASH_PROTOCOL_ERROR` · `PATH_HAS_SPACE` · `FLASH_FAILED`
monitor	`PORT_NOT_FOUND` · `PORT_OPEN_FAILED` · `IO_ERROR` · `INVALID_USAGE`
create-*	`INVALID_NAME` · `TEMPLATE_NOT_FOUND` · `EXAMPLE_NOT_FOUND` · `DEST_NOT_EMPTY` · `COPY_FAILED`
set-target	`TARGET_NOT_FOUND` · `STATE_WRITE_FAILED`
get-target	`STATE_NOT_FOUND`
list-targets	`ENUMERATION_FAILED`

flash summary

{
  "verb": "flash", "schema_version": 1, "success": true,
  "duration_seconds": 35.7, "target": "ws63-liteos-app", "chip": "ws63",
  "port": "COM3", "baud": 921600,
  "fwpkg": "...ws63-liteos-app_all.fwpkg", "fwpkg_size_bytes": 1458920,
  "attempt": "auto",                       // "auto" | "manual"
  "die_id": "0x18265CB5...", "burned_sections": 7,
  "burntool_exit_code": 0, "optlog_path": "...optLog_*.txt",
  "error": null
}

monitor summary

{
  "verb": "monitor", "schema_version": 1, "success": true,
  "duration_seconds": 1.0,
  "exit_reason": "matched",                // matched|timeout|user_interrupt|io_error
  "matched": true, "match_pattern": "device_module_init:: succ!",
  "match_text": "...context around the match...",
  "bytes_read": 895, "port": "COM3", "baud": 115200,
  "log_path": null, "error": null
}

create / set-target / list summaries

create-* → { verb, schema_version, success, name, path, template, files_created, error }. set-target / get-target → { verb, success, target, state_file, available_targets_count, error }. list-targets --json → { by_chip, all_targets, total_targets, ... }; list-examples --json → { by_root, all_examples, total }.

For AI agents & skills

fbb is the mechanism layer. Skills are the policy layer — they decide when to call a verb and how to react. The contract between them is everything in JSON output & exit codes.

Bootstrap (idempotent):

uv tool install git+https://gitcode.com/HiSpark/hs-fbb-cli.git && fbb setup

Every fbb call self-activates the env — agents need not share shell state across calls.

`fbb describe --json` — situational-awareness probe

One call returns everything needed to plan:

Key	Meaning
`schema_version`	Snapshot schema version.
`fbb_cli.version`	Installed `fbb` version.
`build_env.exists` / `venv_python` / `toolchain_dir`	Whether `fbb setup` has run.
`toolchain.ninja` / `riscv_gcc` / `burntool` / `git`	Resolved paths (or `null`).
`python_packages.pyserial`	Version in the venv (or `null`).
`sdk.path` / `name` / `chips`	SDK location, `fbb_<chip>` name, and the chips discovered under `target_config/`.
`sdk.build_entry`	Path to `<SDK>/build.py` (where `fbb build` forwards), or `null`.
`sdk.supported_verbs`	The verbs `fbb` provides for this SDK (fixed set).
`sdk.targets`	Buildable targets.
`sdk.templates` / `sdk.examples`	Scaffold templates and clonable examples.

Recommended flash flow for skills

result = fbb flash <target> --port COMx --json-summary       # parse last stdout line
  success                                  -> done
  error.code == DEVICE_NOT_RESPONDING      -> coach user to press RESET,
                                              retry once with --manual-reset
  otherwise                                -> surface error.message, do not retry

SDK auto-detection

Chip verbs and build resolve the SDK in this order:

--sdk-dir <path> flag
FBB_SDK_DIR environment variable
Walk up from the current directory for src/build.py + CMakeLists.txt

If none resolve, the verb exits 3 with a directed hint.

Mirror configuration

All defaults are self-hosted / Chinese mirrors. Set these before fbb setup:

Variable	Default	Used by
`FBB_PIP_INDEX`	`https://pypi.tuna.tsinghua.edu.cn/simple`	all installers
`FBB_PYTHON_MIRROR`	`https://mirrors.huaweicloud.com/python`	pip route (primary)
`FBB_PYTHON_MIRROR_B`	`https://mirrors.cloud.tencent.com/python`	pip route (fallback)
`UV_PYTHON_INSTALL_MIRROR`	`https://dl.hispark.hisilicon.com/fbb-tools/python`	uv route
`FBB_OBS_BASE`	`https://dl.hispark.hisilicon.com`	manifest + toolchain artifacts
`FBB_TOOLS_MANIFEST_URL`	`$FBB_OBS_BASE/tools.json`	tool availability manifest
`FBB_SDK_ROOT`	`~/hispark`	where `fbb sdk install` clones SDKs
`FBB_SDK_GIT_BASE`	`https://gitcode.com/HiSpark`	SDK repo base (`/<repo>.git`)
`FBB_SDK_TRUNK`	`hs-fbb`	unified-SDK repo a bare chip falls to when no `fbb_<chip>` repo exists
`FBB_GETPIP_URL`	`https://mirrors.aliyun.com/pypi/get-pip.py`	pip route (fallback)

export FBB_PIP_INDEX='https://mirrors.aliyun.com/pypi/simple/'   # bash
$env:FBB_PIP_INDEX = 'https://mirrors.aliyun.com/pypi/simple/'   # PowerShell
fbb setup --force

What gets installed

~/.local/bin/fbb            the CLI (managed by `uv tool install`)
~/.hs-fbb/                  the managed build env (provisioned by `fbb setup`)
├── venv/                   Python 3.12.10 + numpy + kconfiglib + cmake 3.20.5 + ...
├── tools/                  manifest-provisioned, version-keyed:
│   ├── hcc/7.3.0-20240618/     RISC-V cross-compiler
│   ├── ccache/4.13.6/          compiler cache
│   └── <name>/<version>/       ... (shared across SDKs that pin the same version)
├── Git/                    portable Git on Windows when no system git is found
└── .install-state.json     resume marker

~/hispark/                  SDK source checkouts (FBB_SDK_ROOT; visible, yours)
└── fbb_ws63/               cloned by `fbb sdk install ws63`

~/.hs-fbb/ bakes in absolute paths and is machine-specific — each developer regenerates it with fbb setup; it is not redistributable. SDK checkouts under ~/hispark/ are normal git trees you edit and build in.

Activating manually

Not needed when using fbb. For power users / CI wanting a long-lived activated shell:

eval "$(fbb env --print sh)"                                   # bash / zsh
fbb env --print ps1 | Out-String | Invoke-Expression           # PowerShell

Troubleshooting

Always start with fbb doctor — it diagnoses each component and prints the fix.

Symptom	Fix
`fbb: command not found`	`~/.local/bin` not on PATH. `uv tool update-shell` or open a new terminal.
`[fbb] build environment not provisioned`	Run `fbb setup`.
`because running scripts is disabled on this system`	PowerShell policy. `Set-ExecutionPolicy -Scope Process Bypass`.
`CMake was unable to find ... "Ninja"`	Toolchain not on PATH. `fbb doctor`, then `fbb setup --force` if missing.
`gcc: error: CreateProcess: No such file or directory`	Windows 32K command-line limit. Clone the SDK to a shorter path.
`import numpy ... ModuleNotFoundError`	Bare `python` used outside the env. Use `fbb run -- python ...` or `fbb shell`.
Build breaks after `fbb setup` upgraded cmake to 3.31.x	`requirements.txt` pins `cmake==3.20.5`. Force-reinstall, cache bypassed: `uv tool install --force --reinstall --no-cache git+https://gitcode.com/HiSpark/hs-fbb-cli.git`, then `fbb setup --force`.
`fbb flash` → `DEVICE_NOT_RESPONDING`	Board did not auto-reset. Retry with `--manual-reset` and press the board's RESET button.
`fbb flash` → `PORT_BUSY` (exit 17)	A serial monitor / stale flasher holds the port. Close it and retry.
`fbb <verb>` → `cannot run '<verb>': no SDK in scope`	`cd` into an `fbb_*` checkout, pass `--sdk-dir <path>`, or set `FBB_SDK_DIR`.
Behind a corporate proxy	Set `HTTPS_PROXY` / `HTTP_PROXY` before `fbb setup`.

Reinstalling and cleanup

fbb setup --force            # wipe + re-provision the build env
rm -rf ~/.hs-fbb && fbb setup # nuke everything and start over
uv tool uninstall hs-fbb-cli # remove the CLI itself

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE. Artifacts downloaded at provision time retain their own upstream licenses; this repository does not redistribute them.

fbb — HiSpark fbb framework CLI

Contents

Quick start

0. One-shot bootstrap (recommended)

1. Install uv

2. Install fbb + provision the build environment

3. Install an SDK, then build → flash → monitor

Command reference

Group A — environment

fbb setup

fbb sdk install <name>[@<ref>] [flags]

fbb sdk versions <chip> [--all] [--json]

fbb sdk list [--json]

fbb sdk uninstall <chip> [--dry-run] [--no-gc] [--json-summary]

fbb doctor

fbb describe [--json] [--sdk-dir PATH]

fbb env [--print {sh|bash|ps1|bat|cmd|json}]

fbb run -- <cmd> [args...]

fbb shell

fbb help