工程结构总览

本页系统梳理 fw-AC82N_GP-MCU_SDK 仓库的整体布局，说明各顶层目录、关键文件与构建入口的职责，帮助开发者快速定位应用代码、驱动、示例、工具链与独立工程。

Purpose and Scope

本页是仓库的结构导航页，覆盖以下内容：

• 仓库顶层目录（apps/、cpu/、include_lib/、tools/、UBOOT工程/、UI工程/）的职责划分；
• 顶层构建入口（Makefile、AC82N_gp_mcu.cbp、.vscode/）与编译/烧录全流程；
• 关键目录之间的调用与依赖关系、常用配置与裁剪入口。

与仓库布局相关的具体开发细节不在本页展开，而由各自页面或外部文档承载，例如：

• 外设驱动用法（HADC/UART/SPI/IIC/MCPWM/RTC 等）见 cpu/demo/ 示例与对应外设文档；
• 环境搭建与工具链安装细节见 README「环境搭建」章节及杰理文档中心；
• UBOOT 工程、UI 工程为独立编译单元，其内部结构另有说明，本页仅说明它们在仓库中的位置与耦合方式。

Overview

fw-AC82N_GP-MCU_SDK 是珠海杰理科技为 AC82N 系列芯片提供的通用 MCU SDK Release 版本代码及示例工程。AC82N 系列定位为无蓝牙功能的通用 MCU SoC，主要面向两类应用场景：

芯片平台为 cd09，覆盖 AC822B / AC823B / AC825A / AC826B 四个型号。SDK 的核心特性包括：

• 24 位高精度 HADC：有效精度最高可达 19bit；
• 高速 SARADC：采样率可达 1Msps；
• 超低功耗处理器与低功耗 RTC：支持闹钟和唤醒，适合电池供电；
• 丰富的片上外设：HADC、SARADC、IIC、SPI、MCPWM、UART、USB、触摸按键等；
• 支持 APA 播报。

仓库以「统一 GP MCU 应用工程」为入口（位于 sdk/apps/gp_mcu/），配合按命名规则提供的预编译静态库（lib.a）进行链接编译。整个仓库是一个多工程并存的布局：顶层 Makefile 统一驱动主应用与 cd09 平台构建，而 UBOOT工程/ 与 UI工程/ 作为独立编译单元共存于仓库根目录。

Architecture

仓库顶层布局

flowchart TD
    subgraph sg_Root["仓库根目录 fw-AC82N_GP-MCU_SDK"]
        Makefile["Makefile（顶层统一编译入口）"]
        CBP["AC82N_gp_mcu.cbp（Code::Blocks 工程）"]
        VSCode[".vscode/（VS Code 任务配置）"]
    end

    subgraph sg_Apps["apps/ 应用层"]
        GpMcu["apps/gp_mcu/（GP MCU 主应用入口）"]
        Common["apps/common/（公共模块：AT指令/电池/UI/升级等）"]
    end

    subgraph sg_Cpu["cpu/ 芯片平台与驱动"]
        Cd09["cpu/cd09/（hadc / liba / power / segment_code_lcd / tools）"]
        Demos["cpu/demo/（外设示例代码）"]
        Components["cpu/components/（通用组件，如红外编解码）"]
        Gpio["cpu/gpio.c / iic_api.c / iic_soft.c"]
    end

    subgraph sg_Include["include_lib/ 头文件"]
        DriverH["driver/（驱动头文件）"]
        SystemH["system/（系统头文件）"]
    end

    subgraph sg_Tools["tools/ 编译工具与脚本"]
        PromptBat["make_prompt.bat（Windows 命令行入口）"]
        Utils["utils/（make / rm 等工具集）"]
    end

    subgraph sg_Projects["独立编译工程"]
        Uboot["UBOOT工程/"]
        UiProj["UI工程/"]
    end

    Makefile --> GpMcu
    Makefile --> Cd09
    Makefile --> Demos
    CBP --> GpMcu
    GpMcu --> Common
    Cd09 --> Components
    PromptBat --> Makefile
    Uboot -. 独立编译 .-> Makefile
    UiProj -. 独立编译 .-> Makefile

该图基于 README.md 第五节「工程结构」 的目录树绘制，节点名称与仓库实际目录一一对应。

分层调用关系

flowchart TD
    subgraph sg_App["应用层 apps/"]
        Main["gp_mcu 主应用（main 入口 / 配置入口）"]
        CommonM["common 公共模块（AT/电池/UI/升级/设备驱动封装）"]
    end

    subgraph sg_Sys["系统头文件 include_lib/"]
        SysH["system / driver 头文件（接口契约）"]
    end

    subgraph sg_Drv["驱动与平台 cpu/"]
        DrvCd09["cd09 平台驱动（HADC/SARADC/电源/段码LCD）"]
        DrvDemo["demo 外设示例（可直接参考/移植）"]
        DrvCommon["components 通用组件（红外等）"]
    end

    subgraph sg_Hw["硬件"]
        Hw["AC82N SoC（cd09 平台，AC822B/823B/825A/826B）"]
    end

    Main --> CommonM
    Main --> SysH
    CommonM --> SysH
    Main --> DrvCd09
    CommonM --> DrvCd09
    DrvDemo -. 示例参考 .-> DrvCd09
    DrvCd09 --> Hw
    DrvCommon --> Hw

设计意图：仓库按层次分离组织 —— apps/ 只关心业务与应用逻辑，通过 include_lib/ 中的头文件契约调用驱动，具体驱动实现位于 cpu/ 平台目录；cpu/demo/ 则作为「活文档」，展示每个外设的最小可用用法，是新工程移植外设的首选参考。

顶层目录布局详解

仓库的完整目录树定义于 README.md 第五节（节选关键结构如下）：

fw-AC82N_GP-MCU_SDK/
├── apps/                          # 应用层代码
│   ├── common/                    # 公共模块（跨工程共享）
│   │   ├── at_char/               #   AT 指令处理
│   │   ├── battery/               #   电池电量检测
│   │   ├── cJSON/                 #   JSON 解析库
│   │   ├── debug/                 #   调试工具
│   │   ├── decode/                #   解码模块
│   │   ├── device/                #   外设驱动（按键、USB device/host）
│   │   ├── eeprom/                #   EEPROM 读写
│   │   ├── font/                  #   字库
│   │   ├── lcd/                   #   LCD 驱动
│   │   ├── sin_generator/         #   正弦波发生器
│   │   ├── ui/                    #   UI 控件
│   │   ├── ui_platform/           #   UI 平台层
│   │   └── update/                #   固件升级
│   └── gp_mcu/                    #   📌 GP MCU 主应用入口
│       └── include/               #   应用头文件
├── cpu/                           # CPU 相关代码与库文件
│   ├── cd09/                      #   cd09 芯片平台
│   │   ├── hadc/                  #     高精度 ADC 驱动
│   │   ├── liba/                  #     预编译库文件 (.a)
│   │   ├── power/                 #     电源管理
│   │   ├── segment_code_lcd/      #     段码 LCD 驱动
│   │   └── tools/                 #     链接脚本 / 下载脚本
│   ├── components/                #   通用组件（红外编解码等）
│   ├── demo/                      #   外设示例代码
│   ├── gpio.c                     #   GPIO 驱动
│   ├── iic_api.c                  #   IIC 硬件接口
│   └── iic_soft.c                 #   软件模拟 IIC
├── include_lib/                   # 头文件
│   ├── driver/                    #   驱动头文件（cpu / device）
│   ├── system/                    #   系统头文件（device / fs / generic）
│   ├── ui_platform/               #   UI 平台头文件
│   └── update/                    #   升级模块头文件
├── tools/                         # 编译工具与脚本
│   ├── make_prompt.bat            #   Windows 编译命令行入口
│   └── utils/                     #   工具集（make、rm 等）
├── UBOOT工程/                     # UBOOT 工程（独立编译）
├── UI工程/                        # UI 工程（独立编译）
├── Makefile                       # 顶层 Makefile（统一编译入口）
├── AC82N_gp_mcu.cbp               # Code::Blocks 工程文件
└── .vscode/                       # VS Code 配置（tasks.json）

来源：README.md 第五节「工程结构」

apps/ —— 应用层

• apps/gp_mcu/：整个 SDK 的主应用入口，包含应用主函数与配置入口，是开发时最主要的工作目录。include/ 子目录存放应用层头文件。
• apps/common/：跨工程共享的公共模块，与具体芯片平台解耦。包括 AT 指令解析（at_char/）、电池检测（battery/）、JSON 解析库（cJSON/）、调试工具（debug/）、解码（decode/）、设备驱动封装（device/，按键、USB device/host）、EEPROM 读写、字库（font/）、LCD 驱动、正弦波发生器（sin_generator/）、UI 控件与 UI 平台层（ui/、ui_platform/）、固件升级（update/）。

设计意图：把「与业务无关的通用能力」下沉到 common/，使 gp_mcu/ 主应用保持精简，同时保证这些模块可被未来其他工程复用。

cpu/ —— 芯片平台与驱动

• cpu/cd09/：cd09 芯片平台专属代码。其中 hadc/ 为 24 位高精度 ADC 驱动，power/ 为电源管理，segment_code_lcd/ 为段码 LCD 驱动，liba/ 存放预编译静态库（*.a），tools/ 存放链接脚本与下载脚本（编译产物 sdk.elf 即生成于此）。
• cpu/components/：与具体外设无关的通用组件，如红外编解码。
• cpu/demo/：外设示例代码，是 SDK 的「活文档」。覆盖 HADC（hadc_demo.c）、通用 ADC（gpadc_demo.c）、UART（uart_demo.c）、SPI（spi_demo.c）、IIC（iic_demo.c）、MCPWM（mcpwm_demo.c）、RTC（rtc_demo.c）、通用定时器（gptimer_demo.c）、段码 LCD（segment_code_lcd_demo.c）、正弦波发生器（sin_generator_demo.c）、NorFlash（norflash_demo.c）、APA 语音播报（voice_demo.c）等。
• 平台级基础驱动直接位于 cpu/ 根下：gpio.c（GPIO 驱动）、iic_api.c（IIC 硬件接口）、iic_soft.c（软件模拟 IIC）。

include_lib/ —— 公开头文件

头文件按 driver/（cpu / device 驱动）、system/（device / fs / generic 系统）、ui_platform/、update/ 分组。源码实现位于 cpu/ 或 apps/，此处只暴露接口契约，保证应用层与驱动层通过稳定的头文件边界协作。

tools/ —— 编译工具与脚本

• make_prompt.bat：Windows 下预配置好的命令行环境入口，双击即可获得带 make 与工具链路径的编译环境（解决 Windows 下 make 非有效命令的问题）。
• utils/：make、rm 等构建辅助工具集。

独立编译工程

• UBOOT工程/ 与 UI工程/：与主 SDK 相互独立的编译单元，位于仓库根目录。它们与主工程通过约定（如内存布局、升级协议）协同，而非共享同一套构建产物。

顶层构建文件

• Makefile：顶层统一编译入口，支持 make all、make clean、make all VERBOSE=1 等目标。
• AC82N_gp_mcu.cbp：Code::Blocks 工程文件（Windows 推荐方式，Build → Build 即 Ctrl+F9）。
• .vscode/：预配置 VS Code 任务（tasks.json），按 Ctrl+Shift+B 可选择 all / clean 目标。

关键目录速查

核心流程：从源码到固件再到烧录

仓库采用「工具链 → 顶层 Makefile → 链接脚本 → 下载脚本 → 烧录工具」的流水线。完整流程如下：

flowchart TD
    Start([开始开发]) --> Toolchain{"编译工具链已安装?"}
    Toolchain -->|"否"| Install["安装杰理编译工具链 clang"]
    Install --> Env["配置编译环境<br/>Windows: tools/make_prompt.bat<br/>Linux: ulimit -n 8096"]
    Toolchain -->|"是"| Env
    Env --> Build["make all -j`nproc` 并行编译"]
    Build --> Output["生成 cpu/cd09/tools/sdk.elf"]
    Output --> Flash["USB 升级工具 isd_download.exe 烧录"]
    Flash --> Verify{"烧录成功?"}
    Verify -->|"是"| Done([完成])
    Verify -->|"否"| Debug["检查编程模式 / 固件选择"]
    Debug --> Flash

各环节对应的仓库入口：

首次烧录的操作顺序为：USB/UART 连接开发板 → 按住烧录按键复位进入编程模式 → 启动 isd_download.exe → 选择编译生成的固件 → 点击下载。批量生产可使用代理商的生产烧写工具。OTA 场景则支持自定义双备份固件升级（由 apps/common/update/ 与 include_lib/update/ 承载）。

Usage Examples

克隆仓库并进入 SDK 入口

git clone https://gitee.com/Jieli-Tech/AC82N.git
cd AC82N/sdk

来源：README.md 第四节「快速开始」

克隆后仓库根目录为 AC82N/，SDK 主体位于 AC82N/sdk/ 下（含 Makefile 与 AC82N_gp_mcu.cbp）。README、LICENSE 位于仓库根，doc/ 下存放芯片规格书与原理图等硬件资料。

验证工具链安装

# 验证工具链是否安装成功
clang --version

Linux 用户需将杰理工具链解压到 /opt/jieli，并确保 /opt/jieli/pi32/bin/clang 存在。

来源：README.md 第三节「环境搭建」

命令行编译（Makefile）

# Windows 用户
双击 tools/make_prompt.bat 打开命令行环境

# Linux/macOS 用户
cd sdk 根目录
make all -j`nproc`

来源：README.md 第四节「编译并烧录」

编译完成后生成 cpu/cd09/tools/sdk.elf，烧录脚本会自动调用该文件。

Linux 编译注意事项

# 确保文件描述符限制足够大（链接阶段需要打开大量文件）
ulimit -n 8096

# 进入 SDK 根目录执行编译
make all -j`nproc`

来源：README.md 第七节「编译指南」

-j 参数用于并行编译（如 -j4），可显著缩短构建时间；链接阶段因需同时打开大量文件，Linux 下必须调高文件描述符上限，否则会报 Too many open files。

配置选项

SDK 的配置分为板级配置与功能裁剪两类（详见 README.md 第九节「配置说明」）：

配置入口位于 apps/gp_mcu/ 应用配置与平台配置文件中；cpu/*/tools/ 下的链接脚本决定内存布局与固件分区。

关键构建入口（命令速查）

以下命令均在 SDK 根目录（sdk/）下执行：

来源：README.md 第七节「编译指南」

Failure Modes、边界情况与并发注意

常见编译错误及处理

来源：README.md 第七节「常见编译错误」

边界与操作注意

• 烧录前置条件：烧录前必须确保 USB 升级工具正确连接、目标板已进入编程模式（按住烧录按键后复位/重新上电），否则 isd_download.exe 无法识别设备。
• 预编译库依赖：仓库为 SDK Release 代码，必须配合按命名规则提供的 *.a 库文件编译；库缺失会直接导致链接失败（cannot find -lxxx）。
• 平台绑定：当前 SDK 仅面向 cd09 平台（AC822B/823B/825A/826B），目录结构中的 cpu/cd09/ 与编译目标 make all 均以此平台为前提。
• 并发/多任务编译：链接阶段需要同时打开大量文件，并行编译（-j）在 Linux 下受文件描述符上限约束，需先 ulimit -n 8096；Windows 下通过 tools/make_prompt.bat 提供的预配置环境规避路径与环境变量问题。
• 独立工程耦合：UBOOT工程/ 与 UI工程/ 为独立编译单元，改动主 SDK 后需按约定重新编译对应工程，不能指望顶层 Makefile 一并处理。

性能与运维注意事项

• 编译速度：使用 -j 参数并行编译（如 make all -j4）是官方推荐的提速手段。
• 链接资源：链接阶段文件描述符需求高，Linux 下 ulimit -n 8096 为必需步骤。
• 调试手段：可通过 UART 输出串口日志；利用空闲 GPIO 输出调试波形测量时序。
• 固件产物定位：编译产物固定生成于 cpu/cd09/tools/sdk.elf，烧录脚本自动引用，开发时应避免改动该路径约定。
• 升级链路：量产可走生产烧写工具（裸片烧写），运行期升级走 OTA 双备份方案（apps/common/update/），两种路径均与 cpu/*/tools/ 的下载脚本配合。

Extension Points：如何扩展工程

仓库的扩展方式在 README.md 第十节「常见问题」 中有明确指引：

• 创建新工程：基于现有的 apps/gp_mcu/ 与 cpu/demo/ 示例修改，配置对应的引脚和外设即可。apps/common/ 中的公共模块可直接复用，无需重新实现。
• 添加新外设驱动：参考 cpu/demo/ 中的示例代码，按照现有驱动框架在 cpu/ 下添加新的驱动文件；对外接口头文件放入 include_lib/driver/，保持应用层与驱动层的契约边界。
• 功能裁剪：通过配置文件开关各模块（外设使能、模块功能开关、内存配置），在保证需求的前提下减小固件体积。
• 独立工程协同：如需扩展 UBOOT 或 UI 能力，在 UBOOT工程/、UI工程/ 中独立开发，并遵循与主工程约定的升级协议与内存布局。

Tests / 验证参考

本仓库为 SDK Release 工程，未包含独立测试框架；其验证与参考方式主要体现在：

• cpu/demo/ 外设示例：每个示例（hadc_demo.c、uart_demo.c、spi_demo.c、rtc_demo.c 等）即对应外设的最小可用验证程序，可直接编译运行确认硬件与驱动行为。
• 编译产物验证：make all 成功生成 cpu/cd09/tools/sdk.elf 是对代码改动的基本回归验证；make all VERBOSE=1 可展开详细编译过程排查告警。
• 烧录验证：通过 isd_download.exe 烧录后结合 UART 串口日志与 GPIO 调试波形验证运行期行为。

Related Links

• README.md（仓库权威说明）
• README-en.md（英文版说明）
• AC82 在线文档中心
• SDK 版本历史
• 芯片规格书 / 原理图硬件资料（doc/ 目录）
• 升级模块文档（OTA 双备份升级）
• 问题反馈（Gitee Issues）