# fw-AW31N_BLE_SDK

**Repository Path**: Jieli-Tech/fw-AW31N_BLE_SDK

## Basic Information

- **Project Name**: fw-AW31N_BLE_SDK
- **Description**: Firmware for Generic Bluetooth Low Energy SDK（AW3N series）, Support AW31N.
- **Primary Language**: C
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 21
- **Forks**: 8
- **Created**: 2024-04-24
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[tag download]:https://github.com/Jieli-Tech/fw-AW31N_BLE_SDK/tags
[tag_badgen]:https://img.shields.io/github/v/tag/Jieli-Tech/fw-AW31N_BLE_SDK?style=plastic&logo=bluetooth&labelColor=ffffff&color=informational&label=Tag&logoColor=blue

# fw-AW31N_BT_SDK  [![tag][tag_badgen]][tag download]

<div align="center">
**杰理 AW31N系列通用蓝牙 SDK 固件程序**

[English](./README-en.md) · [文档中心](https://doc.zh-jieli.com/AW31/zh-cn/master/index.html) · [SDK 版本历史](https://doc.zh-jieli.com/AW31/zh-cn/master/other/version/index.html) · [报告问题](https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK/issues)

</div>

---

## 📋 目录

- [一、概述](#一概述)
- [二、支持的芯片与平台](#二支持的芯片与平台)
- [三、环境搭建](#三环境搭建)
- [四、快速开始](#四快速开始)
- [五、工程结构](#五工程结构)
- [六、应用选择指南](#六应用选择指南)
- [七、编译指南](#七编译指南)
- [八、烧录与升级](#八烧录与升级)
- [九、配置说明](#九配置说明)
- [十、常见问题](#十常见问题)
- [十一、社区与支持](#十一社区与支持)
- [十二、认证信息](#十二认证信息)
- [十三、免责声明](#十三免责声明)

---

## 一、概述

`fw-AW31N_BLE_SDK` 是杰理科技为 AW31N 系列芯片提供的通用蓝牙 SDK 固件开发包。本 SDK 基于裸机操作系统，提供完整的蓝牙BLE协议栈和丰富的应用示例，支持以下应用场景：

| 应用类型 | 典型产品 |
|---------|---------|
| **BLE 透传/数传** | 透传, 数据传输, 扫描设备, 广播设备, 适配器, AT模组等 |
| **HID 人机交互** | 遥控器、自拍器、翻页器、键盘、3模鼠标（2.4G/USB能支持到1K回报率）等 |

本仓库包含 SDK Release 版本代码及示例工程，需配合对应命名规则的库文件 (`lib.a`) 和子仓库进行编译。

---

## 二、支持的芯片与平台

### 2.1 芯片系列

| 芯片平台 | 芯片型号 | 适用应用 |
|---------|---------|---------|
| **bd47** | AW312B / AW313A/ AW314A/ AW318A/ AW318B | transfer / hid |

### 2.2 蓝牙协议支持

| 蓝牙规范 | QDID | 状态 |
|---------|------|------|
| Core v5.4 | [QDID 222830](https://launchstudio.bluetooth.com/ListingDetails/193923) | ✅ 已认证 |

---

## 三、环境搭建

### 3.1 前提条件

| 系统 | 说明 |
|------|------|
| **Windows** | ✅ 推荐使用 Code::Blocks IDE 编译 |
| **Linux** | ✅ 支持 Makefile 命令行编译 |

### 3.2 安装编译工具链

1. 下载并安装 **杰理编译工具链**：[下载链接](https://doc.zh-jieli.com/Tools/zh-cn/dev_tools/dev_env/index.html)
2. Linux 用户可从此处下载：[pkgman.jieliapp.com](http://pkgman.jieliapp.com/doc/all)
   - 下载后解压到 `/opt/jieli` 目录
   - 确保 `/opt/jieli/common/bin/clang` 存在
3. 安装完成后，打开终端/命令提示符验证：

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

### 3.3 安装烧录工具

| 工具 | 用途 | 获取方式 |
|------|------|---------|
| **USB 升级工具** | 将固件烧录到目标板 | [申请链接](https://item.taobao.com/item.htm?id=620295020803) · [使用文档](https://doc.zh-jieli.com/Tools/zh-cn/dev_tools/forced_upgrade/index.html) |
| **生产烧写工具** | 量产/裸片烧写 | [使用文档](https://doc.zh-jieli.com/Tools/zh-cn/mass_prod_tools/burner_1tuo2/index.html) |
| **无线测试盒** | 空中升级/射频标定/产品测试 | [申请链接](https://item.taobao.com/item.htm?id=620942507511) · [使用文档](https://doc.zh-jieli.com/Tools/zh-cn/mass_prod_tools/testbox_1tuo2/index.html) |

---

## 四、快速开始

### 4.1 克隆仓库

```bash
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
```

### 4.2 选择合适的工程

根据你的产品需求选择应用工程：

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

### 4.3 选择芯片型号和板级配置

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

```
apps/demo/hid/board/
├── bd47/   # AW31N 系列 (3个产品应用和1个demo板级配置)
```

每个芯片目录下包含：
- `Makefile` - 编译脚本
- `board_*.cbp` - Code::Blocks 工程文件
- `board_xxx.c` - 板级初始化代码
- `board_xxx_cfg.h` - 板级配置（引脚、外设等）
- `board_xxx_global_build_cfg.h` - 全局编译配置（功能开关）

### 4.4 编译并烧录

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

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

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

**方式二：Makefile 命令行**

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

# Linux/macOS 用户
cd SDK 根目录

# 编译完整工程
make aw31n_hid

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

> **💡 提示**：所有支持的 target 名称见 [Makefile](https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK/blob/master/Makefile) 开头的注释。

**方式三：VS Code 编译**

仓库已预配置 VS Code 任务，按 `Ctrl+Shift+B` 即可选择编译目标。

---

## 五、工程结构

```
fw-AW31N_BLE_SDK/
├── apps
│   ├── app/                # 应用层代码
│   │   ├── bsp/                  # 公共模块、SDK配置和输出
│   │   │   ├── common/             # 公共模块处理（跨工程共享）
│	│   │   │   ├── bt_common/             # 蓝牙通用处理
│	│   │   │   ├── codeswitch/            # 旋转编码器驱动
│	│   │   │   ├── common_uart/           # 通用串口适配驱动
│	│   │   │   ├── ir/                    # 红外驱动处理
│	│   │   │   ├── key/                   # 按键驱动处理
│	│   │   │   ├── mouse_sensor/          # 传感器驱动处理
│	│	│	│	├── .../
│	│   │   │   ├── msg/                   # 系统消息处理
│	│   │   │   ├── temp_trim /            # 系统温度自适应处理
│	│   │   │   ├── third_party_profile/   # 第三方协议处理
│	│   │   │   ├── update/                # 固件升级处理
│	│   │   │   ├── usb/                   # usb驱动处理
│	│   │   │   ├── vm/                    # 系统消息处理
│	│	│	│	├── .../
│	│   │   │   └── my_malloc.c/           # 系统堆申请处理
│	│	│	├── cpu                   # CPU、系统相关处理文件
│	│	│	├── .../          
│	│	│	└── start                 # 上电应用层启动入口处理
│   │   └── postbuild/            # 工程编译前配置和下载目录等
│   │   │   └── bd47/                  #   各芯片平台的 lib.a 库文件 + 工具脚本
│   │── demo/
│   │   ├── hid/                       # 📌 HID 应用（键盘/鼠标/遥控器/游戏手柄）
│   │   └── tranfer/                   # 📌 BLE 应用
│   └── include_lib/                # 头文件（bt协议栈、驱动、媒体、系统、cpu等）
│       ├── bt_controller_include /    # 蓝牙控制器的头文件
│       ├── bt_include /               # 蓝牙协议栈的头文件
│       ├── device  /                  # 外设驱动的头文件
│       ├── fs  /                      # 文件系统的头文件
│       ├── msg   /                    # 系统消息队列的头文件
│       ├── update  /                  # 无线OTA升级的头文件
│       ├── common /                   # 通用公共的头文件
│       ├── cpu/                       # 各芯片平的头文件
│       ├── .../
│       └── flash/                 #各芯片平台的 lib.a 库文件
├── doc/                    # SDK发布文档资源：版本发布信息、芯片数据手册、硬件设计资料、使用说明文档等
├── tools/                  # 编译工具与脚本
│   └── make_prompt.bat     # Windows 编译命令行入口
├── Makefile                # 顶层 Makefile（统一编译入口）
├── default.workspace       # Code::Blocks 工作空间
└── .vscode/                # VS Code 配置（tasks.json 预定义编译任务）
```

### 5.1 关键目录说明

| 目录 | 作用 |
|------|------|
| `apps/demo/*/board/` | **板级配置**：引脚定义、外设初始化、编译选项 |
| `apps/demo/*/examples/` | **示例应用**：可直接参考或修改的参考实现 |
| `apps/demo/*/include/` | **应用头文件**：模块接口定义 |
| apps/demo/*/config/ | **库配置**：各模块的裁剪配置（决定编译哪些库功能） |
| apps/demo/*/config/ | **公共模块**：examples里面公共使用的功能 |
| ` apps/include_lib/liba/bd**/flash` | **预编译库**：`*.a` 静态库文件（bt_controller_lib.a、bt_protocol_lib.a、cpu_lib.a等） |
| `apps/app/post_build/bd**/` | **烧录工具**：download.bat、fw_add.exe、isd_download.exe 等 |

---

## 六、应用选择指南

### 6.1 TRANSFER (`apps/demo/transfer`)

| 项目 | 说明 |
|------|------|
| **适用场景** | 透传, 数据传输, 扫描设备, 广播设备, 适配器, AT模组等 |
| **关键特性** | 透传, 数据传输，支持 AT 指令控制 |
| **参考文档** | [TRANSFER 开发文档](https://doc.zh-jieli.com/AW31/zh-cn/master/module_demo/spple/index.html) |

### 6.2 HID (`apps/demo/hid`)

| 项目 | 说明 |
|------|------|
| **适用场景** | 媒体播放控制、遥控器、自拍器、翻页器、3模鼠标（2.4G/USB能支持到1K回报率） |
| **关键特性** | 通用HID，3模鼠标，高回报率                                   |
| **参考文档** | [HID 开发文档](https://doc.zh-jieli.com/AW31/zh-cn/master/module_demo/hid/index.html) |



---

## 七、编译指南

### 7.1 编译命令速查表

以下命令在 SDK 根目录下执行：

| 目标 | 芯片 | 应用 | 命令 |
|------|------|------|------|
| AW31N | bd47 | transfer | `make aw31n_transfer ` |
| AW31N | bd47 | hid | `make aw31n_hid` |
| **全部** | 全部 | 全部 | `make all` |
| **清理全部** | 全部 | 全部 | `make clean` |

### 7.2 清理单个工程

```bash
make clean_aw31n_transfer    # 清理 aw31n_transfer 编译产物
make clean_aw31n_hid         # 清理 aw31n_hid 编译产物
```

### 7.3 Linux 编译注意事项

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

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

### 7.4 常见编译错误

| 错误提示 | 解决方法 |
|---------|---------|
| `clang: command not found` | 未安装杰理编译工具链，或环境变量未配置 |
| `Too many open files` | Linux 下执行 `ulimit -n 8096` 增加文件描述符限制 |
| `cannot find -lxxx` | 缺少对应的 `.a` 库文件，检查 `apps/include_lib/liba/*/flash` 目录 |
| `undefined reference to ...` | 功能裁剪配置未包含对应模块，检查 `lib_*_config.c` |

---

## 八、烧录与升级

### 8.1 首次烧录

1. **连接硬件**：将开发板通过 USB 或 UART 连接到 PC
2. **进入编程模式**：按住开发板上的烧录按键，然后复位或重新上电
3. **打开 USB 升级工具**：启动 `isd_download.exe`
4. **选择固件**：选择编译生成的 `.hex` 文件
5. **开始烧录**：点击下载按钮，等待烧录完成

> **⚠️ 注意**：烧录前请确保 USB 升级工具正确连接且目标板已进入编程模式。
> 详细的 INI 配置（apps/app/post_build/bd**/flash/isd_config_ini.c）说明请参考：[下载脚本配置文档](https://doc.zh-jieli.com/Tools/zh-cn/mass_prod_tools/common_function/index.html)

### 8.2 OTA 升级

支持单备份和双备份蓝牙 OTA 升级，详见：[OTA 开发文档](https://doc.zh-jieli.com/AW31/zh-cn/master/update/update_main.html)

---

## 九、配置说明

### 9.1 功能裁剪配置

在每个应用工程的 `config/` 目录下，通过以下配置文件可以灵活裁剪 SDK 功能，减小固件体积：

```bash
apps/demo/hid/config/
├── lib_btctrler_config.c    # 蓝牙控制器配置
├── lib_btstack_config.c     # 蓝牙协议栈配置
├── lib_driver_config.c      # 驱动模块配置
├── lib_profile_config.c     # 蓝牙 Profile 配置
├── lib_system_config.c      # 系统模块配置
├── lib_update_config.c      # 升级模块配置
└── log_config.c             # 日志输出配置
```

### 9.2 板级配置

每个板级目录下的 `board_xxx_cfg.h` 包含：

- **引脚映射**：UART / SPI / I2C / GPIO 等外设的引脚分配
- **外设使能**：开启或关闭特定外设模块
- **时钟配置**：CPU 频率、外设时钟源

`board_xxx_global_build_cfg.h` 包含：

- **功能开关**：按需启用/禁用特定功能
- **内存配置**：堆栈大小、缓冲池大小

---

## 十、常见问题

### 10.1 开发流程相关

**Q: 如何创建自己的工程？**
A: 复制 `apps/` 下对应应用的 `board/` 目录中与芯片型号最接近的板级配置，修改 `board_xxx_cfg.h` 中的引脚和外设配置即可。

**Q: 如何添加新的芯片型号支持？**
A: 在 `cpu/` 下创建对应的平台目录，提供 `liba/` 库文件和 `tools/` 烧录工具，然后在 `apps/demo/*/board/` 下添加对应的板级目录。

### 10.2 编译相关

**Q: Windows 下编译报错 `make` 不是有效命令？**
A: 使用 `tools/make_prompt.bat` 进入预配置的命令行环境，该脚本已设置好所有环境变量和 `make` 的路径。

**Q: 如何加快编译速度？**
A: 使用 `-j` 参数进行并行编译，如 `make aw31n_transfer -j4`。

### 10.3 调试技巧

- **串口日志**：通过 `log_config.c` 配置日志输出等级和通道
- **GPIO  Debug**：利用空闲 GPIO 输出调试波形，测量时序
- **更多问题**：请参考 [FAQ](https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK/issues)

---

## 十一、社区与支持

### 技术交流

| 平台 | 群号/链接 | 状态 |
|------|-----------|------|
| **钉钉 1群** | `90400000565` | ✅ 可加入 |

### 资源链接

| 资源 | 链接 |
|------|------|
| 📖 **在线文档中心** | [doc.zh-jieli.com/AW31](https://doc.zh-jieli.com/AW31/zh-cn/master/index.html) |
| 📄 **芯片数据手册** | [SoC 数据手册扼要](https://doc.zh-jieli.com/vue/#/docs/aw31n) / [本地下载](./doc) |
| 📚 **SDK 版本历史** | [版本发布记录](https://doc.zh-jieli.com/AW31/zh-cn/master/other/version/index.html) |
| 🏗️ **SDK 架构文档** | [模块架构说明](https://doc.zh-jieli.com/AW31/zh-cn/master/getting_started/sdk_app_develop/index.html) |
| 🛒 **开发板购买** | [杰理官方店铺](https://shop321455197.taobao.com/) |
| 🐛 **问题反馈** | [Gitee Issues](https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK/issues) |

---

## 十二、认证信息

本 SDK 支持的蓝牙协议栈已通过蓝牙 SIG 认证：

| 蓝牙规范 | QDID | 认证链接 |
|---------|------|---------|
| Core v5.4 | QDID 222830 | [查看认证详情](https://launchstudio.bluetooth.com/ListingDetails/193923) |

---

## 十三、免责声明

`fw-AW31N_BLE_SDK` 支持 AW31N 系列芯片开发。AW31N 系列芯片支持通用蓝牙常见应用，可作为开发、评估、样品及量产使用，对应 SDK 版本请见 [Tags](https://github.com/Jieli-Tech/fw-AW31N_BLE_SDK/tags) 和 [Releases](https://gitee.com/Jieli-Tech/fw-AW31N_BLE_SDK/tags)。

---

<div align="center">
  <sub>Copyright © 2024-2026 珠海杰理科技股份有限公司. All rights reserved.</sub>
</div>