项目概述与能力地图

本文档是 fw-AC630N_BT_SDK 的顶层概述页，介绍该 SDK 的定位、芯片平台、可构建应用工程、公共子系统与构建方式，并给出整个仓库的能力地图，帮助开发者在进入具体子系统之前建立全局认知。

Purpose and Scope

本页覆盖以下内容：

• SDK 的定位与组成（Jieli 在 Zephyr RTOS 之上的蓝牙固件源码补充包）
• AC630/1N 芯片家族的硬件能力与蓝牙协议能力
• 可构建的应用工程（SPP/LE、HID、Mesh）
• apps/common 公共子系统能力清单
• 构建系统（Makefile / Codeblock）与工具链获取方式
• 认证信息与开发阶段声明

以下主题属于本仓库中其他页面的范畴，本页仅提供入口指引，不展开细节：

• SPP/LE 透传应用的实现细节 → 参见 SPP_LE 应用 页面（apps/spp_and_le）
• HID 应用（键盘/鼠标/标准 HID profile）→ 参见 HID 应用 页面（apps/hid）
• 蓝牙 Mesh 组网实现 → 参见 Mesh 应用 页面（apps/mesh）
• 按键、电源管理、存储设备等公共组件的深度实现 → 参见对应 公共组件 页面

Overview

fw-AC630N_BT_SDK 是杰理科技（Jieli）为 AC630/1N 系列 蓝牙 SoC 提供的固件 SDK。根据 README.md 的说明，本仓库包含 Jieli 在开源项目 Zephyr RTOS 之上添加的源码，必须与 lib.a 以及使用相同命名约定的仓库组合，才能构建所提供的示例工程并使用附加的子系统与库。

SDK 的核心价值在于：在统一的 Zephyr RTOS 基础上，把经典蓝牙（Classic）与低功耗蓝牙（LE）双模协议栈能力、外设驱动与上层应用模板打包，使开发者可以快速产出蓝牙防丢器 / Beacon / 蓝牙 HID / 蓝牙透传等产品形态。芯片系列通过 Bluetooth SmartReady v5.0 认证（QDID 134104），协议栈支持 Classic 的 SDP/RFCOMM/SPP 以及 LE 的 ATT/SM/HOGP/Mesh。

需要特别注意的是（见 README.md 的 Disclaimer）：AC630/1N 系列属于预量产（pre-production）器件，蓝牙 Mesh 协议在 v0.2.0 中仅面向原型验证与评估，量产支持"即将到来"。

Architecture

flowchart TD
    subgraph sg_Apps["Application Layer (apps)"]
        SPP["SPP_LE 透传应用<br/>apps/spp_and_le"]
        HID["HID 应用<br/>apps/hid"]
        MESH["Mesh 应用<br/>apps/mesh"]
    end

    subgraph sg_Common["Common Subsystems (apps/common)"]
        KEY["key 按键驱动<br/>adkey / iokey / key_driver"]
        PWR["power_manage<br/>充电管理 app_charge"]
        STORAGE["storage_dev<br/>存储设备抽象"]
        CODESW["code_switch<br/>编码开关"]
        TPP["third_party_profile<br/>第三方 Profile<br/>custom_cfg / hid_user"]
        OMS["optical_mouse_sensor<br/>光电鼠标传感器 OMSensor_manage"]
        FILEOP["file_operate<br/>文件操作"]
        BTCOMM["bt_common.h<br/>蓝牙公共接口"]
    end

    subgraph sg_Base["SDK Base"]
        ZEPHYR["Zephyr RTOS"]
        LIB["lib.a 预编译库"]
        STACK["Bluetooth 5.0 双模协议栈<br/>Classic: SDP/RFCOMM/SPP<br/>LE: ATT/SM/HOGP/Mesh"]
    end

    subgraph sg_HW["Hardware (AC630/1N)"]
        CHIP["AC6311A / AC6313A<br/>AC6318A / AC6319A"]
    end

    SPP --> KEY
    SPP --> BTCOMM
    HID --> TPP
    HID --> OMS
    MESH --> BTCOMM
    KEY --> ZEPHYR
    PWR --> ZEPHYR
    STORAGE --> ZEPHYR
    CODESW --> ZEPHYR
    TPP --> STACK
    OMS --> ZEPHYR
    FILEOP --> STORAGE
    BTCOMM --> STACK
    ZEPHYR --> CHIP
    LIB --> ZEPHYR
    STACK --> CHIP

架构分层说明：

• 应用层（Application Layer）：仓库根目录 README 明确列出三个可构建工程——SPP/LE 透传、HID、Mesh。每个工程位于独立目录，通过 apps/app_cfg 选择目标后构建（见 README.md）。
• 公共子系统层（Common Subsystems）：apps/common 下按功能划分的共享代码，包括按键驱动、电源/充电管理、存储设备、编码开关、第三方 Profile、光电鼠标传感器、文件操作等，是应用工程的公共底座。目录结构来自仓库实际文件清单（ListFiles 结果）。
• SDK 底座（SDK Base）：Zephyr RTOS + Jieli 预编译 lib.a + Bluetooth 5.0 双模协议栈。README 明确说明本仓库必须与 lib.a 及同命名约定的仓库组合使用。
• 硬件层：AC6311A/AC6313A/AC6318A/AC6319A 四款 SoC，具体参数见下一节。

芯片家族与硬件能力

doc/README.md 给出了 AC630/1N 系列四款型号的完整规格（doc/README.md）：

关键设计要点：

• 同核同构：四款型号共享 32bit@120MHz 内核、48~56KB RAM 与 256KB Flash，差异主要在内置充电（6311A/6313A 支持 250mA 充电）与电源方案（LDO/DCDC 组合 vs 纯 LDO）以及工作电压范围。这意味着同一份 SDK 固件可跨型号复用，应用层只需按型号裁剪电源与充电配置。
• 双模协议栈：Classic 侧提供 SDP/RFCOMM/SPP（经典串口透传所需），LE 侧提供 ATT/SM/HOGP/Mesh（HID over GATT 与组网所需），三档 PHY 速率（1M/2M/Coded）覆盖了从 Beacon 广播到长距离 CodedPHY 的典型物联网场景。
• 功耗目标：Sleep@30µA、Systemoff@1µA 的指标决定了 SDK 的电源管理子系统（apps/common/power_manage）必须以低功耗为第一优先级设计。
• OTA 全支持：四款型号均支持 OTA 升级，仓库中对应 apps/common/include/update_tws.h 等升级相关公共接口。

可构建应用工程

根据 README.md，仓库提供三个可构建的蓝牙应用工程：

设计意图：三个工程分别对应三种主流产品形态，共用同一套 apps/common 底座，验证了"一套公共代码、多产品形态"的平台化思路。其中 HID 工程与 apps/common/third_party_profile/hid_user.c、apps/common/optical_mouse_sensor/ 存在直接关联，SPP/LE 与 Mesh 工程则依赖 apps/common/include/bt_common.h 提供的公共蓝牙接口。

公共子系统能力地图

apps/common 是 SDK 的公共代码底座。以下能力清单基于仓库实际文件结构（ListFiles 结果），目录与文件均真实存在；各子系统内部的实现细节由对应子页面深入展开。

按键输入（apps/common/key）

• key_driver.c：按键驱动核心，统一管理按键扫描与事件分发
• adkey.c：ADC 按键（通过模拟量区分多键）
• iokey.c：IO 按键（数字电平检测）

设计意图：将按键的"物理采样"与"业务消费"解耦，应用只需订阅按键事件，无需关心底层是 ADC 还是 IO 采样。

电源与充电（apps/common/power_manage）

• app_charge.h：充电管理接口，对应 AC6311A/AC6313A 的 250mA 内置充电能力

与芯片的 LDO/DCDC 电源方案、Sleep@30µA / Systemoff@1µA 低功耗指标直接配套。

存储设备（apps/common/storage_dev）

• storage_dev.h：存储设备抽象层，为文件操作与 OTA 提供统一的底层读写接口

文件操作（apps/common/file_operate）

• file_operate.h：文件级操作接口，依赖 storage_dev 抽象

编码开关（apps/common/code_switch）

• code_switch.c / include/code_switch.h：编码开关（旋转编码器）检测，常见于音量调节等交互场景

第三方 Profile（apps/common/third_party_profile）

• common/3th_profile_api.h：第三方 Profile 公共 API
• common/custom_cfg.c/.h：自定义配置（Profile 参数裁剪入口）
• jieli/hid_user.c：杰理 HID 用户态实现，HID 应用工程直接依赖

设计意图：通过 custom_cfg 提供配置入口，使 HID 等 Profile 的 GATT 服务/特征值可按产品需求裁剪，无需改动协议栈核心。

光电鼠标传感器（apps/common/optical_mouse_sensor）

• OMSensor_manage.c / include/OMSensor_manage.h：光电传感器管理
• hal3205/hal3205.c/.h：HAL3205 传感器芯片驱动

该子系统服务于 HID 蓝牙鼠标产品形态，将传感器位移数据转换为 HID 鼠标报告。

公共头文件（apps/common/include）

• bt_common.h：蓝牙公共接口声明，SPP/LE 与 Mesh 应用均依赖
• standard_hid.h：标准 HID 描述符/报告定义
• update_tws.h：TWS/升级相关接口

构建系统与工具链

SDK 支持两种构建方式（README.md）：

1. Codeblock 构建：进入工程目录，找到 .cbp 工程文件，双击构建。
2. Makefile 构建：在 apps/app_cfg 中选择目标工程，双击 make_prompt 打开构建环境，执行 make。

工具链（JL Toolchain）通过百度网盘获取（README.md），仓库根目录的 Makefile、rule.mk、make_prompt.bat 共同构成构建基础设施：rule.mk 承载编译规则，make_prompt.bat 负责拉起带工具链 PATH 的构建终端。

设计意图：双构建通道降低了入门门槛（Codeblock 适合图形化调试），同时保留 Makefile 通道以支持 CI/脚本化批量构建。

核心流程

构建流程

开发者从拿到 SDK 到产出固件，遵循以下流程（依据 README.md 的 Build 章节绘制）：

flowchart TD
    Start([开始]) --> Env["获取 JL Toolchain<br/>并配置构建环境"]
    Env --> Select{"选择构建方式"}
    Select -->|"Codeblock"| Cbp["进入工程目录<br/>双击 .cbp 工程文件"]
    Cbp --> Build1["构建固件"]
    Select -->|"Makefile"| Cfg["在 apps/app_cfg<br/>选择目标工程"]
    Cfg --> Prompt["双击 make_prompt<br/>打开构建终端"]
    Prompt --> Make["执行 make"]
    Make --> Build1
    Build1 --> Out["生成固件产物"]
    Out --> Flash["烧录至 AC630/1N 开发板"]
    Flash --> Test["功能验证<br/>SPP透传 / HID / Mesh"]
    Test --> End([结束])

要点：目标工程选择在构建之前完成（apps/app_cfg 或直接进入对应工程目录），两个通道殊途同归，最终都编译出面向 AC630/1N 系列的可烧录固件。

典型产品开发路径

flowchart LR
    A["选定产品形态<br/>防丢/Beacon/HID/透传"] --> B["选择对应应用工程<br/>spp_and_le / hid / mesh"]
    B --> C["裁剪公共子系统配置<br/>custom_cfg / power_manage / key"]
    C --> D["构建与烧录"]
    D --> E["低功耗与 OTA 验证"]

该路径解释了仓库"应用工程 + 公共子系统"的组织动机：产品差异集中在应用层，平台能力沉淀在公共层，从而最大化复用。

使用示例

以下示例均提取自仓库 README 原文，展示如何选择并构建工程。

示例 1：查看可构建工程列表

README 的 Build 章节明确列出了三个可构建工程（README.md）：

Select a project to build. The following folders contains buildable projects:

* APP_Bluetooth : [SPP_LE](https://gitee.com/Jieli-Tech/fw-AC630N_BT_SDK/blob/master/apps/spp_and_le)

* APP_Bluetooth : [HID](https://gitee.com/Jieli-Tech/fw-AC630N_BT_SDK/blob/master/apps/hid)

* APP_Bluetooth : [Mesh](https://gitee.com/Jieli-Tech/fw-AC630N_BT_SDK/blob/master/apps/mesh)

Source: README.md

示例 2：Makefile 构建流程

README 给出的 Makefile 构建步骤（README.md）：

# 1. 在 apps/app_cfg 中选择要构建的目标工程
# 2. 双击 make_prompt 打开构建终端（仓库根目录）
# 3. 执行 make
make

Source: README.md

示例 3：工具链获取

README 说明工具链获取方式（README.md）：

Toolchain
------------

how to get the `JL Toolchain` and setup the build enviroment,see below

* Lastest：(https://pan.baidu.com/s/1f5pK7ZaBNnvbflD-7R22zA) 提取码: ukgx

Source: README.md

说明：本页为项目概述页，未深入读取 apps/* 内部源码，因此此处仅提供仓库级（README）代码示例；应用与子系统内部的具体代码示例，请参见对应子页面（SPP_LE / HID / Mesh / 公共组件）。

配置选项

SDK 层面的关键"配置"体现在目标工程选择与公共组件裁剪两个层面。基于 README 与目录结构可确认的选项如下：

失败模式、边界情况与并发

依据 README 的 Disclaimer 与文档公开信息，本 SDK 存在以下需要开发者注意的边界：

• 预量产器件：AC630/1N 系列属于 pre-production 器件（README.md），量产前需关注芯片勘误与固件更新。
• Mesh 支持阶段：蓝牙 Mesh 协议在 v0.2.0 中仅用于原型验证与评估，不支持直接用于量产产品；计划中的正式支持尚未发布。
• 依赖完整性：本仓库是"源码补充包"，必须与 lib.a 及同命名约定的仓库组合才能构建。单独拉取本仓库将无法完成编译，这是最常见的构建失败根因。
• 型号差异：内置充电与工作电压范围在 6311A/6313A 与 6318A/6319A 之间存在差异，电源管理配置选错型号会导致充电/掉电行为异常。
• 并发说明：本页未读取应用内部源码，按键、协议栈回调等并发模型细节由对应子页面说明；从目录结构看，按键驱动与 Profile 回调（hid_user.c、3th_profile_api.h）是典型的并发/中断上下文交汇点，实现时需注意临界区保护。

性能与运维考虑

芯片公开指标（doc/README.md）决定了运维与功耗设计的目标值：

• 计算能力：32bit@120MHz，48~56KB RAM，256KB Flash——资源有限，应用层需避免大缓冲与高频轮询。
• 功耗目标：Sleep@30µA、Systemoff@1µA，产品级功耗验证需围绕低功耗模式展开。
• OTA：全系列支持 OTA，升级链路相关的公共接口位于 apps/common/include/update_tws.h。
• 开发板：可通过 README 中的淘宝入口申请 EV Board（README.md）。

扩展点

SDK 面向产品定制的扩展入口（基于目录结构识别，具体接口签名见子页面）：

• 新应用工程：参照 apps/spp_and_le / apps/hid / apps/mesh 的组织方式新建工程，并在 apps/app_cfg 中登记目标。
• 自定义 Profile：通过 apps/common/third_party_profile/common/custom_cfg.c/.h 与 3th_profile_api.h 扩展 GATT 服务。
• 新外设驱动：参照 apps/common/optical_mouse_sensor/hal3205 的模式，在 apps/common 下新增设备驱动子目录并接入管理模块。
• 按键策略：在 apps/common/key/key_driver.c 的驱动框架上扩展新的按键类型（现有 adkey/iokey 两种）。

测试

仓库根目录未发现独立的自动化测试工程（根文件仅含 LICENSE、Makefile、README.md、make_prompt.bat、rule.mk）。固件验证主要依赖：

• 各应用工程的示例固件烧录到 EV Board 进行真机验证（SPP 透传回环、HID 上报、Mesh 组网）
• 蓝牙认证测试：Bluetooth 5.0 声明与 QDID 134104（README.md）对应的认证流程

相关链接

• README.md（仓库总览）
• doc/README.md（芯片选型表）
• SDK 发布信息 PDF
• SDK 介绍文档 PDF
• 应用工程入口：apps/spp_and_le（SPP/LE 透传）、apps/hid（HID）、apps/mesh（Mesh）
• 公共子系统入口：apps/common/key、apps/common/power_manage、apps/common/storage_dev、apps/common/third_party_profile、apps/common/optical_mouse_sensor
• 相关子页面：SPP_LE 应用 / HID 应用 / Mesh 应用 / 公共组件（本仓库 Wiki 中的对应页面）