快速开始：选型、编译与烧录

本文介绍 fw-AW31N_BLE_SDK 从克隆仓库、芯片/应用选型、板级配置、环境搭建、编译到烧录的完整上手流程，帮助开发者最快在 AW31N 系列芯片上跑通第一个蓝牙应用。

Purpose and Scope

本页面覆盖「快速开始」的完整闭环：芯片选型 → 应用选型 → 板级配置 → 编译（Code::Blocks / Makefile / VS Code 三种入口）→ 固件烧录，并深入解读顶层 Makefile 与板级 Makefile 的协作机制，说明 Windows/Linux 两种平台的工具链差异。

以下主题属于兄弟页面，不在本文展开：

• 工程结构与目录职责：各目录的详细说明请参考仓库 README 的「工程结构」章节。
• 配置说明（功能裁剪）：board_xxx_cfg.h / board_xxx_global_build_cfg.h 的功能开关与引脚配置细节属于配置主题。
• 常见问题与认证信息：属于 FAQ 与认证主题。

Overview

fw-AW31N_BLE_SDK 是杰理科技（Jieli）为 AW31N 系列芯片提供的通用蓝牙 SDK 固件开发包，基于裸机操作系统，内置完整蓝牙 BLE 协议栈（Bluetooth Core v5.4，QDID 222830 已认证），并提供 transfer（透传/数传）与 hid（人机交互）两大类应用示例。SDK 采用「顶层 Makefile 统一入口 + 板级 Makefile 分工程编译」的结构，配合预编译静态库（lib.a）与对应命名规则的子仓库，实现一次配置、多平台编译。

对于第一次接触该 SDK 的开发者，典型的决策路径是：

1. 确认目标芯片属于 bd47 平台（AW312B / AW313A / AW314A / AW318A / AW318B）；
2. 根据产品形态选择应用类型（透传选 transfer，HID 设备选 hid）；
3. 在 apps/demo/*/board/bd47/ 下挑选或新建板级配置；
4. 搭建编译环境（Windows 推荐 Code::Blocks，Linux 使用 Makefile）；
5. 编译生成 .hex 固件，用 USB 升级工具或生产烧写工具烧录。

Architecture

以下流程图展示了从选型到烧录的完整链路，以及每个阶段对应的仓库路径与工具：

flowchart TD
    subgraph sg_Selection["选型阶段"]
        A["芯片选型<br/>bd47 平台：AW312B / AW313A / AW314A / AW318A / AW318B"]
        B["应用选型<br/>apps/demo/transfer 或 apps/demo/hid"]
        C["板级配置<br/>apps/demo/*/board/bd47/"]
    end
    subgraph sg_Build["编译阶段"]
        D["编译入口<br/>Code::Blocks / Makefile / VS Code"]
        E["杰理工具链<br/>clang / q32s-lto-wrapper"]
        F["输出产物<br/>apps/app/post_build/bd47/sdk.elf → .hex"]
    end
    subgraph sg_Flash["烧录阶段"]
        G["USB 升级工具"]
        H["生产烧写工具 / 无线测试盒"]
    end
    A --> B --> C
    C --> D
    D --> E --> F
    F --> G
    F --> H

架构说明：

• 选型阶段决定「编译什么」：芯片平台（bd47）决定工具链目标（-target q32s），应用类型（transfer/hid）决定顶层 Makefile 的 target，板级目录决定具体的引脚与功能配置。
• 编译阶段决定「怎么编译」：三种入口最终都汇入板级 Makefile；板级 Makefile 负责定位杰理 clang 工具链、组装 CFLAGS/DEFINES，并通过链接器（LTO）产出 ELF，再经 post_build 脚本生成可烧录的 .hex。
• 烧录阶段决定「烧到哪里」：开发阶段用 USB 升级工具烧 .hex；量产阶段用生产烧写工具（裸片烧写）或无线测试盒（空中升级/射频标定）。

芯片与应用选型

芯片平台（bd47）

SDK 当前支持的芯片平台为 bd47，覆盖 AW31N 系列以下型号，均适用于 transfer 与 hid 应用：

该平台通过板级 Makefile 中的 -DCONFIG_CPU_BD47=1 宏定义区分，配合 -target q32s 指定 CPU 架构（q32s 为杰理 32 位 DSP/MCU 内核）。蓝牙协议栈已通过 Core v5.4 认证（QDID 222830），选型时无需担心协议合规性。

应用类型（transfer / hid）

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

选型建议：纯数据通道类产品（传感器数据上报、AT 模组）选择 transfer；需要与 PC/手机进行人机交互的外设（键鼠、遥控器、翻页器）选择 hid。两者的目录结构、编译方式完全一致，仅板级配置与应用代码不同。

板级配置结构

每个应用目录下都有 board/ 子目录，按芯片平台划分：

apps/demo/hid/board/
└── bd47/   # AW31N 系列（3 个产品应用和 1 个 demo 板级配置）

每个芯片目录下包含 5 类关键文件：

选型完成后，下一步是搭建编译环境。工具链安装要求详见下一节。

环境搭建

前提条件

安装杰理编译工具链

1. 下载并安装杰理编译工具链（官方下载链接见 README「环境搭建」章节）。
2. Linux 用户可从 pkgman.jieliapp.com 下载，解压到 /opt/jieli 目录，并确保 /opt/jieli/common/bin/clang 存在（注意目录层次）。
3. 安装完成后验证：

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

工具链的定位逻辑在板级 Makefile 中硬编码：Windows 下为 C:/JL/pi32/bin（使用 clang.exe、q32s-lto-wrapper.exe、llvm-ar.exe），Linux 下为 /opt/jieli/q32s/bin（使用 clang、lto-wrapper、lto-ar）。因此安装路径必须与 Makefile 中的约定一致，否则编译会因找不到 clang 而失败。

安装烧录工具

编译流程

三种编译入口

flowchart TD
    subgraph sg_Entry["编译入口（三选一）"]
        CB["Code::Blocks<br/>打开 board_*.cbp，Build → Build (Ctrl+F9)"]
        MK["Makefile 命令行<br/>make aw31n_hid"]
        VSC["VS Code<br/>Ctrl+Shift+B 选择编译任务"]
    end
    subgraph sg_Top["顶层 Makefile（仓库根目录）"]
        T["make aw31n_hid / aw31n_transfer"]
    end
    subgraph sg_Board["板级 Makefile（apps/demo/*/board/bd47/Makefile）"]
        B1["设置工具链路径 TOOL_DIR"]
        B2["组装 CFLAGS / DEFINES"]
        B3["链接产出 sdk.elf 并调用 post_build 脚本"]
    end
    subgraph sg_Out["输出与烧录"]
        O["apps/app/post_build/bd47/ 下生成 .hex"]
        P["USB 升级工具烧录 .hex"]
    end
    CB --> T
    MK --> T
    VSC --> T
    T --> B1 --> B2 --> B3
    B3 --> O
    O --> P

方式一：Code::Blocks（推荐 Windows 用户）

# 1. 进入对应的板级目录
cd apps/demo/hid/board/bd47/

# 2. 双击打开 .cbp 工程文件（如 AW31N_hid.cbp）
# 3. 在 Code::Blocks 中点击 Build → Build (Ctrl+F9)
# 4. 编译成功后，使用 USB 升级工具烧录生成的 .hex 文件

方式二：Makefile 命令行

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

# Linux/macOS 用户
cd SDK 根目录

# 编译完整工程
make aw31n_hid

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

方式三：VS Code 编译

仓库已预配置 VS Code 任务（.vscode/tasks.json），按 Ctrl+Shift+B 即可选择编译目标。

顶层 Makefile 的委托机制

顶层 Makefile 是整个 SDK 的统一编译入口，本身不包含编译逻辑，而是把工作委托给各应用的板级 Makefile：

# 支持的目标
# make aw31n_transfer
# make aw31n_hid

.PHONY: all clean aw31n_transfer aw31n_hid clean_aw31n_transfer clean_aw31n_hid

all: aw31n_transfer aw31n_hid
	@echo +ALL DONE

clean: clean_aw31n_transfer clean_aw31n_hid
	@echo +CLEAN DONE

aw31n_transfer:
	$(MAKE) -C apps/demo/transfer/board/bd47 -f Makefile

aw31n_hid:
	$(MAKE) -C apps/demo/hid/board/bd47 -f Makefile

设计意图：all 默认编译全部应用，方便 CI/全量验证；clean 同样按应用拆分，避免互相污染。新增应用时只需在此追加一个 target，保持「顶层调度、板级实现」的分层结构。顶层 Makefile 中所有支持的 target 名称见 Makefile 开头注释。

板级 Makefile 的关键配置

以 apps/demo/hid/board/bd47/Makefile 为例，其核心职责是按操作系统选择工具链并组装编译参数：

# 工具路径设置
ifeq ($(OS), Windows_NT)
# Windows 下工具链位置
TOOL_DIR := C:/JL/pi32/bin
CC    := clang.exe
CXX   := clang.exe
LD    := q32s-lto-wrapper.exe
AR    := llvm-ar.exe
...
SYS_LIB_DIR := C:/JL/pi32/q32s-lib
SYS_INC_DIR := C:/JL/pi32/q32s-include
EXT_CFLAGS  := # Windows 下不需要 -D__SHELL__
...
## 后处理脚本
FIXBAT          := ../../../../../tools/utils/fixbat.exe # 用于处理 utf8->gbk 编码问题
POST_SCRIPT     := ../../../../../apps/app/post_build/bd47/download.bat
...
else
# Linux 下工具链位置
TOOL_DIR := /opt/jieli/q32s/bin
CC    := clang
...
EXT_CFLAGS  := -D__SHELL__ # Linux 下需要这个保证正确处理 download.c
...
POST_SCRIPT     := ../../../../../apps/app/post_build/bd47/download.sh
endif

设计意图与平台差异：

• 工具链封装：Windows 用 q32s-lto-wrapper.exe，Linux 用 lto-wrapper，两者都基于 LLVM LTO 链接，保证 lib.a 跨平台一致性。
• -D__SHELL__ 差异：Linux 的 download.c 需要在 shell 环境下正确处理路径，故单独加宏；Windows 下由 .bat 脚本驱动，不需要。
• 编码处理：Windows 的 .bat 脚本由 fixbat.exe 做 UTF-8 → GBK 转换，避免中文路径/注释乱码；Linux 直接用 touch 占位。
• 输出路径统一：ELF 输出到 apps/app/post_build/bd47/sdk.elf，与各应用共用同一个 post_build 目录，方便烧录脚本统一取件。

编译参数与宏定义（CFLAGS/DEFINES）体现了 q32s 平台的关键约束：-target q32s 指定 CPU 目标；-flto + -Oz/-Os 追求代码体积（裸机 Flash 资源有限）；-Werror=... 系列把常见错误升级为编译失败；宏定义中 -DCONFIG_CPU_BD47=1、-DAPP_BT_BLE=1、-DAPP_CASE_HID、-DSDK_VERSION_CFG_DEFINE=0x130001、-DSDK_VERSION_DATE_DEFINE=20250822 等决定了本次编译的芯片平台、应用类型与版本信息。

Core Flow

编译与烧录时序

sequenceDiagram
    participant Dev as 开发者
    participant T as 顶层 Makefile
    participant BM as 板级 Makefile
    participant TC as 杰理工具链 clang/q32s
    participant PS as post_build 脚本
    participant FT as 烧录工具

    Dev->>T: make aw31n_hid
    T->>BM: $(MAKE) -C apps/demo/hid/board/bd47 -f Makefile
    BM->>TC: clang -flto -target q32s ... 编译与 LTO 链接
    TC-->>BM: sdk.elf + sdk.elf.objs.txt
    BM->>PS: 调用 download.bat / download.sh
    PS-->>Dev: 生成可烧录 .hex 固件
    Dev->>FT: 打开 USB 升级工具选择 .hex
    FT-->>Dev: 烧录完成，上电运行

关键点：整个流程中 sdk.elf 是编译与烧录的中间桥梁——链接产物统一落在 apps/app/post_build/bd47/，post_build 脚本（download.bat/download.sh）负责将其转换为烧录工具可直接使用的 .hex。开发者拿到 .hex 后即可用 USB 升级工具完成烧录，无需关心 ELF 内部的段布局。

使用示例

示例一：克隆仓库并选择工程

git clone https://github.com/Jieli-Tech/fw-AW31N_BLE_SDK.git
或者
git clone https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK.git

cd fw-AW31N_BLE_SDK

Source: README.md

示例二：完整编译命令

# Windows 用户：双击 tools/make_prompt.bat 打开命令行环境
# Linux/macOS 用户：直接 cd 到 SDK 根目录

# 编译 HID 应用（如遥控器/键盘/鼠标）
make aw31n_hid

# 编译 TRANSFER 应用（透传/数传/AT 模组）
make aw31n_transfer

# 全量编译
make all

# 清理
make clean

# 查看详细编译过程
make VERBOSE=1

Source: README.md 与 Makefile

示例三：Windows 命令行环境入口

SET SCRIPT_PATH=%~dp0%
set PATH=%SCRIPT_PATH%\utils;%PATH%
cd ..
cmd

该脚本将 tools/utils 加入 PATH（其中包含 fixbat.exe 等辅助工具），然后回到 SDK 根目录打开交互式命令行，方便开发者直接执行 make aw31n_hid 等命令。

Source: tools/make_prompt.bat

示例四：板级 Makefile 工具链与输出配置

# 工具路径设置
ifeq ($(OS), Windows_NT)
# Windows 下工具链位置
TOOL_DIR := C:/JL/pi32/bin
CC    := clang.exe
...
SYS_LIB_DIR := C:/JL/pi32/q32s-lib
SYS_INC_DIR := C:/JL/pi32/q32s-include
else
# Linux 下工具链位置
TOOL_DIR := /opt/jieli/q32s/bin
...
endif

# 输出文件设置
OUT_ELF   := ../../../../../apps/app/post_build/bd47/sdk.elf
OBJ_FILE  := $(OUT_ELF).objs.txt

解读：OUT_ELF 使用相对路径（从 apps/demo/hid/board/bd47/ 上溯 5 级到仓库根目录），把 ELF 输出到所有应用共享的 post_build/bd47/ 目录；OBJ_FILE 记录参与链接的对象文件清单，供 post_build 脚本分析。若工具链安装位置与 TOOL_DIR 不一致，需同步修改此处。

Source: apps/demo/hid/board/bd47/Makefile

配置选项

以下配置项决定编译产物与目标平台，修改后需重新 make：

注：board_xxx_cfg.h 与 board_xxx_global_build_cfg.h 中的引脚/外设/功能开关配置属于「配置说明」主题，本文不展开。

API Reference

make 目标（顶层 Makefile）

板级 Makefile 参数

失败模式与边界情况

工具链相关

选型与版本相关

• lib.a 命名规则：仓库包含的是 Release 版本代码，需配合对应命名规则的预编译库文件（bt_controller_lib.a、bt_protocol_lib.a、cpu_lib.a 等）和子仓库编译。库文件与 SDK 代码版本不匹配是「编译通过但链接失败」的常见原因。
• 平台宏一致性：CONFIG_CPU_BD47=1、APP_BT_BLE=1、APP_CASE_HID 等 DEFINES 必须与所选应用一致；错误组合会导致外设驱动或协议栈裁剪异常。
• -Werror 策略：板级 Makefile 启用了 -Werror 及 -Werror=implicit-function-declaration、-Werror=return-type、-Werror=undef 等，任何警告都会终止编译。这是刻意的「零容忍」设计，防止裸机固件中因隐式声明/未定义宏产生难以排查的运行时缺陷。

边界情况

• 顶层 make all 会串行编译两个应用，耗时较长；若只需单个应用，请使用 make aw31n_hid 或 make aw31n_transfer 节省时间。
• 本 SDK 为裸机单线程模型，编译/烧录流程本身无并发风险；但并行执行多个 make 可能因共享 post_build/bd47/ 输出目录产生竞争，建议始终通过顶层 Makefile 串行构建。
• 烧录阶段使用 USB 升级工具时，需先让目标板进入升级模式（与工具配套的强制升级文档说明），否则工具无法识别设备。

性能与运维建议

• 代码体积优化：板级 Makefile 默认启用 -flto（LTO 链接）与 -Oz/-Os 体积优化、-mllvm -inline-threshold=5 控制内联膨胀，这是针对 Flash 资源受限的裸机场景的默认策略，不建议关闭。
• 详细日志：排查编译问题时使用 make VERBOSE=1 查看完整命令行，便于确认宏定义与工具链参数是否生效。
• 统一产物目录：所有应用的 sdk.elf/.hex 均输出到 apps/app/post_build/bd47/，运维脚本只需固定监听该目录即可，无需关心具体应用。
• 版本信息可追溯：SDK_VERSION_CFG_DEFINE（0x130001）与 SDK_VERSION_DATE_DEFINE（20250822）会编入固件，可通过工具读取，便于现场固件版本核对。

扩展点

• 新增应用 target：在顶层 Makefile 中追加形如 aw31n_xxx: $(MAKE) -C apps/demo/xxx/board/bd47 -f Makefile 的目标，并加入 all/clean 依赖链。
• 新增板级配置：在 apps/demo/*/board/bd47/ 下复制现有板级文件，新增 board_xxx.c、board_xxx_cfg.h、board_xxx_global_build_cfg.h 与对应 .cbp，再在板级 Makefile 中挂接新的源文件列表。
• 自定义编译宏：板级 Makefile 的 DEFINES += $(EXT_CFLAGS) 预留了追加通道，可在不改动核心文件的前提下注入自定义宏。
• 烧录流程扩展：post_build 目录中的 download.bat/download.sh 是烧录流水线的挂载点，可在此追加自动生成烧录脚本、固件签名、版本校验等步骤。

Related Links

• README.md（官方快速开始与文档中心入口）
• README-en.md（英文版说明）
• 顶层 Makefile（编译目标一览）
• HID 板级 Makefile（工具链与编译参数）
• tools/make_prompt.bat（Windows 命令行入口）
• 杰理 AW31 文档中心
• 兄弟页面参考：工程结构（目录职责详解）、配置说明（功能裁剪与引脚配置）、常见问题（编译/烧录问题排查）