Solution目录结构¶

本章节主要说明 Solution 代码包中各目录的职责，帮助开发者知道“代码放在哪里、每个目录大概负责什么”。如果你是第一次拿到代码，建议同时阅读快速熟悉 Solution 代码框架，先按推荐流程完成工程选择、配置确认、编译运行，再逐步深入到具体源码。

可以先按下面这张图理解本文档和代码目录的关系：

拿到 Solution 代码
  ↓
先看本章节，了解目录分工
  ↓
进入 solution/readme.md，快速定位常用入口
  ↓
选择 examples 下合适的参考工程
  ↓
阅读工程目录下的 readme.md
  ↓
参考 kconfig_readme.md 确认 menuconfig 配置

简单来说：

本章节用于说明 目录结构和目录职责；
solution/readme.md 用于在代码仓内做 快速导航；
各目录下的 readme.md 用于说明 当前目录怎么读、入口在哪里、常见修改点是什么；
solution/kconfig_readme.md 用于说明 常见配置项怎么理解、什么时候需要修改。

1. 主目录组成¶

Solution 软件的主目录核心分为 SDK 和 Solution 两个子目录，二者分工明确，共同支撑开发流程，具体说明如下：

代码包根目录
├── sdk/        # 底层 SDK，提供芯片、驱动、RTOS、中间件和第三方库等基础能力
└── solution/   # 产品方案层，包含框架、组件、示例工程、工具和配置说明

初学者可以先记住一个原则：

做产品应用开发时，通常先看 solution；只有在需要修改底层驱动、RTOS、中间件或芯片相关能力时，才需要深入 sdk。

1.1 SDK 子目录¶

基于 SDK 2.X 稳定版本构建，仅在以下必要场景随 Solution 版本同步更新，避免频繁变更影响稳定性：

漏洞修复：修复 SDK 原生存在的功能bug或兼容性问题；
功能集成：新增 Solution 框架依赖的核心功能（如特定硬件驱动、通信协议适配）；
性能优化：针对 Solution 场景做底层性能调优（如内存占用、运行效率提升）；
需求补充：若需集成未包含的功能，可向开发组提需求，或自行合入代码（需遵循 SDK 代码规范）。

1.2 Solution 子目录¶

Solution 开发的核心目录，包含从框架到工具、从组件到例程的完整开发资源，支持客户按需选用组件，快速搭建产品并推进量产。目录结构如下图所示

其中几个最常用的入口可以先这样理解：

目录或文件	初学者先理解成	常见使用场景
`framework`	Solution 的主框架	理解应用启动、页面调度、系统服务、低功耗等框架机制
`components`	可选功能组件库	打开或裁剪蓝牙、Wi-Fi、传感器、OTA、天气等产品能力
`examples`	示例工程和产品参考	选择和目标产品最接近的工程，作为开发起点
`tools`	开发和量产工具	使用 Butterfli、GUI Builder、资源工具、烧录工具等
`readme.md`	solution 目录快速导航	第一次进入代码仓时，快速知道先看哪里
`kconfig_readme.md`	Kconfig 配置导读	使用 menuconfig 前后，确认各类配置项的作用和影响

2. Solution子目录详细介绍¶

Solution 子目录是开发核心目录，包含 framework（主框架）、components（组件库）、examples（示例工程）、tools（开发工具） 四大核心模块，各模块功能、目录组织及使用逻辑如下：

2.1 framework¶

提供 Solution 运行的底层核心框架，涵盖 UI 调度、基础组件、系统服务及板级配置模板，是所有应用开发的“地基”，确保功能兼容性与稳定性。

2.1.1 核心组成¶

子目录/文件	功能说明
`gui_fwk`	UI 调度主框架：负责应用间调度切换、应用内页面管理、动画效果（如过渡动画、滑动动效）调度，保障 UI 操作流畅度。
`gui_widget`	基础 UI 组件库：封装按钮、列表、图表、弹窗、进度条等常用控件，支持自定义样式（如颜色、字体）与交互逻辑（如点击、滑动事件），可直接调用。
`service`	系统服务层，向上提供统一调用接口。包括IPC通信机制、线程、多语言、flashdb、内存管理、动态应用机制、电池管理、button、低功耗等服务
`__template__`	工程生成模板目录：存放 Butterfli 创建/初始化工程时使用的配置和工程骨架，包括： - HCPU flash 分区表（`config/hcpu/flash_map`） - HCPU/LCPU/OTA 链接脚本（`linker_script`） - HCPU/LCPU MSP 配置（`msp_config`，包含 `HAL_MspInit`、MPU/cache 等启动相关配置） - HCPU、LCPU、OTA、Simulator 等子工程模板（`project`）

2.1.2 关键注意事项¶

配置加载逻辑：Butterfli 开发工具根据 PrjCfg.ini 中的路径，从 __template__ 载入 flash 分区表、链接脚本、HCPU/LCPU MSP 文件以及工程骨架，用于初始化或更新工程；

警告

若需调整 flash 分区、链接地址、MSP/MPU/cache 等模板配置，请修改 __template__ 下的对应文件。不要修改 HCPU/LCPU/Simulator 工程目录下由模板生成的同名文件；这些文件在后续重新生成或同步工程时可能被模板覆盖，导致修改失效。

2.1.3 目录结构¶

2.2 components（组件库目录）¶

提供解耦式功能组件，覆盖通信、硬件适配、系统服务等场景，组件间独立无强依赖，支持按需集成，灵活搭建产品功能，避免冗余代码，降低开发与维护成本。

2.2.1 组件分类与功能¶

组件目录	功能说明
`alipay`	支付宝支付码、乘车码、安全、通信及适配层相关组件
`app_tool`	应用工具组件，按 `APP_TOOL_SUPPORT` 开关集成
`battery`	电池检测、温控、强制充电等电池服务组件
`ble`	BLE 服务、连接、NVM、AMS/ANCS/HID、OTA、微信及 Zephyr BLE 相关组件
`bt`	传统蓝牙服务组件，覆盖 HF、A2DP、SPP、AVRCP、AG、HID、PBAP、GATT 等 profile
`button`	按键服务组件，主要面向 HCPU 或 PC 仿真工程
`call`	蓝牙通话功能组件，随 `BT_USING_HF` 等通话能力启用
`comm`	Solution 通用通信与信息封装组件
`db`	HCPU/PC 仿真侧实时数据库组件
`freq_resp`	频响相关功能组件，主要用于 HCPU 或 PC 仿真工程
`fs`	文件系统扩展组件，依赖 DFS 或 PC 仿真环境
`lcpu`	HCPU/LCPU 协同相关服务组件
`message`	应用消息管理组件，随 `APP_MESSAGE_USED` 启用
`metrics`	开机性能/指标统计组件，随 `USING_POWER_ON_METRICS` 启用
`micropython`	MicroPython 与 LVGL 绑定支撑组件，按存储介质和色深选择生成文件
`music`	音乐播放组件，支持本地、BLE、BT 等音频播放路径
`net`	网络应用服务组件，随 `APP_NETWORK_USED` 或 PC 仿真环境启用
`nvm`	NVM 参数存储组件，主要面向 HCPU 或 PC 仿真工程
`nxp`	NXP GUI Guider 动态应用模板与适配组件
`ota`	OTA 升级组件，包含普通 OTA、扩展 OTA、传输、OTA Manager 等子模块
`pm`	低功耗和电源管理相关组件，支持可选动画逻辑
`quickjs`	QuickJS 与 LVGL/脚本运行框架组件
`recorder`	录音/音频采集相关服务组件，非 LCPU 和非 OTA Manager 工程集成
`sensor`	传感器服务、NVM、算法及 GPS/加速度/心率/环境光/磁力计等驱动适配组件
`squareline`	SquareLine Studio 动态应用模板与适配组件
`support_script`	组件构建、工程生成或发布流程使用的辅助脚本目录
`sys_cfg`	系统配置服务组件，随 `USING_SYS_CFG` 启用
`tf`	TF 卡服务组件，随 `USING_TF_CARD` 启用
`tf_install`	TF 卡安装工具组件，依赖 DFS 和 TF 卡能力
`usb_mstorage`	USB 大容量存储组件，随 `RT_USB_DEVICE_MSTORAGE` 启用
`weather`	天气服务组件，依赖 WebClient 或 PC 仿真环境
`wifi`	Wi-Fi 应用与 Wi-Fi NVM 管理组件，随 `APP_WIFI_USED` 或 PC 仿真环境启用
`xiaozhi`	小智 AI 交互组件，依赖网络应用能力并支持 WebSocket/MQTT 路径

说明： Kconfig 和 SConscript 是组件目录的配置/构建入口文件，不作为独立组件列入上表。

2.2.2 使用逻辑¶

组件通过 menuconfig/Kconfig 中的宏定义开关控制是否集成，最终在各组件的 SConscript 中通过 GetDepend() 判断后加入编译；
常见组件开关关系如下，实际是否编译还会叠加 HCPU/LCPU、PC 仿真、OTA Manager 等工程类型条件：

组件目录	主要宏/条件	说明
`alipay`	`PKG_ALIPAY_PAY_CODE`、`PKG_ALIPAY_TRANSPORT_CODE` 及各 `PKG_ALIPAY_*` 子开关	支付宝相关功能按支付码、乘车码、HAL/FWK/第三方库等子模块分别裁剪
`app_tool`	`APP_TOOL_SUPPORT`	应用工具支持
`battery`	`BF0_LCPU`、`SENSOR_IN_HCPU`、`BATTERY_SERVICE_SIMULATOR`	电池服务、检测、温控、强制充电等模块按工程侧和仿真开关集成
`ble`	`BSP_BLE_SIBLES`、`BSP_BLE_AMS`、`BSP_BLE_ANCS`、`BSP_BLE_HID`、`ZBT`、`OTA_EXT_V3` 等	BLE 基础服务及 AMS/ANCS/HID/OTA/Zephyr BLE 等子能力
`bt`	`RT_USING_BT`、`BT_USING_HF`、`BT_USING_A2DP`、`BT_USING_SPP`、`BT_USING_AVRCP`、`BT_USING_AG`、`BT_USING_HID`、`BT_USING_PBAP`、`BT_USING_GATT`	传统蓝牙及 profile 级裁剪
`button`	`BF0_HCPU` 或 `BSP_USING_PC_SIMULATOR`	HCPU/仿真侧按键服务
`call`	`BT_USING_HF`	蓝牙通话服务
`comm`	默认加入	通用通信/信息封装
`db`	`BF0_HCPU` 或 `BSP_USING_PC_SIMULATOR`	HCPU/仿真侧数据库服务
`freq_resp`	`BF0_HCPU` 或 `BSP_USING_PC_SIMULATOR`	频响相关功能
`fs`	`RT_USING_DFS` 或 `BSP_USING_PC_SIMULATOR`	文件系统相关扩展
`lcpu`	默认加入	HCPU/LCPU 协同服务
`message`	`APP_MESSAGE_USED`	应用消息服务
`metrics`	`USING_POWER_ON_METRICS`	开机指标统计
`micropython`	`MICROPYTHON_USING_LVGL`、`SOLUTION_RES_USING_NAND`、`LV_COLOR_DEPTH_16/24`	MicroPython/LVGL 绑定，并按存储介质和色深选择源码
`music`	`PKG_USING_LIBHELIX`、`BSP_BLE_SIBLES`、`RT_USING_BT`、`AUDIO`	本地、BLE、BT 音乐路径按音频与协议栈开关裁剪
`net`	`APP_NETWORK_USED` 或 `BSP_USING_PC_SIMULATOR`	网络应用服务
`nvm`	`BF0_HCPU` 或 `BSP_USING_PC_SIMULATOR`	HCPU/仿真侧 NVM 服务
`nxp`	`APP_DLMODULE_APP_USED`	NXP GUI Guider 动态应用模板
`ota`	`BSP_USING_DFU`、`OTA_EXT_V3`、`BT_PAN_OTA`、`TF_OTA`、`USB_OTA`、`DFU_OTA_MANAGER` 等	OTA 应用、扩展 OTA、传输和 OTA Manager 按场景裁剪
`pm`	`BF0_HCPU` 或 `BSP_USING_PC_SIMULATOR`，可选 `PM_ANIM_USED`	电源管理及可选动画
`quickjs`	`QUICKJS_LVGL`	QuickJS/LVGL 脚本框架
`recorder`	非 `BF0_LCPU` 且非 `DFU_OTA_MANAGER`	录音/音频采集服务
`sensor`	`RT_USING_SENSOR`、`RT_USING_GPS`、`SENSOR_SERVICE_SIMULATOR`、`SENSOR_ALGO_SIMULATOR`、`SENSOR_IN_HCPU`、各传感器型号开关	传感器服务、算法和具体器件驱动按能力裁剪
`squareline`	`APP_DLMODULE_APP_USED`	SquareLine Studio 动态应用模板
`sys_cfg`	`USING_SYS_CFG`	系统配置服务
`tf`	`USING_TF_CARD`	TF 卡服务
`tf_install`	`USING_TF_CARD`、`RT_USING_DFS`	TF 卡安装工具
`usb_mstorage`	`RT_USB_DEVICE_MSTORAGE`	USB 大容量存储
`weather`	`PKG_USING_WEBCLIENT` 或 `BSP_USING_PC_SIMULATOR`	天气网络服务
`wifi`	`APP_WIFI_USED` 或 `BSP_USING_PC_SIMULATOR`	Wi-Fi 应用与 NVM 管理
`xiaozhi`	`XIAOZHI_SUPPORT`、`APP_NETWORK_USED`、`PKG_USING_NETWORK_WEBSOC`、`PKG_USING_NETWORK_MQTT`	小智 AI 交互，并按 WebSocket/MQTT 网络路径裁剪

2.3 examples¶

包含产品例程，覆盖新手入门到量产参考的需求，代码注释清晰，可直接参考复用，降低学习与开发成本。

2.3.1 目录组织规则¶

带下划线前缀（_XXX）：非板级工程，通用演示或工具适配类，不绑定具体硬件；
不带下划线前缀：板级工程，绑定特定硬件方案（如手表、宫格终端），可直接编译烧录验证。

2.3.2 各子目录详细说明¶

2.3.3 板级工程内部结构¶

每个不带下划线的板级工程（如 watch、grid_view、container），内部按“功能模块”标准化组织，方便定位代码，典型结构如下：
（包含 application（应用代码）、project（工程）、resource（资源）等子目录）

2.3.4 建议阅读顺序¶

第一次看 examples 时，不建议把所有示例都从头读一遍。更推荐先选一个合适的工程，再顺着工程目录阅读。

solution/examples/readme.md
  ↓
选择 hello_world / watch / grid_view / container 等工程
  ↓
solution/examples/<工程名>/readme.md
  ↓
application/readme.md  # 看应用代码入口
resource/readme.md     # 看图片、字体、多语言等资源
  ↓
project/               # 看具体板级工程、编译配置和生成文件

各类产品可以优先从下面的工程开始：

产品或学习目标	建议工程	说明
只想先跑通开发流程	`hello_world`	工程最简单，适合确认环境、编译、烧录和应用入口
手表、手环等复杂带屏产品	`watch`	功能完整，包含表盘、菜单、平铺和常见系统应用
简单带屏产品或轻量菜单产品	`grid_view`	比 `watch` 更轻量，适合只需要宫格菜单的场景
单应用产品或后装应用产品	`container`	默认无内置应用，适合从空框架开始定制
外置表盘、外置应用或工具生成应用	`_dynamic_app`	用于学习动态应用、动态表盘、GUI Builder、QJS、MicroPython 等能力

选定工程后，需要结合 solution/kconfig_readme.md 检查工程配置。示例工程的默认配置通常偏演示用途，实际项目应根据芯片、屏幕、存储、蓝牙、传感器、OTA、低功耗和资源方案重新确认。

2.4 tools（工具目录）¶

提供 Solution 开发全流程所需的开发辅助工具与产线工具，覆盖“开发-调试-量产”各环节，提升效率并保障量产稳定性。

开发工具Butterfli：一站式开发工具，集成工程创建、编译、烧录、调试功能
产线烧写工具Impeller：16 通道并行烧录工具（支持 SWD/UART 模式）
GUI_Builder工具：可视化 UI 开发工具，零编程制作表盘/应用
Graphics_convert：图形转换工具，提供图片、视频的转换，主要用于外置SD/TF卡的资源