SDK 文档与在线资源

本页汇总 fw-AW33N_BLE_SDK 仓库内外的全套 SDK 文档与在线资源，包括仓库内 doc/ 目录的离线资料、杰理在线文档中心、开发工具、社区支持与认证信息，帮助开发者快速定位所需的文档与工具入口。

Purpose and Scope

本页面向使用 AW33N 系列芯片进行 BLE 开发的工程师，系统性地梳理 SDK 文档与在线资源 的完整生态：

• 仓库内离线文档：doc/ 目录下的用户手册、硬件设计指南、AT 命令说明、SDK 发布版本信息、原理图、开发板资料、BLE Profile 工具等。
• 在线文档中心：杰理官方文档站点 doc.zh-jieli.com/AW33（文档中心、版本历史、模块开发文档、SDK 架构文档）。
• 开发工具资源：编译工具链、USB 升级工具、生产烧写工具、无线测试盒的获取方式与使用文档入口。
• 社区与支持：钉钉技术交流群、Gitee Issues 反馈渠道、官方店铺。
• 认证信息：蓝牙 SIG 认证的 QDID 与查询链接。

以下主题属于其他页面的范畴，本页仅提供入口指引而不展开：环境搭建与编译细节（见"编译指南"相关页面）、工程结构与应用选择（见"工程结构"相关页面）、烧录与 OTA 升级流程（见"烧录与升级"相关页面）、功能裁剪与板级配置（见"配置说明"相关页面）。

概述

fw-AW33N_BLE_SDK 是杰理科技为 AW33N 系列芯片提供的通用蓝牙 SDK 固件开发包，基于裸机操作系统，提供完整的 BLE 协议栈与丰富的应用示例（BLE 透传/数传、HID 人机交互等）。该 SDK 的文档体系分为三个层次，形成"仓库内快速索引 → 本地离线资料 → 在线全量文档"的互补结构：

1. 仓库根目录 README.md：作为第一入口，包含概述、支持芯片、环境搭建、快速开始、工程结构、编译指南、烧录升级、配置说明、常见问题、社区支持与认证信息等一站式速查内容，并在顶部提供了文档中心、版本历史、问题反馈的直达链接。
2. 仓库内 doc/ 目录：存放随 SDK 发布的离线 PDF 资料、原理图、开发板资料、选型表与辅助工具压缩包，适合在无法访问外网或需要硬件细节时查阅。
3. 在线文档中心 doc.zh-jieli.com/AW33：官方维护的全量文档站点，按 zh-cn/master 版本分支组织，包含 SDK 架构说明、各模块（transfer、hid、OTA 等）开发文档、版本发布记录以及各类工具的在线手册。

理解这套文档体系的价值在于：README 解决"怎么上手"，doc/ 解决"硬件与协议细节"，在线文档中心解决"模块级深入开发"，三者结合覆盖从选型、设计、开发到量产的完整链路。

架构

下图展示了 SDK 文档与在线资源的整体生态结构：

flowchart TD
    subgraph sg_Repo["仓库 fw-AW33N_BLE_SDK (master)"]
        README["README.md<br/>(中文主入口)"]
        README_EN["README-en.md<br/>(英文版)"]
        subgraph sg_Doc["doc/ 离线资料目录"]
            D1["AW33N用户手册V1.0.pdf"]
            D2["AW33N硬件设计指南V1.0.pdf"]
            D3["AT命令说明/"]
            D4["SDK介绍/开发文档.rar"]
            D5["硬件资料/原理图/"]
            D6["硬件资料/开发板/"]
            D7["ble_profile_tools/"]
        end
    end

    subgraph sg_Online["杰理在线文档中心"]
        DOC_INDEX["文档中心首页<br/>doc.zh-jieli.com/AW33"]
        DOC_VERSION["SDK 版本历史"]
        DOC_ARCH["SDK 架构文档"]
        DOC_MODULE["模块文档<br/>(transfer / hid / OTA ...)"]
    end

    subgraph sg_Tools["开发工具资源"]
        TOOL_CHAIN["编译工具链 (clang)"]
        TOOL_UPGRADE["USB 升级工具 (isd_download)"]
        TOOL_PROD["生产烧写工具"]
        TOOL_TESTBOX["无线测试盒"]
    end

    subgraph sg_Support["社区与支持"]
        SUPPORT_DD["钉钉群 90400000565"]
        SUPPORT_ISSUES["Gitee Issues"]
        SUPPORT_SHOP["官方淘宝店铺"]
    end

    subgraph sg_Cert["认证信息"]
        CERT["蓝牙 SIG QDID DN:Q332415<br/>(Core v5.4 / v6.0)"]
    end

    README -->|"顶部导航"| DOC_INDEX
    README -->|"本地下载"| sg_Doc
    README -->|"申请/文档链接"| sg_Tools
    README -->|"问题反馈"| SUPPORT_ISSUES
    README_EN --> DOC_INDEX
    DOC_INDEX --> DOC_VERSION
    DOC_INDEX --> DOC_ARCH
    DOC_INDEX --> DOC_MODULE
    README --> CERT
    README --> SUPPORT_DD

架构说明：

• README.md 是唯一的枢纽节点：所有离线文档、在线文档、工具、社区与认证入口都由它串联。它既包含自包含的速查内容（编译命令、工程结构、FAQ），又以表格形式外链到各资源。
• doc/ 目录与在线文档中心互补：离线 PDF 侧重硬件（原理图、设计指南、选型表）与发布版本信息；在线文档中心侧重模块级软件开发的持续更新内容。
• 工具资源按用途划分：编译工具链面向构建阶段，USB 升级工具/生产烧写工具/无线测试盒面向烧录与量产阶段，三者分别对应 README「环境搭建」与「烧录与升级」章节的表格入口。
• 认证与社区是商业落地的保障：SIG QDID 用于合规声明，钉钉群与 Gitee Issues 提供研发支持闭环。

仓库内文档（doc/ 目录）

doc/ 目录随 SDK 版本发布同步更新，是开发者离线获取硬件与协议级资料的权威来源。其内容结构如下：

设计意图

• 按硬件型号拆分原理图：原理图按芯片型号（AW332A、AW333A、AW336A、AW336A0、AW338A）分别存放，并额外提供 Findmy 与 无线鼠标 等方案级参考图，使不同产品线的硬件工程师只需查阅对应文件，避免混淆。
• 配套选型表：AW33N选型表.xlsx 与原理图目录同级放置，将"选型 → 参考设计"两步衔接起来。
• 工具随文档分发：make_gatt_services 这类 BLE Profile 生成工具以压缩包形式随文档发布，保证工具版本与 SDK 版本的一致性（当前为 v1.2.2）。

关键文件参考

• 在线文档中心对 doc/ 目录的引用见 README「资源链接」表格：README.md，其中明确标注了"本地下载"入口指向 ./doc。
• AT 命令示例文本 at_cmd_sample.txt 位于 doc/AT命令说明/at_cmd_sample.txt，供 AT 模组开发者直接对照使用。

在线文档中心

杰理官方文档站点是 SDK 文档体系的全量在线版本，地址为 https://doc.zh-jieli.com/AW33/zh-cn/master/index.html。README 顶部导航条与「资源链接」表格均提供了直达入口：

这些链接均来自 README 各章节，例如 HID 应用的参考文档入口定义在应用选择指南中：

| **参考文档** | [HID 开发文档](https://doc.zh-jieli.com/AW33/zh-cn/master/module_demo/hid/index.html) |

Source: README.md

在线文档的版本管理方式

在线文档中心按 zh-cn/master 分支组织，与仓库 master 分支保持同步；other/version/index.html 专门维护版本历史，README 顶部徽章（GitHub Tag 徽章）同时展示当前最新 tag。这种"仓库分支 = 文档分支"的设计保证了开发者查阅的文档永远与所克隆的代码版本匹配。

开发工具资源

工具资源按开发阶段分为三类，均由 README「环境搭建」章节统一管理：

设计意图：研发阶段与量产阶段使用不同的烧录工具（isd_download.exe 面向单板调试，生产烧写工具面向批量裸片），工具文档统一托管在 doc.zh-jieli.com/Tools 之下，与 SDK 文档中心同源管理，避免文档分散。

社区与支持

技术交流

资源链接速查

Source: README.md

问题反馈闭环

README「调试技巧」一节明确建议：遇到编译、运行问题先查 Gitee Issues FAQ，再通过钉钉群与官方研发沟通。Issue 渠道与仓库同源托管于 Gitee，问题记录可追溯、可检索，是社区支持的主通道。

认证信息

SDK 内置蓝牙协议栈已通过蓝牙 SIG 认证，可直接用于量产合规申报：

README 概述章节与认证章节对 Core v5.4 / v6.0 的 QDID 记录一致（DN:Q332415），对应蓝牙资质页面 qualification.bluetooth.com/ListingDetails/260833。设计意图：将 QDID 直接写入 README，使客户在合规评审阶段无需向厂商索取认证材料即可自查。

核心使用流程

从文档体系出发的典型开发路径如下：

sequenceDiagram
    participant Dev as 开发者
    participant README as README.md
    participant Doc as doc/ 离线资料
    participant Online as 在线文档中心
    participant Tools as 工具资源
    participant Issue as Gitee Issues

    Dev->>README: 1. 阅读概述/支持芯片，确认 AW33N 适用
    Dev->>README: 2. 按"快速开始"克隆仓库、选择工程
    Dev->>Doc: 3. 查阅用户手册/硬件设计指南/原理图
    Dev->>Online: 4. 查阅模块文档(transfer/hid/OTA)与版本历史
    Dev->>Tools: 5. 安装编译工具链并编译
    Dev->>Tools: 6. 使用 USB 升级工具烧录固件
    Dev->>README: 7. 对照 FAQ 排查问题
    Dev->>Issue: 8. 未解决则提交 Issue / 加入钉钉群

流程要点：

• 步骤 1-2 完全由 README 自包含信息驱动（芯片平台表、apps/demo/transfer 与 apps/demo/hid 目录），无需先访问外部文档即可开始。
• 步骤 3-4 是"离线硬件资料 + 在线软件文档"的双轨查阅：硬件细节看 doc/ 原理图与设计指南，软件模块开发看在线文档中心。
• 步骤 5-6 的工具安装与烧录细节在 README「环境搭建」「烧录与升级」章节给出，工具本身通过外部链接申请或下载。
• 步骤 7-8 构成支持闭环：FAQ 内置了最常见错误的解决方案，兜底渠道是 Gitee Issues 与钉钉群。

使用示例

以下示例均提取自 README，展示如何借助文档资源快速进入开发状态。

克隆仓库并选择工程

git clone https://gitee.com/Jieli-Tech/fw-AW33N_BLE_SDK.git

cd fw-AW33N_BLE_SDK

SDK 根目录
├── apps/demo/transfer    # BLE 透传/数传等应用
└── apps/demo/hid/        # HID 人机交互设备等应用

Sources:

• README.md
• README.md

验证编译环境

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

Source: README.md

编译命令速查

make aw33n_transfer        # 编译 bd57 平台 transfer 应用
make aw33n_hid             # 编译 bd57 平台 hid 应用
make all                   # 编译全部工程
make clean                 # 清理全部编译产物

Source: README.md

Linux 并行编译注意事项

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

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

Source: README.md

常见问题与失败模式

文档体系本身已内置了针对高频失败场景的排查表，README「常见编译错误」一节即为典型的故障处置参考：

Source: README.md

边界情况与注意事项

• 烧录前检查：README 明确警告"烧录前请确保 USB 升级工具正确连接且目标板已进入编程模式"，并将 INI 配置（apps/app/post_build/bd**/flash/isd_config_ini.c）的详细说明指向下载脚本配置文档，避免因配置错误导致烧录失败。
• 文档版本与 SDK 版本一致性：doc/ 离线资料（如用户手册 V1.0、硬件设计指南 V1.0）与在线文档中心按 master 分支同步更新；若使用历史 tag 版本，应以对应 tag 发布时随附的文档为准，避免新旧 API 混用。
• 离线资料格式差异：doc/ 内同时存在 PDF、RAR、XLSX、TXT 等多种格式，部分为压缩包（开发文档.rar、make_gatt_services-v1.2.2.rar），需要解压后使用；AT 命令示例为纯文本 at_cmd_sample.txt，可直接对照。

性能与运维注意事项

• 并行编译：README 明确推荐 -j 参数（如 make aw33n_transfer -j4），但强调链接阶段文件描述符需求，Linux 下必须先 ulimit -n 8096 再并行编译，否则会触发 Too many open files。
• Windows 环境：make 非系统命令时，需通过 tools/make_prompt.bat 进入预配置命令行环境，该脚本已设置好全部环境变量与 make 路径——这是文档资源中值得优先利用的"免配置入口"。
• 日志与调试：串口日志等级/通道通过 log_config.c 配置，GPIO Debug 可利用空闲引脚输出波形测量时序；这两项能力在 README「调试技巧」中作为官方推荐的排查手段记录。

扩展点

文档资源体系的扩展方式与 SDK 工程扩展方式一一对应：

• 新增板级配置：复制 apps/ 下对应应用的 board/ 目录中与芯片型号最接近的板级配置，修改 board_xxx_cfg.h 引脚与外设配置——此时应同步参考 doc/硬件资料/原理图/ 中对应型号的参考原理图，保证引脚映射与硬件一致。
• 新增芯片型号支持：在 cpu/ 下创建平台目录，提供 liba/ 库文件与 tools/ 烧录工具，并在 apps/demo/*/board/ 下添加板级目录——该流程需要配套更新 README 支持芯片表与文档中心的版本信息。
• 自定义 GATT Profile：使用 doc/ble_profile_tools/make_gatt_services-v1.2.2.rar 生成服务代码，再结合在线文档中心的模块文档完成集成。

相关链接

• README.md（中文主入口）
• README-en.md（英文版）
• 杰理在线文档中心 AW33
• SDK 版本历史
• Gitee Issues 反馈
• 蓝牙 SIG 认证详情（QDID DN:Q332415）