结合OPEN AI 整理的教程，方便自己学习CH592
# 01 快速上手与 SDK 结构代码级教程
本文用于第一次接触 `CH592EVT_org` 的开发者，目标是告诉你：应该从哪个官方示例开始复制、每个目录是什么、改代码时先改哪些文件、不要先碰哪些复杂配置。
## 1. BLE 示例根目录
BLE 官方示例主要在：
```text
EVT/EXAM/BLE/
```
这个目录下既有基础角色示例，也有具体应用示例。新项目不要从空目录开始，应复制最接近目标的官方示例。
## 2. 最重要的公共目录
```text
EVT/EXAM/BLE/LIB/
EVT/EXAM/BLE/HAL/
```
含义：
| 目录 | 作用 |
|---|---|
| `LIB` | BLE 协议栈头文件、库文件、ROM 接口 |
| `HAL` | BLE 初始化、TMOS、睡眠、按键、LED、配置宏 |
关键文件：
| 文件 | 作用 |
|---|---|
| `LIB/CH59xBLE_LIB.h` | BLE 协议栈 API、GAP/GATT/HCI 类型和函数声明 |
| `LIB/CH59xBLE_ROM.h` | 使用 ROM 协议栈时的接口入口 |
| `LIB/libCH59xBLE.a` | BLE 协议栈库 |
| `HAL/include/CONFIG.h` | BLE 工程核心配置宏和默认值 |
| `HAL/MCU.c` | `CH59x_BLEInit()` 等底层初始化 |
| `HAL/SLEEP.c` | 睡眠低功耗处理 |
## 3. 示例怎么选
| 目标 | 优先复制哪个示例 |
|---|---|
| 手机连接 CH592F，读写特征，接收 Notify | `Peripheral` |
| CH592F 主动扫描并连接其他 BLE 设备 | `Central` |
| 串口和 BLE 互相透传 | `BLE_UART` |
| 同时做主机和从机 | `CentPeri` |
| 主从并存且多连接 | `MultiCentPeri` |
| 多个主机连接多个从机 | `MultiCentral` |
| 只广播不连接 | `Broadcaster` |
| 只扫描不连接 | `Observer` |
| HID 键盘鼠标 | `HID_Keyboard`、`HID_Mouse` 等 |
| OTA 升级 | `BackupUpgrade_OTA`、`OnlyUpdateApp_*` |
| 吞吐测试 | `SpeedTest_Peripheral`、`SpeedTest_Central` |
新手建议：先跑 `Peripheral`，再学 `Central`，最后学 `BLE_UART` 和多连接。
## 4. Peripheral 工程结构
```text
EVT/EXAM/BLE/Peripheral/
├── APP/
│ ├── peripheral_main.c
│ ├── peripheral.c
│ └── include/peripheral.h
└── Profile/
├── gattprofile.c
└── include/gattprofile.h
```
文件职责：
| 文件 | 作用 |
|---|---|
| `peripheral_main.c` | 系统启动、协议栈初始化、进入 TMOS 主循环 |
| `peripheral.c` | 广播、连接状态、GAP 参数、应用事件、Notify 调用 |
| `peripheral.h` | Peripheral 事件宏、连接结构体、函数声明 |
| `gattprofile.c` | 自定义 GATT 服务属性表、读写回调、Notify 实现 |
| `gattprofile.h` | UUID、特征编号、特征长度、Profile API |
如果你做普通 BLE 外设，主要改这 5 个文件。
## 5. Central 工程结构
```text
EVT/EXAM/BLE/Central/
├── APP/
│ ├── central_main.c
│ ├── central.c
│ └── include/central.h
└── Profile/
└── include/gattprofile.h
```
文件职责：
| 文件 | 作用 |
|---|---|
| `central_main.c` | 系统启动、Central 角色初始化、TMOS 主循环 |
| `central.c` | 扫描、过滤目标、连接、发现服务、读写、订阅 Notify |
| `central.h` | Central 事件宏和函数声明 |
| `gattprofile.h` | 目标服务和特征 UUID |
如果你做主机连接外设，重点改 `central.c` 里的目标地址、服务 UUID、特征 UUID 和 GATT 状态机。
## 6. BLE_UART 工程结构
```text
EVT/EXAM/BLE/BLE_UART/
├── APP/
│ ├── peripheral_main.c
│ ├── peripheral.c
│ ├── app_drv_fifo/
│ └── ble_uart_service/
└── Profile/
└── devinfoservice.c
```
文件职责：
| 文件 | 作用 |
|---|---|
| `peripheral.c` | UART3 初始化、中断、FIFO、BLE 发送事件 |
| `ble_uart_service.c` | RX Write、TX Notify、CCCD |
| `app_drv_fifo.c` | 环形 FIFO 缓冲 |
如果你做串口透传，先不要改 Profile 逻辑，先确认手机写入能从 UART 输出，UART 输入能 Notify 到手机。
## 7. 新建工程标准流程
推荐步骤：
```text
复制最接近的官方示例
-> 改工程名
-> 确认 include path 和源文件列表
-> 先原样编译烧录
-> 用手机工具验证原始功能
-> 改设备名
-> 改广播数据
-> 改 GATT UUID
-> 改业务协议
-> 再优化 MTU、低功耗、多连接
```
不要一开始同时改 UUID、MTU、配对、低功耗和多连接，否则出问题很难定位。
## 8. 复制 Peripheral 后最先改哪几处
### 8.1 改扫描响应名
`peripheral.c`：
```c
static uint8_t scanRspData[] = {
0x12,
GAP_ADTYPE_LOCAL_NAME_COMPLETE,
'S','i','m','p','l','e',' ','P','e','r','i','p','h','e','r','a','l',
};
```
长度字段要跟名字同步改。
### 8.2 改 GAP 设备名
```c
static uint8_t attDeviceName[GAP_DEVICE_NAME_LEN] = "Simple Peripheral";
```
### 8.3 改 Service UUID
`gattprofile.h`：
```c
#define SIMPLEPROFILE_SERV_UUID 0xFFE0
#define SIMPLEPROFILE_CHAR1_UUID 0xFFE1
```
### 8.4 改写入回调
`peripheral.c`：
```c
static void simpleProfileChangeCB(uint8_t paramID, uint8_t *pValue, uint16_t len)
```
手机写 Char3 后，业务逻辑从这里开始。
## 9. 编译前检查清单
| 检查项 | 说明 |
|---|---|
| 新增 `.c` 文件是否加入工程 | 否则链接不到函数 |
| include path 是否包含新头文件目录 | 否则找不到 `.h` |
| 预处理宏是否正确 | 比如 `BLE_BUFF_MAX_LEN`、`HAL_SLEEP` |
| `MEM_BUF` 是否只定义一次 | 多定义或未定义都会出问题 |
| Link.ld 是否来自同类工程 | OTA/IAP 工程尤其要小心 |
| 启动文件是否匹配芯片 | 不要混用不同芯片启动文件 |
## 10. 手机调试工具验证顺序
先验证原始官方示例：
```text
扫描到设备名
连接成功
发现服务
读特征成功
写特征成功
开启 Notify
收到 Notify
断开后能重新广播
```
这 7 步都通，再开始改业务。
## 11. 常用修改点对应文件
| 需求 | 修改文件 |
|---|---|
| 改设备名 | `APP/peripheral.c` |
| 改广播 UUID | `APP/peripheral.c` 和 `Profile/include/gattprofile.h` |
| 改服务 UUID | `Profile/include/gattprofile.h` |
| 新增特征 | `Profile/gattprofile.c/.h` |
| 处理手机写入 | `APP/peripheral.c` 的 Profile 回调 |
| 发送 Notify | `APP/peripheral.c` 调用 Profile Notify API |
| 改连接参数 | `APP/peripheral.c` |
| 改 MTU/缓存 | 工程预处理宏或 `CONFIG.h` |
| 开低功耗 | `CONFIG.h` 和硬件 GPIO 配置 |
## 12. 不建议新手先改的内容
先不要改：
- `CH59x_BLEInit()` 调用顺序。
- `HAL_Init()` 调用顺序。
- `TMOS_SystemProcess()` 主循环。
- 低功耗睡眠。
- 多连接。
- OTA Linker 脚本。
- 32K 时钟。
- 大 MTU 和高吞吐。
先跑通最小闭环，再逐步打开这些功能。
## 13. 最小可交付 BLE 外设闭环
```text
手机扫描到设备
手机连接设备
手机写 Write 特征
MCU 串口打印写入数据
MCU 通过 Notify 回 OK
手机收到 OK
```
只要这个闭环通了，说明启动、广播、连接、GATT、写回调、CCCD、Notify 都已经正常。
## 14. 文档阅读顺序
建议：
1. `01_快速上手与SDK结构.md`
2. `02_启动链路与协议栈配置.md`
3. `03_Peripheral从机开发流程.md`
4. `05_自定义GATT_Profile.md`
5. `06_配对绑定连接与数据传输.md`
6. `04_Central主机开发流程.md`
7. `07_BLE_UART透传工程解析.md`
8. `08_多连接低功耗调试与注意事项.md`
## 15. 常见问题
| 现象 | 先看哪里 |
|---|---|
| 编译失败 | include path、源文件是否加入工程 |
| 烧录后没串口 | `DEBUG`、UART 引脚、`UART1_DefInit()` |
| 扫不到设备 | `Peripheral_Init()`、广播使能、广播包长度 |
| 连接后没服务 | `SimpleProfile_AddService()` |
| 写入没回调 | `SimpleProfile_RegisterAppCBs()` |
| Notify 收不到 | CCCD 是否开启，connHandle 是否正确 |
| 大包失败 | MTU、`BLE_BUFF_MAX_LEN`、分包 |
| 低功耗后异常 | `HAL_SLEEP`、32K、GPIO |
|
|
