环境搭建与工具链安装

本文介绍 fw-AW33N_BLE_SDK（杰理 AW33N 系列蓝牙 SDK）开发环境搭建的完整流程：支持的操作系统、杰理编译工具链（clang 工具链）的下载与安装、验证方法、烧录/测试工具，以及 Makefile、Code::Blocks、VS Code 等构建入口与工具链的集成方式。

Purpose and Scope

本页覆盖的内容：

• 开发前置条件（Windows / Linux 支持情况）
• 杰理编译工具链的下载、安装路径约定与安装验证
• 烧录与生产测试工具的获取方式
• 顶层 Makefile、make_prompt.bat、default.workspace（Code::Blocks）、VS Code 任务等构建入口如何与工具链衔接
• Linux 下文件描述符限制（ulimit -n）等关键环境参数

本页不覆盖以下内容（由其他目录页承接）：

• 具体编译命令与目标速查：见「编译指南」相关页面（README.md 第七节）
• 固件烧录与 OTA 升级细节：见「烧录与升级」相关页面（README.md 第八节）
• 应用选择与工程结构详解：见「应用选择指南」「工程结构」相关页面

Overview

fw-AW33N_BLE_SDK 是杰理科技为 AW33N 系列芯片（平台代号 bd57，含 AW332A / AW333A / AW336A / AW336A0 / AW338A）提供的裸机 BLE SDK。与常见基于 GCC 的嵌入式 SDK 不同，本 SDK 使用杰理自研的 clang 工具链编译，并提供蓝牙协议栈、CPU 驱动等**预编译静态库（lib.a）**与源码工程配合链接。

因此，环境搭建的关键点有三个：

1. 安装正确的编译工具链：必须是杰理官方工具链（clang 系），不是系统自带的 GCC；
2. 遵循路径约定：Linux 下必须解压到 /opt/jieli，并确保 /opt/jieli/common/bin/clang 存在，Makefile 才能找到编译器；
3. 准备配套工具与库：烧录工具、预编译 lib.a 库文件（随仓库提供），以及足够大的文件描述符上限（链接阶段需要）。

环境就绪后，开发者通过顶层 Makefile 统一入口执行 make aw33n_transfer / make aw33n_hid 即可完成两个参考工程的编译，产物为 .hex 文件，位于对应 board 目录下。

Architecture

下图展示「环境搭建 → 工具链 → 构建系统 → 编译产物」的整体架构关系：

flowchart TD
    subgraph sg_Host["宿主机环境"]
        OS["Windows / Linux"]
        TOOLCHAIN["杰理 clang 工具链<br/>(/opt/jieli/common/bin/clang)"]
        FLASH_TOOL["烧录/测试工具<br/>(USB升级/生产烧写/测试盒)"]
    end

    subgraph sg_SDK["SDK 仓库"]
        MAKEFILE["顶层 Makefile<br/>(make aw33n_transfer / aw33n_hid)"]
        BOARD_MK["板级 Makefile<br/>apps/demo/*/board/bd57"]
        PREBUILT["预编译静态库 lib.a<br/>bt_controller_lib / bt_protocol_lib / cpu_lib"]
        VSCODE["VS Code 任务<br/>(.vscode/tasks.json)"]
        CB["Code::Blocks<br/>default.workspace"]
    end

    subgraph sg_Output["编译产物"]
        HEX[".hex 固件文件<br/>(board 目录)"]
    end

    OS --> TOOLCHAIN
    OS --> FLASH_TOOL
    MAKEFILE --> BOARD_MK
    BOARD_MK --> TOOLCHAIN
    BOARD_MK --> PREBUILT
    VSCODE --> MAKEFILE
    CB --> BOARD_MK
    BOARD_MK --> HEX
    HEX --> FLASH_TOOL

架构说明：

• 宿主机层是环境搭建的直接对象：操作系统提供 clang 工具链与烧录工具的运行环境。README 明确 Windows 推荐使用 Code::Blocks IDE，Linux 支持 Makefile 命令行编译（README.md#L62-L70）。
• 工具链是整个环境的基石：编译由 clang 驱动，工具链路径被板级 Makefile 引用；路径不符合约定时编译会直接失败。
• SDK 构建层：顶层 Makefile 将命令转发到具体工程的板级 Makefile（apps/demo/transfer/board/bd57、apps/demo/hid/board/bd57），板级 Makefile 调用 clang 并链接 include_lib 中的预编译 lib.a 库（Makefile#L20-L30）。
• 产物层：编译输出 .hex，随后由 USB 升级工具 / 生产烧写工具 / 无线测试盒完成烧录与测试。

环境搭建步骤详解

前提条件

来源：README.md#L62-L70

设计意图：Windows 用户通过 IDE 获得图形化编译/调试体验，Linux 用户通过命令行获得可脚本化的 CI 能力；两条路径共用同一套板级 Makefile 与 clang 工具链，保证产物一致。

安装杰理编译工具链

工具链必须使用杰理官方编译工具链（基于 clang），不能使用系统自带 GCC 替代。安装步骤：

1. 下载工具链：从杰理文档中心获取安装包：
   • 通用入口：杰理编译工具链下载页
   • Linux 专用入口：pkgman.jieliapp.com
2. Linux 安装路径约定：下载后解压到 /opt/jieli 目录，并确保 /opt/jieli/common/bin/clang 存在（注意目录层次）。
3. 验证安装：在终端/命令提示符中执行：

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

来源：README.md#L71-L82

设计意图：/opt/jieli 是杰理工具链的固定安装根目录，板级 Makefile 内部按此路径查找编译器。README 中特别提示「注意目录层次」，是因为解压工具链后 clang 实际位于 common/bin 子目录而非根目录，层级错误会导致后续编译找不到编译器。

Linux 文件描述符限制（ulimit）

顶层 Makefile 头部的注释中明确记录了一个 Linux 特有的环境要求：

# 3. 确认 ulimit -n 的结果足够大（建议大于8096），否则链接可能会因为打开文件太多而失败
#    可以通过 ulimit -n 8096 来设置一个较大的值

来源：Makefile#L6-L7

设计意图：链接阶段需要同时打开大量目标文件与静态库（lib.a），若系统默认文件描述符上限（通常为 1024）过小，链接器会报「打开文件太多」错误。这是该 SDK 在 Linux 上最常见的环境类故障，安装后应优先检查。

安装烧录与测试工具

来源：README.md#L84-L91

设计意图：开发阶段使用 USB 升级工具即可完成固件验证；量产阶段需使用生产烧写工具对裸片进行批量烧写；无线测试盒则用于射频性能标定与产线测试。三者覆盖「开发 → 量产 → 测试」全链路。

获取 SDK 源码

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

cd fw-AW33N_BLE_SDK

来源：README.md#L96-L102

仓库为 SDK Release 版本代码，需配合按命名规则提供的库文件（lib.a）与子仓库进行编译（README.md#L42），因此克隆后请勿删除 apps/include_lib 下的预编译库，否则链接阶段将失败。

构建入口与工具链集成

环境搭建完成后，可通过以下四种方式触发编译，它们最终都汇入同一套板级 Makefile：

方式一：顶层 Makefile（Linux/Windows 命令行）

顶层 Makefile 是统一编译入口，将命令转发到具体工程的板级 Makefile：

aw33n_transfer:
	$(MAKE) -C apps/demo/transfer/board/bd57 -f Makefile

clean_aw33n_transfer:
	$(MAKE) -C apps/demo/transfer/board/bd57 -f Makefile clean

aw33n_hid:
	$(MAKE) -C apps/demo/hid/board/bd57 -f Makefile

clean_aw33n_hid:
	$(MAKE) -C apps/demo/hid/board/bd57 -f Makefile clean

来源：Makefile#L20-L30

使用方式（在 SDK 根目录）：

# 编译完整工程
make aw33n_hid

# 编译完成后，在对应 board 目录下找到生成的 .hex 文件

来源：README.md#L150-L156

设计意图：顶层 Makefile 只做「路由」，不承载编译逻辑——每个应用工程的板级 Makefile（board/bd57/Makefile）才是真正调用 clang、链接 lib.a 的地方。这种分层设计使得新增应用只需在顶层添加一个转发目标。

方式二：make_prompt.bat（Windows 专用命令行入口）

仓库提供 Windows 专用 Make 命令行入口脚本，自动把编译工具目录加入 PATH：

SET SCRIPT_PATH=%~dp0%
set PATH=%SCRIPT_PATH%\tools\utils;%PATH%

cmd

来源：make_prompt.bat#L1-L4

设计意图：%~dp0% 取脚本自身所在目录，据此将 tools\utils（存放 make 等编译辅助工具）注入 PATH，随后打开一个预配置的 cmd 窗口。这样 Windows 用户无需手动配置环境变量即可直接使用 make 命令。

方式三：Code::Blocks IDE（Windows 推荐）

仓库根目录的 default.workspace 是预配置的 Code::Blocks 工作空间（README.md#L212），工程文件为 board_*.cbp 形式（README-en.md#L132）。Windows 用户打开工作空间后即可在 IDE 内完成编译，IDE 会调用与命令行相同的工具链。

方式四：VS Code 任务

仓库预配置了 VS Code 构建任务（.vscode/tasks.json），按 Ctrl+Shift+B 即可选择编译目标（README.md#L160-L163），适合偏好轻量编辑器的开发者。

环境就绪检查清单

完成上述步骤后，可按以下顺序自检：

1. clang --version 能输出版本信息（工具链已安装且 PATH 正确）；
2. Linux 下 /opt/jieli/common/bin/clang 文件存在（路径层级正确）；
3. Linux 下 ulimit -n 返回值大于 8096（必要时执行 ulimit -n 8096）；
4. SDK 根目录存在 Makefile、default.workspace、make_prompt.bat；
5. apps/include_lib 下的 lib.a 预编译库完整；
6. 执行 make aw33n_hid 能在 apps/demo/hid/board/bd57 下生成 .hex 文件。

核心流程：从零搭建到首次编译

下图展示从环境准备到产出固件的完整时序：

sequenceDiagram
    participant Dev as 开发者
    participant OS as 宿主机(Windows/Linux)
    participant TC as 杰理 clang 工具链
    participant SDK as SDK 仓库
    participant MK as 顶层/板级 Makefile
    participant LB as 预编译库 lib.a

    Dev->>OS: 下载并安装杰理编译工具链
    OS->>OS: Linux: 解压到 /opt/jieli
    Dev->>OS: 验证 clang --version
    OS-->>Dev: 输出版本号
    Dev->>SDK: git clone 仓库
    Dev->>OS: 检查 ulimit -n > 8096 (Linux)
    Dev->>MK: make aw33n_hid / aw33n_transfer
    MK->>TC: 调用 clang 编译源码
    MK->>LB: 链接 bt_controller_lib / bt_protocol_lib / cpu_lib
    LB-->>MK: 符号解析完成
    MK-->>Dev: 输出 .hex 固件 (board 目录)
    Dev->>OS: 使用 USB升级/烧写工具烧录

流程要点：

1. 工具链先行：任何编译动作都依赖 clang 工具链，且 Linux 路径必须为 /opt/jieli/common/bin/clang；
2. 环境参数调优：Linux 下需确认文件描述符上限，否则链接阶段失败；
3. 编译路由：顶层 Makefile 将目标转发到 apps/demo/*/board/bd57 的板级 Makefile；
4. 静态链接：蓝牙协议栈与 CPU 驱动来自预编译 lib.a，与源码编译出的目标文件一起链接成 .hex；
5. 烧录闭环：.hex 通过烧录工具写入目标板，完成开发验证。

API Reference：Makefile 目标

顶层 Makefile 是环境验证与日常编译的核心接口，其公开目标如下（来源：Makefile#L8-L30、README.md#L254-L263）：

参数： 无（目标即参数）。

返回： 编译成功输出 +ALL DONE / +CLEAN DONE（make all / make clean 时）；失败返回非零退出码并停止。

前置条件（Throws 等价场景）：

• clang 工具链未安装或路径不符 → 编译器找不到，报 clang: command not found；
• Linux ulimit -n 过小 → 链接阶段报「打开文件太多」类错误；
• 预编译 lib.a 缺失 → 链接阶段符号未定义错误。

Configuration Options

失败模式与边界情况

基于源码注释与 README 的明确记载，环境搭建阶段最常见的故障如下：

边界情况：

• Windows 与 Linux 的差异：Windows 推荐 Code::Blocks（default.workspace），Linux 走 Makefile 命令行；make_prompt.bat 仅面向 Windows，其 %~dp0% 路径解析依赖脚本所在目录，移动脚本会破坏 tools\utils 的路径注入；
• 目标与目录的强绑定：make aw33n_transfer 固定路由到 apps/demo/transfer/board/bd57，芯片平台（bd57）与应用（transfer/hid）一一对应，不可混用（Makefile#L20-L27）；
• 产物位置约定：.hex 输出到对应 board 目录，不同应用产物互不覆盖，但 make clean 会同时清理全部工程产物。

性能与运维注意事项

• 链接阶段是资源瓶颈：.hex 由源码目标文件与多个 lib.a 静态库链接而成，链接器需打开大量文件，这是 ulimit -n 要求高于系统默认值（1024）的根本原因；建议 CI 环境在构建前显式设置 ulimit -n 8096；
• 增量构建：顶层 Makefile 通过 $(MAKE) -C 递归调用子 Makefile，子 Makefile 基于文件时间戳做增量编译，日常迭代只需重复 make 同一目标即可；
• 清理策略：make clean 为全量清理，会删除两个工程的中间产物，下次编译为全量构建，耗时较长；单工程清理应使用 make clean_aw33n_transfer / make clean_aw33n_hid；
• 可脚本化：Linux 命令行编译方式天然适配 CI/CD 流水线（git clone → 工具链检查 → make all → 收集 .hex）。

扩展点

• 新增应用工程：在 apps/demo/<app>/board/bd57 下按现有工程结构新建板级配置，并在顶层 Makefile 的 .PHONY 与目标列表中添加对应转发目标（参考 Makefile#L12-L30 的 aw33n_hid 模式）；
• 新增芯片平台：在 apps/demo/*/board/ 下新增平台目录，并配套 apps/include_lib/liba/<platform>/flash 下的对应 lib.a 预编译库；
• 定制构建入口：修改 make_prompt.bat 可追加更多工具目录到 PATH；修改 .vscode/tasks.json 可新增 VS Code 构建任务。

测试与验证

SDK 仓库本身未包含环境相关的自动化测试脚本，环境就绪与否以「编译验证」为准：成功执行 make aw33n_hid / make aw33n_transfer 并生成 .hex 即视为环境搭建完成。建议在环境变更（换机、升级工具链、切换系统）后，先执行一次 make clean + make all 做全量回归验证。

Related Links

• README.md（环境搭建与快速开始）
• README-en.md（English: Environment Setup）
• Makefile（顶层编译入口与工具链要求）
• make_prompt.bat（Windows 命令行入口）
• 杰理文档中心：开发环境工具
• 杰理文档中心：AW33 系列文档
• 相关页面：编译指南（make 目标速查）、烧录与升级（download.bat / isd_download.exe 用法）、工程结构（apps/demo/*/board 布局）