总体架构与工程分层

本文档介绍杰理 AC792N_AIoT_SDK 的整体架构与工程分层：从仓库根目录布局、sdk/ 内部的分层结构、应用/平台/中间件边界，到 project.jlproj 工程文件与 src/ 配置体系的联动方式，帮助开发者快速建立对整个固件工程的全局认知。

Purpose and Scope

本页面是 AC792N SDK 的入口级导航文档，覆盖：

• 仓库顶层目录布局（sdk/、src/、ui_prj/、doc/、project.jlproj 等）及其职责；
• sdk/ 内部的分层架构：应用层（apps/）、中间件层（audio/、common/config/）、平台层（cpu/wl83/、include_lib/、lib/）；
• 工程变体（variant）机制与 project.jlproj 的配置驱动设计；
• 构建系统（Makefile target）与配置到固件的编译流水线。

以下主题不属于本页范围，由其他目录页覆盖：具体模块 API（蓝牙协议栈、媒体框架、LVGL 等）、各方案工程的业务逻辑细节、烧录/升级工具使用、在线文档中的模块开发指南。本页仅给出"哪里有什么、如何组织、如何构建"的总体视图。

概述

AC792N_AIoT_SDK 是杰理科技为 AC792N 系列 AIoT 多媒体 SoC 提供的通用 SDK 固件开发包。AC792N 是一颗低成本、高集成度的 WiFi 802.11b/g/n + 双模蓝牙 V5.4 音视频多媒体系统级芯片，内部集成主频高达 320MHz 的双核浮点 DSP，并完整集成音频（ADC/DAC）、视频（DVP/MIPI 摄像头 + ISP）、显示（MIPI/RGB 推屏 + LVGL/AWTK + GPU2.5D）与丰富外设资源（README.md）。

SDK 的定位与设计意图

整个仓库的设计围绕 "一个芯片平台、多套方案工程、配置驱动裁剪" 展开：

1. 平台与方案分离：芯片平台代码（sdk/cpu/wl83/）、预编译库（sdk/lib/、cpu/wl83/liba/）与方案应用（sdk/apps/*/）物理隔离，应用工程只需关心业务与板级配置，不接触底层寄存器级实现。
2. 二进制与源码分层：协议栈、驱动、编解码器等以预编译静态库（*.a）提供，接口以头文件形式暴露于 sdk/include_lib/，既保护了核心实现，又保证了应用层可编译、可链接。
3. 配置驱动：仓库根 project.jlproj 统一管理工程变体（variant）与全部可视化配置（板级/功能/蓝牙/网络/音频/LE_AUDIO/音频流程），配置被编译打包为 boardcfg.bin、modecfg.bin、stream.bin 等运行时配置块，实现"改配置不改代码"。
4. 多方案复用：sdk/apps/common/ 集中承载跨工程共享的音频、视频、显示、AI 等中间件，wifi_camera、wifi_soundbox、wifi_bbm 三个方案与 7 个 demo 工程均复用同一公共底座。

架构

仓库顶层布局

flowchart TD
    subgraph sg_Root["仓库根 fw-AC792_SDK"]
        JL["project.jlproj<br/>杰理工程文件<br/>（变体 + 配置清单）"]
        SRC["src/<br/>项目配置<br/>（板级/功能/蓝牙/网络/音频 JSON + 音频流程 x6flow）"]
        SDK["sdk/<br/>SDK 主体（源码 + 预编译库 + 构建系统）"]
        UI["ui_prj/<br/>杰理 UI 工程资源"]
        DOC["doc/ + docs/<br/>数据手册/硬件资料/在线文档源"]
        ST["sdk_tools/<br/>SDK 工具"]
        RM["README.md / README-en.md<br/>SDK 使用手册"]
    end

    JL -->|"引用并驱动"| SRC
    JL -->|"选择 variant 路径"| SDK
    SRC -->|"编译期打包为 bin"| SDK
    RM -->|"说明整体用法"| SDK
    UI -->|"生成 UI 资源供应用引用"| SDK

仓库根目录职责如下（README.md 工程结构）：

SDK 内部分层

flowchart TD
    subgraph sg_App["应用层 sdk/apps/"]
        CAM["wifi_camera<br/>WiFi 摄像头方案"]
        SB["wifi_soundbox<br/>WiFi 智能音箱方案"]
        BBM["wifi_bbm<br/>婴儿监护器方案"]
        DEMO["demo<br/>7 个功能示例工程"]
        COMMON["common<br/>跨工程公共模块<br/>asr/audio_music/camera/lcd/lvgl_v8/v9/<br/>dma2d_gpu/pjsip/jlttf/screen_mirror/video/LLM"]
    end

    subgraph sg_Mid["中间件与板级层"]
        AUDIO["audio/<br/>音频中间件"]
        CFG["common/config/<br/>蓝牙 Profile/用户参数/授权码/日志"]
        BOARD["board/wl83/<br/>板级配置<br/>board_develop_AC79xx.h / sdk_config.h"]
    end

    subgraph sg_Platform["平台与库层"]
        CPU["cpu/wl83/<br/>CPU 平台代码 + liba 预编译库 + tools"]
        INCLIB["include_lib/<br/>btctrler/btstack/driver/media/net/system/update 头文件"]
        LIB["lib/<br/>预编译静态库 *.a"]
    end

    subgraph sg_Build["构建系统"]
        MK["sdk/Makefile<br/>统一编译入口"]
        BAT["make_prompt.bat<br/>Windows 命令行环境"]
        WS["default.workspace<br/>工程工作区"]
    end

    CAM --> COMMON
    SB --> COMMON
    BBM --> COMMON
    DEMO --> COMMON
    COMMON --> AUDIO
    COMMON --> CFG
    CAM --> BOARD
    SB --> BOARD
    BBM --> BOARD
    DEMO --> BOARD
    COMMON --> INCLIB
    BOARD --> CPU
    INCLIB --> LIB
    MK --> CAM
    MK --> SB
    MK --> BBM
    MK --> DEMO
    BAT --> MK

架构要点（设计意图）：

• 应用层依赖公共底座：四个应用域（3 方案 + 7 demo）全部构建在 apps/common/ 之上，新增方案只需复用 common 模块并编写板级配置，避免重复实现。
• 接口与实现分离：应用层通过 include_lib/ 的头文件调用底层能力，实现封装在 lib/ 与 cpu/wl83/liba/ 的预编译库中；功能裁剪通过 common/config/ 的配置项完成，而不是修改库源码。
• 板级配置是方案与芯片的粘合层：board/wl83/ 下的 board_develop_AC79xx.h 按芯片型号区分引脚映射、外设使能与时钟内存配置，是移植到不同型号（AC7921A~AC7926A）的核心修改点。

工程变体与配置驱动

project.jlproj 通过 variant 数组声明可选工程，并通过 defaultVariant 指定默认工程；每个变体指向具体的 sdk/apps/*/board/wl83/ 目录及其 make task（project.jlproj）：

flowchart LR
    JL["project.jlproj"] -->|"defaultVariant"| SB["wifi_soundbox/board/wl83<br/>task: ac792n_wifi_soundbox"]
    JL -->|"variant["0"]"| CAM["wifi_camera/board/wl83<br/>task: ac792n_wifi_camera"]
    SRC["src/ 配置<br/>板级/功能/蓝牙/LE_AUDIO/网络/音频 JSON"] -->|"tabform 清单"| CFG["配置编译工具"]
    CFG -->|"打包"| BINS["boardcfg.bin / modecfg.bin / btcfg.bin<br/>leacfg.bin / audiocfg.bin / stream.bin"]
    MK["make &lt;task&gt;"] --> FW["固件产物"]
    BINS --> FW
    SB --> MK
    CAM --> MK

工程分层详解

应用层：sdk/apps/

应用层是开发者主要编写业务代码的地方，包含方案工程、公共模块与功能示例三类（README.md）：

7 个 demo 工程覆盖了从"最小启动骨架"（demo_hello）到单项能力验证（BLE 数传、EDR 音乐、WiFi 联网、音频采集播放、LVGL UI）的完整梯度，是理解 SDK 模块接口的最佳起点（README.md）。

板级配置层：sdk/apps/*/board/wl83/

每个应用目录下的 board/wl83/ 是方案与芯片之间的粘合层，包含（README.md）：

• Makefile — 编译脚本；
• AC792N_*.cbp — Code::Blocks IDE 工程文件；
• board_develop_AC79xx.h — 板级配置头文件，按芯片型号区分（如 board_develop_AC7926A.h），定义引脚映射、外设使能、时钟、内存配置；
• board_develop.c / sdk_config.h — 板级初始化与全局配置。

设计意图：板级与业务解耦。换芯片型号或改硬件引脚时，主要修改该目录下的板级配置头文件，业务代码不受影响。这也是官方 FAQ 推荐的新工程创建路径——复制最接近的方案工程，替换 board_develop_AC79xx.h（README.md）。

平台与库层：cpu/、include_lib/、lib/

• sdk/cpu/wl83/：CPU 平台代码 + 预编译库（liba/*.a）+ 烧录工具（tools/）；
• sdk/include_lib/：全部对外头文件，按模块分目录——btctrler（蓝牙控制器）、btstack（蓝牙协议栈）、driver（驱动）、media（媒体）、net（网络）、system（系统）、update（升级）等（README.md）；
• sdk/lib/：预编译静态库（*.a）。

这一层体现了 SDK 的二进制分发策略：协议栈与编解码器等体积大、成熟稳定的部分以 .a 静态库交付，链接期由 -lxxx 引用；编译错误 cannot find -lxxx 通常意味着该目录缺少对应库文件（README.md）。

库配置层：sdk/apps/common/config/

该目录集中了功能裁剪与参数配置，是控制固件体积与行为的关键（README.md）：

设计意图：裁剪即配置。链接期出现 undefined reference to ... 时，优先检查该目录下对应模块是否被裁剪（README.md）。

中间件层：sdk/audio/

audio/ 是独立于应用的音频中间件目录，承载音频框架相关的中间件代码，与 apps/common/audio_music 等应用侧音频模块配合，共同构成 SDK 的媒体能力。

配置体系：project.jlproj + src/

仓库采用"工程文件驱动 + 可视化配置"的模式：project.jlproj 定义工程元信息与配置清单（tabform），src/ 存放各类配置源文件（JSON / tone / x6flow），编译时被打包为二进制配置块（project.jlproj）：

音频流程（*.x6flow）是这套配置体系中最具特色的部分：系统模式、媒体、蓝牙通话、麦克风音效、USB Audio、录音、声波配网、智能语音、LE_Audio、recoder_vir_tx 共 10 个流程以图形化流程文件定义，统一打包进 stream.bin，使音频通路拓扑可以脱离代码在工具中调整。

构建系统与核心流程

构建入口

SDK 顶层提供统一的构建入口（sdk/Makefile 与 sdk/make_prompt.bat）：

• Windows：双击 sdk/make_prompt.bat 进入预配置的命令行环境（脚本已设置好 make 路径与环境变量），或直接使用 Code::Blocks 打开 board/wl83/AC792N_*.cbp 工程；
• Linux：在 sdk/ 目录执行 make <target>，如 make ac792n_wifi_camera；
• 全部 target 名称见 sdk/Makefile 开头注释（README.md）。

常用 make target（README.md）：

从配置到固件的完整流水线

sequenceDiagram
    participant Dev as 开发者
    participant JL as project.jlproj
    participant SRC as src/ 配置源
    participant MK as Makefile / Code::Blocks
    participant SDK as sdk/ 编译链接
    participant FW as 固件产物

    Dev->>JL: 选择变体（默认 wifi_soundbox）<br/>选择配置（tabform 清单）
    JL->>SRC: 读取板级/功能/蓝牙/网络/音频 JSON<br/>与音频流程 x6flow
    SRC-->>MK: 配置源文件
    Dev->>MK: make ac792n_wifi_soundbox<br/>或 IDE Build
    MK->>SDK: 进入 board/wl83 编译应用层
    SDK->>SDK: 解析 board_develop_AC79xx.h / sdk_config.h
    SDK->>SDK: 链接 include_lib + lib + cpu/wl83/liba
    MK->>MK: 打包配置为 boardcfg.bin / stream.bin 等
    SDK-->>FW: 生成固件镜像
    Dev->>FW: USB 升级工具 / 生产烧写工具烧录

Linux 编译注意点

• 链接阶段需要打开大量文件，先执行 ulimit -n 8096 提升文件描述符限制；
• 并行编译加速：make ac792n_wifi_camera -j\nproc``；
• 常见错误排查（README.md）：clang: command not found 表示工具链未安装或环境变量未配置；cannot find -lxxx 表示缺少对应 .a 库；undefined reference to ... 表示功能裁剪配置未包含对应模块。

工程元数据：project.jlproj 关键字段

variant + defaultVariant 机制的设计意图：同一份仓库可同时管理多套方案，IDE 依据 defaultVariant 决定默认打开的工程，开发者可通过工具切换变体而无需改动代码（project.jlproj）。

使用示例

示例 1：查看工程变体与默认工程

project.jlproj 中的变体声明决定了 IDE 打开的工程与 make task（本仓库包含 wifi_camera 变体，默认工程为 wifi_soundbox）：

{
  "variant": [
    {
      "name": "wifi_camera",
      "path": ".\\sdk\\apps\\wifi_camera\\board\\wl83",
      "task": " ac792n_wifi_camera"
    }
  ],
  "defaultVariant": {
    "path": ".\\sdk\\apps\\wifi_soundbox\\board\\wl83",
    "task": "ac792n_wifi_soundbox",
    "name": "默认配置"
  }
}

Source: project.jlproj

示例 2：编译指定方案

在 sdk/ 目录下选择目标工程编译（Windows 用户先运行 make_prompt.bat；Linux 用户注意 ulimit -n 8096）：

# 编译 WiFi 摄像头方案
make ac792n_wifi_camera

# 并行编译 WiFi 智能音箱（默认变体）
make ac792n_wifi_soundbox -j`nproc`

# 编译最小启动示例工程
make ac792n_demo_demo_hello

# 清理单个工程产物
make clean_ac792n_wifi_camera

Source: README.md

示例 3：基于方案工程创建新工程

SDK 官方推荐的自建工程路径——复制最接近的方案，替换板级配置：

sdk/apps/<你的工程>/board/wl83/
├── Makefile                        # 编译脚本
├── AC792N_*.cbp                    # Code::Blocks 工程文件
├── board_develop_AC79xx.h          # 板级配置（按芯片型号，如 board_develop_AC7926A.h）
├── board_develop.c                 # 板级初始化
└── sdk_config.h                    # 全局配置

Source: README.md

故障模式与边界情况

• 编译错误 clang: command not found：杰理编译工具链未安装或环境变量未配置。Windows 使用 sdk/make_prompt.bat，Linux 确保 /opt/jieli/common/bin/clang 存在（README.md）。
• Too many open files：Linux 链接阶段文件描述符不足，执行 ulimit -n 8096（README.md）。
• cannot find -lxxx：sdk/cpu/wl83/liba/ 与 sdk/lib/ 缺少对应 .a 库文件，检查平台库是否完整。
• undefined reference to ...：sdk/apps/common/config/ 下功能裁剪配置未包含对应模块，属配置问题而非源码问题（README.md）。
• 芯片型号差异：AC792N 系列不同型号（AC7921A~AC7926A）封装、存储容量、内存类型（DDR1/SDRAM）不同，选型与板级配置必须匹配，参考 doc/硬件资料/datasheet/ 选型表（README.md）。
• 分支选择：仓库为开发主线（AC792N_SDK_V3），量产建议使用对应的稳定发布版本；版本号遵循 major.minor.patch 语义（README.md）。

扩展点

SDK 的扩展主要沿三条路径进行：

1. 新增方案工程：复制 sdk/apps/ 下最接近的方案，在 board/wl83/ 中适配 board_develop_AC79xx.h 与 .cbp，并在 sdk/Makefile 中注册新 target。
2. 扩展公共模块：在 sdk/apps/common/ 下新增共享中间件（如新的音效、UI 框架、AI 平台对接），供各方案工程复用；AI 云平台类对接（图灵、百度云、腾讯云、涂鸦、阿里云、华为 HiLink 等）均在此层扩展（README.md）。
3. 调整功能与音频流程：通过 src/ 下的 JSON 配置与 音频流程/*.x6flow 图形化流程文件调整功能集与音频通路拓扑，无需改动 C 代码，由 project.jlproj 的 tabform 清单统一管理（project.jlproj）。

运维与调试建议

• 串口日志：通过 sdk/apps/common/config/log_config/ 配置日志输出等级和通道；
• GPIO 调试：利用空闲 GPIO 输出调试波形，测量时序；
• 烧录工具：开发阶段用 USB 升级工具，量产用生产烧写工具；升级支持 SD 卡/U 盘（不备份升级）与 WiFi/蓝牙（备份升级，失败可回滚）（README.md）。

相关链接

• README.md（SDK 使用手册总入口）
• project.jlproj（杰理工程文件）
• sdk/Makefile（构建入口）
• AC792 在线文档中心
• 相邻目录页：应用方案（wifi_camera / wifi_soundbox / wifi_bbm）、功能配置体系、构建与烧录指南