项目概述与芯片平台

fw-AC82N_GP-MCU_SDK 是杰理科技（Jieli）为 AC82N 系列芯片提供的通用 MCU（GP MCU）SDK 固件开发包。本页概述该 SDK 的整体定位、支持的芯片平台（cd09）、工程结构、核心外设能力以及从环境搭建到编译烧录的完整开发流程，是整个仓库文档体系的总览入口。

Purpose and Scope

本页面向刚接触 AC82N 平台的开发者与集成工程师，回答以下问题：

这个 SDK 是什么？适用于哪些产品和应用场景？
它支持哪些芯片型号？芯片平台（cd09）具备哪些外设能力？
仓库的目录结构如何组织？各目录的职责边界是什么？
如何搭建开发环境、编译固件并烧录到目标板？

本页不深入的内容（留给对应的专题页面）：

单个外设（HADC、SARADC、UART、SPI、IIC、MCPWM、RTC 等）的具体驱动实现与 API 细节，请参见各外设示例页面（如 cpu/demo/hadc_demo.c 对应的"高精度 ADC"页面）。
UI 工程、UBOOT 工程的独立编译细节，参见对应的工程页面。
固件升级（OTA）机制的内部实现，参见"固件升级"页面。

Overview

项目定位

fw-AC82N_GP-MCU_SDK 是杰理科技为 AC82N 系列芯片提供的通用 MCU SDK。AC82N 系列定位为无蓝牙（non-Bluetooth）功能的通用 MCU SoC，主要面向以下两类应用场景：

应用类型	典型产品
高精度测量	体脂秤、传感器采集、精密仪器仪表、血压计、耳温枪
低功耗产品	电池供电设备、便携式仪器、RTC 闹钟唤醒应用

选择"无蓝牙、纯 MCU"定位的核心理由是：这类产品不需要无线连接，但对测量精度、静态功耗和外设丰富度有很高要求。将无线射频模块从 SoC 中剥离，可以在同等功耗预算下把资源集中在 ADC 精度与低功耗设计上。

核心特性

24 位高精度 HADC：有效精度最高可达 19 bit，面向体脂秤、血压计等精密测量场景
高速 SARADC：采样率可达 1 Msps，面向传感器高速采集
超低功耗处理器：适用于电池供电的便携场景
低功耗 RTC：支持闹钟和唤醒功能，支撑"休眠-定时唤醒"类应用
丰富的片上外设：HADC、SARADC、IIC、SPI、MCPWM、UART、USB、触摸按键等
支持 APA 播报：可驱动音频播报，用于语音提示类产品

本仓库包含 SDK Release 版本代码及示例工程，需配合对应命名规则的预编译库文件（lib.a）进行编译。SDK 源码与库文件分离，是杰理 SDK 的一贯设计：应用层代码开源可读，而底层驱动、协议栈以静态库形式提供。

术语表

术语	含义
GP MCU	General Purpose MCU，通用单片机应用
HADC	High-resolution ADC，高精度模数转换器（24 位）
SARADC	Successive Approximation Register ADC，逐次逼近型模数转换器（1 Msps）
MCPWM	Motor Control PWM / Multi-channel PWM，电机控制或多通道 PWM
APA	Audio Playback Announcement，语音播报
cd09	芯片平台代号，对应 AC822B/AC823B/AC825A/AC826B 系列
lib.a	预编译静态库，SDK 的二进制发布形态

Architecture

SDK 总体架构

SDK 采用经典的分层嵌入式软件架构，从顶层应用到最底层硬件自顶向下划分为四层：

flowchart TD
    subgraph sg_App["应用层 apps/"]
        AppMain["apps/gp_mcu<br/>GP MCU 主应用入口"]
        Common["apps/common<br/>公共模块：AT / battery / cJSON / UI / update"]
    end

    subgraph sg_Demo["示例层 cpu/demo/"]
        HADCDemo["hadc_demo.c / gpadc_demo.c"]
        UartDemo["uart_demo.c / spi_demo.c / iic_demo.c"]
        McpwmDemo["mcpwm_demo.c / rtc_demo.c / gptimer_demo.c"]
        OtherDemo["segment_code_lcd / sin_generator / norflash / voice"]
    end

    subgraph sg_Platform["芯片平台层 cpu/cd09/"]
        LibA["liba/ 预编译库 (.a)"]
        HADCDrv["hadc/ 高精度 ADC 驱动"]
        Power["power/ 电源管理"]
        SegLcd["segment_code_lcd/ 段码 LCD"]
        Tools["tools/ 链接与下载脚本"]
    end

    subgraph sg_Interface["接口层 include_lib/"]
        DriverHdr["driver/ 驱动头文件"]
        SysHdr["system/ 系统头文件"]
        UiHdr["ui_platform/ UI 平台头文件"]
        UpdateHdr["update/ 升级模块头文件"]
    end

    subgraph sg_Build["构建体系"]
        Makefile["Makefile 统一编译入口"]
        Cbp["AC82N_gp_mcu.cbp Code::Blocks 工程"]
        Vscode[".vscode/tasks.json"]
    end

    AppMain --> Common
    AppMain --> HADCDemo
    AppMain --> LibA
    HADCDemo --> DriverHdr
    UartDemo --> DriverHdr
    McpwmDemo --> DriverHdr
    OtherDemo --> DriverHdr
    LibA --> HADCDrv
    LibA --> Power
    LibA --> SegLcd
    DriverHdr --> LibA
    SysHdr --> LibA
    Makefile --> LibA
    Cbp --> Makefile
    Vscode --> Makefile

各层职责说明：

应用层（apps/）：apps/gp_mcu/ 是 GP MCU 主应用入口，包含应用主函数与配置入口；apps/common/ 提供跨工程共享的公共模块（AT 指令、电池检测、cJSON、调试、解码、外设驱动、EEPROM、字库、LCD、UI、固件升级等）。
示例层（cpu/demo/）：提供可直接参考的外设示例代码，是开发者学习每个外设用法的第一手资料。
芯片平台层（cpu/cd09/）：cd09 平台的驱动与库文件，包括 HADC 驱动、预编译静态库（liba/）、电源管理（power/）、段码 LCD 驱动（segment_code_lcd/）以及链接/下载脚本（tools/）。
接口层（include_lib/）：SDK 对外暴露的头文件集合，按 driver / system / ui_platform / update 分类，是应用层与预编译库之间的契约。
构建体系：顶层 Makefile 是统一编译入口；AC82N_gp_mcu.cbp 供 Windows 下 Code::Blocks 使用；.vscode/tasks.json 支持 VS Code 一键编译。

芯片平台与工程的关系

flowchart LR
    subgraph sg_SDK["fw-AC82N_GP-MCU_SDK"]
        Platform["cd09 芯片平台<br/>AC822B / AC823B / AC825A / AC826B"]
        App["GP MCU 应用工程<br/>apps/gp_mcu"]
        Libs["预编译库<br/>cpu/cd09/liba/*.a"]
        Elf["编译产物<br/>cpu/cd09/tools/sdk.elf"]
    end

    UsbTool["USB 升级工具<br/>isd_download.exe"]
    Board["目标开发板<br/>AC82N 系列"]

    Platform --> App
    App --> Libs
    Libs --> Elf
    Elf --> UsbTool
    UsbTool --> Board

当前 Release 版本仅包含 cd09 一个芯片平台。这一设计意味着：SDK 顶层代码（应用、公共模块、示例）与具体芯片平台解耦，后续如扩展新平台，只需在 cpu/ 下新增对应平台目录并提供相同的 liba/、tools/ 结构即可。

芯片平台：cd09

芯片型号与选型

SDK 当前支持的芯片平台与型号如下：

芯片平台	芯片型号	应用领域
cd09	AC822B / AC823B / AC825A / AC826B	高精度测量 / 智能控制 / 低功耗产品

芯片型号 / 规格书 / 原理图资料请查阅：doc/原理图&硬件资料

同一平台下多个型号（AC822B/823B/825A/826B）共享同一套 SDK 代码与预编译库，型号差异主要体现在封装、引脚数和资源规格上，应用层代码无需区分。这降低了产品线扩展的维护成本——同一固件工程可通过板级配置适配不同型号。

片上外设矩阵

cd09 平台面向"测量 + 低功耗 + 人机交互"三大需求设计，片上外设可分为四类：

类别	外设	用途
模拟采集	24 位 HADC、1 Msps SARADC	精密测量、传感器采集、电池电压检测
通信接口	IIC、SPI、UART、USB	与传感器、主机或外设芯片通信
控制与定时	MCPWM、GPTimer、触摸按键	电机/负载控制、通用定时、触摸人机交互
低功耗与显示	低功耗 RTC、段码 LCD 驱动、APA 播报	闹钟唤醒、段码屏显示、语音提示

从 cpu/cd09/ 的目录划分可以印证平台能力边界：hadc/（高精度 ADC）、power/（电源管理）、segment_code_lcd/（段码 LCD）是 cd09 平台最核心的自研驱动模块，其余外设通过预编译库提供。

平台目录结构

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

设计意图：平台层（cpu/）与库文件（liba/）的分离，使应用开发者无需关心芯片寄存器级细节，只需通过 include_lib/ 中的头文件调用标准 API；同时 iic_soft.c（软件模拟 IIC）与 iic_api.c（硬件 IIC）并存，允许开发者按成本与引脚约束在软/硬件 IIC 之间切换。

SDK 工程结构

顶层布局

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 相关代码与库文件
├── include_lib/                   # 头文件（driver / system / ui_platform / 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）

关键目录职责速查

目录	作用
`apps/gp_mcu/`	GP MCU 主应用入口：应用主函数、配置入口
`cpu/demo/`	外设示例：可直接参考的 HADC/UART/SPI/IIC/MCPWM/RTC 等示例代码
`cpu/*/liba/`	预编译库：`*.a` 静态库文件
`cpu/*/tools/`	烧录/链接工具：下载脚本、链接脚本
`apps/common/`	公共模块：AT 指令、电池检测、USB、UI 等模块
`include_lib/driver/`	驱动头文件（cpu / device）
`include_lib/system/`	系统头文件（device / fs / generic）
`include_lib/ui_platform/`	UI 平台头文件
`include_lib/update/`	升级模块头文件
`tools/make_prompt.bat`	Windows 下预配置的编译命令行环境入口

两个独立编译的工程目录（UBOOT工程/、UI工程/）需要注意：它们不属于主 Makefile 的应用编译流程，需单独构建后再与主固件配合烧录，这是杰理 SDK 多工程协作的常见形态。

GP MCU 应用入口

SDK 包含一个统一的 GP MCU 应用工程，入口位于：

sdk/
├── apps/gp_mcu/          # GP MCU 主应用入口
├── cpu/demo/             # 外设示例代码
│   ├── hadc_demo.c       # 高精度 ADC 示例
│   ├── gpadc_demo.c      # 通用 ADC 示例
│   ├── uart_demo.c       # UART 示例
│   ├── spi_demo.c        # SPI 示例
│   ├── iic_demo.c        # IIC 示例
│   ├── mcpwm_demo.c      # MCPWM 示例
│   ├── rtc_demo.c        # RTC 示例
│   ├── gptimer_demo.c    # 通用定时器示例
│   └── ...
└── AC82N_gp_mcu.cbp      # Code::Blocks 工程文件

Source: README.md

这一结构体现了 SDK 的"一个主应用 + 一组外设示例"范式：apps/gp_mcu/ 是实际产品固件的起点，cpu/demo/ 中的示例代码则按外设组织，开发者将所需示例中的初始化与采集逻辑移植到主应用中即可完成功能集成。

开发流程（Core Flow）

从拿到仓库到固件上板，完整的开发链路如下：

flowchart TD
    Start([开始]) --> Clone["克隆仓库<br/>git clone AC82N.git"]
    Clone --> Env{"操作系统?"}
    Env -->|"Windows"| Cb["安装杰理编译工具链<br/>使用 Code::Blocks 打开 .cbp"]
    Env -->|"Linux"| Lx["安装工具链到 /opt/jieli<br/>验证 clang 可用"]
    Env -->|"macOS"| Mac["自行配置交叉编译工具链"]
    Cb --> Build1["Build → Build (Ctrl+F9)"]
    Lx --> Build2["make all -j`nproc`"]
    Mac --> Build2
    Build1 --> Elf["生成 cpu/cd09/tools/sdk.elf"]
    Build2 --> Elf
    Elf --> Flash["USB 升级工具 isd_download.exe<br/>选择固件并烧录"]
    Flash --> Boot{"进入编程模式?"}
    Boot -->|"否"| Retry["按住烧录按键 + 复位/重新上电"]
    Retry --> Flash
    Boot -->|"是"| Done([固件运行 / 调试])
    Done --> Debug["UART 日志 / GPIO 波形调试"]

关键节点说明：

克隆仓库：git clone https://gitee.com/Jieli-Tech/AC82N.git 后进入 sdk 目录。
环境准备：必须安装杰理编译工具链（clang 交叉编译器，pi32 架构）。Linux 下解压到 /opt/jieli 并确保 /opt/jieli/pi32/bin/clang 存在；Windows 推荐 Code::Blocks IDE。
编译：Windows 用户直接使用 Code::Blocks 构建；Linux/macOS 用户在 SDK 根目录执行 make all。编译完成后生成 cpu/cd09/tools/sdk.elf，烧录脚本会自动调用。
烧录：使用 USB 升级工具（isd_download.exe）选择固件下载。首次烧录需按住开发板烧录按键并复位进入编程模式。
调试：通过 UART 串口日志与 GPIO 调试波形定位问题。

使用示例

示例一：验证编译工具链

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

Source: README.md

工具链安装是否成功以 clang 可执行为准；若提示 clang: command not found，说明未安装杰理编译工具链或环境变量未配置（见下文"常见编译错误"表）。

示例二：Linux/macOS 命令行编译

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

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

Source: README.md

tools/make_prompt.bat 是 Windows 下预配置的编译环境入口——它已设置好所有环境变量和 make 的路径，解决 Windows 命令行无 make 命令的问题。-j 参数启用并行编译以缩短构建时间。

示例三：Linux 链接阶段文件描述符调优

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

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

Source: README.md

链接阶段需要同时打开大量目标文件与库文件，Linux 默认的 ulimit -n（通常 1024）会导致 Too many open files 错误，编译前需提高限制。

示例四：编译命令速查

目标	芯片	说明	命令
全部	cd09	编译并下载	`make all`
清理	cd09	清理编译产物	`make clean`
详细编译	cd09	显示详细编译过程	`make all VERBOSE=1`

Source: README.md

VERBOSE=1 用于排查编译问题时输出完整命令行；make clean 清理产物后重新全量编译，是解决增量编译异常的常用手段。

示例五：GP MCU 应用定位

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

Source: README.md

克隆后 SDK 主工程位于 sdk/ 子目录，所有编译、配置操作均在该目录下进行。

Configuration Options

SDK 的配置分为板级配置与功能裁剪两类，均在应用/平台配置文件中完成：

配置项	类别	说明	参考位置
引脚映射	板级配置	UART / SPI / IIC / GPIO 等外设的引脚分配	`apps/gp_mcu/` 板级配置
外设使能	板级配置	开启或关闭特定外设模块	`apps/gp_mcu/` 板级配置
时钟配置	板级配置	CPU 频率、外设时钟源	`apps/gp_mcu/` 板级配置
功能裁剪	功能裁剪	通过配置文件灵活裁剪 SDK 功能，减小固件体积，调整各模块功能开关和内存配置	各模块配置文件

设计意图：板级配置（引脚/外设/时钟）与应用逻辑分离，使同一套应用代码可以快速适配不同型号（AC822B/823B/825A/826B）或不同硬件板卡；功能裁剪则通过编译期配置开关实现，未启用的模块不参与链接，直接减小固件体积——这对低容量 Flash 的低成本产品至关重要。

失败模式、边界情况与常见问题

常见编译错误

错误提示	原因	解决方法
`clang: command not found`	未安装杰理编译工具链，或环境变量未配置	下载并安装工具链；Linux 解压到 `/opt/jieli`
`Too many open files`	Linux 文件描述符限制过低，链接阶段打开文件过多	执行 `ulimit -n 8096` 增加限制
`cannot find -lxxx`	缺少对应的 `.a` 库文件	检查 `cpu/cd09/liba/` 目录，确认库文件与芯片平台匹配
`make: command not found`	Windows 环境未配置 make 路径	使用 `tools/make_prompt.bat` 打开编译命令环境

边界情况与注意事项

库文件与源码必须配套：SDK 是"源码 + 预编译库（lib.a）"的发布形态，库文件必须与 SDK 版本、芯片平台（cd09）匹配。混用不同版本的库会导致链接错误或运行时行为异常。
多工程独立编译：UBOOT工程/ 与 UI工程/ 需独立编译，主 Makefile 不会自动构建它们；若产品用到 UI 或 UBOOT 定制，需分别构建后再统一烧录。
首次烧录须进入编程模式：按住开发板烧录按键后复位/重新上电，否则 USB 升级工具无法识别目标板。
macOS 支持受限：macOS 下需自行配置交叉编译工具链，官方不提供开箱即用的环境，建议 Windows/Linux 开发。

性能与运维注意事项

并行编译：使用 make all -j（如 -j4、-jnproc``）可显著缩短编译时间；Windows 下同样适用。
固件体积控制：通过配置文件的"功能裁剪"关闭不需要的模块（AT 指令、UI、升级等），未启用模块不参与链接，可减小固件体积，降低 Flash 占用与烧录时间。
产物位置：编译产物 cpu/cd09/tools/sdk.elf 固定生成，烧录脚本自动引用，不要手工移动或改名，否则烧录脚本会失效。
量产烧录：量产/裸片烧写使用独立的生产烧写工具（1拖2），与开发阶段的 USB 升级工具分开，由代理商渠道提供。

扩展点

SDK 的设计为二次开发预留了清晰的扩展路径：

新增产品功能：在 apps/gp_mcu/ 主应用中添加业务逻辑，复用 apps/common/ 公共模块（cJSON、电池检测、EEPROM、LCD、UI 等）。
新增外设驱动：参考 cpu/demo/ 中对应外设的示例代码，按照现有驱动框架在应用中注册新驱动文件，并通过板级配置完成引脚映射。
新建工程：基于现有 apps/gp_mcu/ 和 cpu/demo/ 示例修改，配置对应引脚和外设即可，无需从零搭建工程骨架。
适配新板卡：只修改板级配置（引脚映射、外设使能、时钟），应用层代码无需改动——这是应用/平台分层带来的直接收益。
平台级扩展：在 cpu/ 下新增平台目录，提供与 cd09 相同的 liba/、tools/、驱动目录结构，顶层应用与公共模块即可复用。

新增驱动时务必遵循"示例先行"的实践：先在 cpu/demo/ 中验证外设行为，再集成进 apps/gp_mcu/，可显著降低调试难度。

项目概述与芯片平台

Purpose and Scope

Overview

项目定位

核心特性

术语表

Architecture

SDK 总体架构

芯片平台与工程的关系

芯片平台：cd09

芯片型号与选型

片上外设矩阵

平台目录结构

SDK 工程结构

顶层布局

关键目录职责速查

GP MCU 应用入口

开发流程（Core Flow）

使用示例

示例一：验证编译工具链

示例二：Linux/macOS 命令行编译

示例三：Linux 链接阶段文件描述符调优

示例四：编译命令速查

示例五：GP MCU 应用定位

Configuration Options

失败模式、边界情况与常见问题

常见编译错误

边界情况与注意事项

性能与运维注意事项

扩展点

仓库内资源

外部官方资源

相关 Wiki 页面

社区与支持