HiDiTingV100 一站式CLI开发环境使用指南
一站式CLI开发环境通过统一的命令行工具 fbb 封装了工程配置、编译、烧写、监视等完整工作流。开发者无需下载 CMake/Ninja 等环境，也无需操作这些底层命令，只需使用 fbb 系列子命令即可完成全部操作。
主要特性：
- 支持 SDK 源码树外执行工程构建
- 支持一键快速创建空工程
- 通过图形化功能裁剪与配置
- 内置烧写与串口监视器
- 跨平台：Windows、Linux
环境准备
📌 前置依赖：Git
安装命令通过 Git 协议拉取源码，需确保系统已安装 Git。
- Windows 推荐通过 winget 安装：
- Linux：
sudo apt install git（Debian/Ubuntu）或sudo dnf install git（Fedora）安装后重新打开终端，执行
git --version确认安装成功。
环境安装
一行命令完成 uv 安装、fbb-cli 安装和 fbb setup：
Windows（以管理员身份启动 PowerShell）：
提示（仅在报错时处理）
若安装时提示 PowerShell requires an execution policy in [Unrestricted, RemoteSigned, Bypass]，在当前窗口执行：
该设置仅对当前 PowerShell 进程生效，关闭窗口后自动失效。
若提示「此应用已被你的组织的应用程序控制策略阻止」，请确认下载地址和文件来源正确，并联系 IT 按企业流程审核、放行 CLI 下载的工具。
Linux：
完成后执行 fbb doctor 验证环境是否就绪。若输出正常，则继续进行代码下载与编译。
代码下载与编译
执行以下命令下载 SDK，可通过 --dir <sdk_dir> 参数指定安装路径；当前默认安装到用户目录的 hispark 子目录。
下载完成后，按终端 Done. Next: 提示进入 SDK 的 src 目录：
仅在提示需要准备构建环境时执行：
编译固件：
编译成功后，固件包位于 output\3322\fwpkg\diting-community.fwpkg。
⚠️ 路径要求：SDK 路径不能包含空格或中文。
⚠️ 编译失败提示：若编译日志中出现
access denied，可能是杀毒软件拦截了工具链进程。请确认工具来源可信，并将工具链相关可执行程序（含ccache）加入杀毒软件信任白名单；企业环境请联系 IT 管理员处理。
烧写与调试
Windows
USB 烧写（推荐）
在管理员 PowerShell 中执行：
烧写成功后监视启动日志：
串口烧写
显示烧写等待后，给 Hi3322 断电并重新上电：
fbb flash -f "output\3322\fwpkg\diting-community.fwpkg" -p COM3 --chip 3322 --manual-reset --timeout 600
烧写成功后，使用上面的 monitor 命令查看启动日志。
Linux
Linux 当前使用串口烧写。普通用户首次使用前需加入 dialout 组：
首次配置权限：执行
sudo usermod -aG dialout "$USER"，然后注销并重新登录；重新打开终端后执行id -nG，确认输出包含dialout。
显示烧写等待后，给 Hi3322 断电并重新上电：
fbb flash -f "output/3322/fwpkg/diting-community.fwpkg" -p /dev/ttyUSB0 --chip 3322 --manual-reset --timeout 600
烧写成功后监视启动日志：
FLASH_RC=0 表示烧写成功；monitor 输出包含 APP|run: 表示新固件已启动。若实际日志波特率为 115200，请将 --baud 改为 115200。
低功耗设备：USB 烧写提示
specify --trigger-port; AT probe saw none时，先通过 AT 串口执行AT+PM=0关闭低功耗，再重新烧写。
其他
创建并编译树外工程
树外工程是位于 SDK src 目录之外的独立工程，通过 CLI 引用 SDK 进行编译。
📌 路径建议：树外编译可能因为路径过长导致 Ninja 创建
.rsp文件失败；为避免该问题，建议使用较短的树外工程路径（如D:\fbb\myapp）。
编译时工具链会将应用代码与所依赖的 SDK 组件一并编译，并生成固件镜像（.fwpkg）。
📌 树外编译预先配置 SDK 路径（执行命令时
--sdk-dir也可以指定）：Windows（PowerShell）：
如需永久生效，将上述命令添加到 PowerShell Profile（
$PROFILE）中，重新打开终端后即可生效。Linux：
如需永久生效，将上述命令添加到
~/.bashrc或~/.zshrc中，然后执行以下命令使其立即生效：
-
创建工程：
-
进入工程目录：
-
查看可用目标：
-
设置编译目标：
-
编译：
工程目录结构
fbb create-project myapp 生成的标准工程结构如下：
myapp/
├── fbb-project.toml # 工程描述文件（工程名、chip，以及可选的 SDK 版本等）
├── CMakeLists.txt # 顶层工程文件
├── README.md
└── main/
├── CMakeLists.txt # 主组件构建文件
├── include/
│ └── samplepage/
│ ├── SamplePage.h
│ ├── SamplePresenter.h
│ └── SampleView.h
└── src/
├── SamplePage.cpp
└── SamplePresenter.cpp
执行 fbb set-target 后，CLI 会在工程根目录另行创建 .fbb-target，用于保存默认编译目标。
📌 说明：模板固定使用
samplepage作为组件名，生成的源文件以Sample前缀命名。开发者可直接在此基础上修改，或重命名为自己的组件名。
顶层 CMakeLists.txt 示例：
cmake_minimum_required(VERSION 3.14.1)
set(FBB_PROJECT_COMPONENT_NAME "samplepage")
find_package(fbb REQUIRED HINTS
"$ENV{FBB_SDK_DIR}/build/cmake"
"$ENV{FBB_SDK_ROOT_DIR}/build/cmake")
project(myapp)
main/CMakeLists.txt 示例：
set(COMPONENT_NAME "samplepage")
set(SOURCES
${CMAKE_CURRENT_SOURCE_DIR}/src/SamplePage.cpp
${CMAKE_CURRENT_SOURCE_DIR}/src/SamplePresenter.cpp
)
set(PUBLIC_HEADER
${CMAKE_CURRENT_SOURCE_DIR}/include
)
set(WHOLE_LINK true)
set(MAIN_COMPONENT true)
set(APP_TARGETS "diting-community")
build_component()
命令参考
fbb list-targets
列出 SDK 中所有可用的编译目标（Individual Target）和目标组（Target Group）。
输出示例：
可用目标:
==================================================
[3322] 单目标:
3322-loaderboot
3322-recovery
3322-seliteos-release
3322-ssb
diting-community
diting-community-bike
diting-community-native-js
diting-community-xts
[3322] 目标组:
pack_diting_community
pack_diting_community_bike
pack_diting_community_native_js
pack_diting_community_xts
共 8 个目标、4 个目标组,跨 1 个芯片
fbb set-target
设置当前工程的默认编译目标，目标名保存在工程目录下的 .fbb-target 文件中，后续 fbb build 在未指定目标时会读取此值。
命令格式：fbb set-target <目标名>。
示例：
fbb get-target
查看当前工程已保存的默认目标。
fbb create-project
在指定路径使用内置空白模板创建新工程。基于 SDK 示例创建工程请使用 fbb create-project-from-example。
命令格式：fbb create-project <工程名> [--path <目录>]。
| 参数 | 说明 |
|---|---|
<工程名> |
必填。新工程的名称 |
--path <目录> |
工程创建的父目录，默认为当前目录 |
示例：
使用空白模板在当前目录创建：
在指定目录创建：
fbb create-component
命令格式：fbb create-component <组件名> [--path <父目录>]。
📌 推荐用法：在工程内任意目录执行命令且不指定
--path，CLI 会自动定位工程根目录并创建components/<组件名>。如需指定路径并让构建系统自动发现组件，请将--path设置为工程的components目录。
示例：
进入工程目录：
创建组件：
执行后生成：
myapp/
├── components/
│ └── my_sensor/
│ ├── CMakeLists.txt
│ ├── Kconfig
│ ├── component.c
│ └── include/
│ └── component.h
└── ...
📌 空组件说明：新建组件的
component.c仅包含空函数占位实现，component.h包含对应声明，开发者可在此基础上添加扩展功能逻辑。
fbb config get / set / unset
不打开图形界面，直接读取或修改目标的 Kconfig 选项（适合脚本/CI 场景）。
命令格式：
fbb config --target <Individual Target> get <CONFIG_NAME>fbb config --target <Individual Target> set <CONFIG_NAME>=<值>fbb config --target <Individual Target> unset <CONFIG_NAME>
示例：
📌 前提：指定的 Individual Target 必须已有
.config文件；目标组（如pack_diting_community）没有独立的.config，不能用于fbb config。⚠️
fbb config set注意：set命令配置的CONFIG_NAME必须在当前.config中已存在（即 SDK 支持该选项）。若配置项不存在，命令会报错。可先用fbb config get <CONFIG_NAME>确认选项是否可用。⚠️ Hi3322 树外配置限制：当前版本不应在树外工程中使用
fbb menuconfig diting-community --mode defconfig初始化配置，请保留 SDK 随目标提供的 3322 配置，不要用defconfig覆盖。
fbb menuconfig
打开基于 Kconfig 的图形化配置界面，可裁剪功能模块、调整编译开关。配置结果保存至对应目标的 .config 文件。
命令格式：fbb menuconfig <目标名>。
示例：
⚠️ 仅支持 Individual Target：
menuconfig不支持 Group Target（如pack_diting_community）。必须指定组内的具体 Individual Target，例如：fbb menuconfig diting-community。📌 说明：修改配置后需重新运行
fbb build使配置生效。
fbb build
编译当前目标；--clean 先清理构建输出再全量编译。
编译已保存的默认目标：
编译指定目标：
命令格式：fbb build <目标名>。
清理后全量重新编译：
命令格式：fbb build --clean <目标名>。
💡 增量编译：
fbb build默认进行增量编译。CMake 会检测源文件变更，仅重新编译受影响的模块。⚠️ SDK 工作区状态：当前 Hi3322 构建脚本可能更新 SDK 中的预编译库、第三方生成头文件、签名文件和缓存。即使采用树外工程，SDK 源码树也不保证完全只读。建议在干净的 SDK 工作区中构建，并在构建后执行
git status --short区分源码改动与生成副作用。
| 参数 | 说明 |
|---|---|
<目标名> |
可选。未指定时使用 fbb set-target 保存的默认目标 |
--clean |
清理构建输出后全量编译 |
fbb flash
通过 hsflash 将固件包（.fwpkg）烧写到开发板，支持串口与 USB DFU 两种传输介质。
命令格式：fbb flash -f <固件路径> [选项]。
| 选项 | 说明 | 默认值 |
|---|---|---|
-f/--file <路径> |
指定 .fwpkg 固件包路径；当前 Hi3322 平铺包需要显式指定 |
无 |
-p/--port <COMx> |
选择串口烧写并指定端口（如 COM3、/dev/ttyUSB0） | 串口芯片可自动检测 |
-d/--device [VID:PID] |
选择 USB DFU 烧写；可覆盖 SDK 设备 ID | 读取 chip JSON |
--trigger-port <COMx> |
USB 模式的 AT 控制串口 | 自动探测 AT 应答 |
--baud <N> |
烧写波特率 | 读取 chip JSON |
--chip <名称> |
手动指定芯片配置键（Hi3322 使用 3322） |
从路径/目标名自动推断 |
--manual-reset |
手动进入下载模式；Hi3322 实测需在显示烧写等待后断电重上电 | 否 |
--load-only |
选择 *_load_only.fwpkg；当前 Hi3322 不提供该包，请勿使用 |
否 |
--no-elevate |
Windows 下禁用自动 UAC；需要管理员权限时直接失败 | 否 |
--timeout <秒> |
可选的整体烧写超时时间 | 不设置，由 hsflash 使用各阶段超时 |
--json-summary |
在 stdout 末尾输出一行 JSON 摘要（适合脚本解析） | 否 |
具体烧写与 monitor 命令见上文烧写与调试。
fbb monitor
打开串口监视器，实时查看开发板输出日志，支持超时退出与日志保存。
命令格式：fbb monitor [选项]。
| 选项 | 说明 |
|---|---|
--port <COMx> |
串口名（自动检测时可省略） |
--baud <N> |
波特率，默认 115200 |
--chip <名称> |
芯片型号（单芯片 SDK 自动选择） |
--until <正则> |
匹配到正则表达式时自动退出（exit 0） |
--timeout <秒> |
超时秒数，超时未匹配 --until 则退出（exit 4） |
--reset |
打开串口后发送复位命令 |
--log <文件> |
同时将输出写入日志文件（如 fbb-monitor.log）；不指定则不记录 |
快速监视命令见上文烧写与调试。CI/CD 可在该命令后增加 --until <正则>、--timeout <秒> 和 --log <文件>。
fbb list-examples
列出 SDK 内所有可用的示例工程。
fbb create-project-from-example
基于 SDK 内置示例工程创建新工程，适合快速开发特定功能。
命令格式：fbb create-project-from-example <示例名> [--name <工程名>] [--path <目录>]。
| 参数 | 说明 |
|---|---|
<示例名> |
必填。示例名见 fbb list-examples |
--name <工程名> |
可选。新工程目录名，默认与示例名相同 |
--path <目录> |
工程创建的父目录，默认为当前目录 |
示例：
查看所有可用示例：
基于已列出的示例创建（工程名与示例名相同）：
命令格式：fbb create-project-from-example <示例名> --path ~/projects。
指定工程名：
命令格式：fbb create-project-from-example <示例名> --name myapp --path ~/projects。
命令速查表
| 命令 | 功能 |
|---|---|
fbb setup |
初始化构建环境（工具链、venv） |
fbb list-targets |
列出所有可用目标和目标组 |
fbb set-target <目标> |
设置默认编译目标（保存到工程 .fbb-target） |
fbb get-target |
查看已保存的默认目标 |
fbb create-project <名称> |
创建新工程 |
fbb create-component <名称> |
创建新组件 |
fbb config --target <目标> get/set/unset |
非交互式读写 Individual Target 的 Kconfig 选项 |
fbb menuconfig <目标> |
图形化功能配置（仅 Individual Target） |
fbb build [目标] |
增量编译 |
fbb flash -f <固件> -p <串口> |
使用原串口方式烧写固件 |
fbb flash -f <固件> -d |
在管理员 PowerShell 中执行 USB 烧写并自动复位 |
fbb monitor --port <串口> --baud <波特率> |
串口监视器 |
fbb list-examples |
列出可用示例 |
fbb create-project-from-example <示例> |
基于示例创建工程 |
fbb describe |
打印环境、SDK、工具链状态（诊断用） |
fbb doctor |
诊断构建环境 |