%E8%93%9D%E7%89%99%E8%BF%9E%E6%8E%A5%E6%96%B9%E6%A1%88%E4%B8%8E%E6%B5%81%E7%A8%8B.md

# 蓝牙连接方案与流程

本文档说明车机端（ESP32）蓝牙是如何建立连接、以及连接后的处理流程。基于 NimBLE 协议栈，作为 GATT 从机（Server），等待手机 APP 连接。

---

## 一、整体架构

- 协议栈：NimBLE（ESP-IDF 组件）
- 角色：BLE 从机（Peripheral / Server）
- 设备名：ESP32（宏 DEVICE_NAME）
- 主服务 UUID：0xFFFF
- 连接方式：可连接广播，手机端发起连接

---

## 二、系统启动与 BLE 初始化顺序

```
app_main()
  ├── 事件组创建 (system_event_group)
  ├── LCD / LVGL / SPIFFS / 动画任务 等初始化
  └── ble_main()   // 蓝牙入口
        ├── NVS 初始化、表情包存储加载
        ├── nimble_port_init()                    // NimBLE 端口初始化
        ├── ble_gatts_count_cfg(gatt_svr_svcs)    // 统计 GATT 服务
        ├── ble_gatts_add_svcs(gatt_svr_svcs)     // 注册 GATT 服务与特征
        ├── nimble_host_config()                  // 配置主机（reset_cb, sync_cb）
        ├── nimble_port_freertos_init(nimble_host_task)  // 启动 NimBLE 主机任务
        ├── xTaskCreate(notification_task)        // 通知发送任务
        └── xTaskCreate(sentinel_task)            // 哨兵模式任务
```

说明：GATT 服务在 `ble_main()` 里完成注册，NimBLE 主机在独立任务中运行；主机同步完成后会触发 `sync_cb`，再开始广播。

---

## 三、GATT 服务与特征定义

在 `ble.c` 中通过 `gatt_svr_svcs[]` 定义：

| 类型     | UUID   | 说明                     | 权限 / 属性 |
|----------|--------|--------------------------|-------------|
| 主服务   | 0xFFFF | 自定义主服务             | -           |
| 特征 TX  | 0xFF01 | 可读可写，APP 写、车机收 | READ, WRITE |
| 特征 RX  | 0xFF02 | 只读，APP 读             | READ        |
| 特征 NOTIFY | 0xFF03 | 通知，车机主动推给 APP | READ, NOTIFY, WRITE + CCCD(0x2902) |

- APP 下发指令：写 **TX (0xFF01)**，车机在 `gatt_svr_chr_access` 里收到后调用 `ble_data_ansy()` 解析协议。
- 车机上报数据：通过 **NOTIFY (0xFF03)** 发送协议帧；只有 APP 对 NOTIFY 特征的 CCCD 写入 0x0001 后，车机才能成功发通知。

---

## 四、广播与连接建立流程

### 4.1 主机同步完成后（ble_app_on_sync）

1. 推断本机地址类型：`ble_hs_id_infer_auto()`
2. 设置设备名：`ble_svc_gap_device_name_set("ESP32")`
3. 开始广播：`ble_app_advertise()`

### 4.2 广播内容（ble_app_advertise）

- 广播数据（Advertising Data）：
  - 设备名：ESP32（完整名）
  - 标志：可发现、不支持 BR/EDR
  - 16bit UUID：0xFFFF（完整列表）
- 扫描响应（Scan Response）：发射功率（自动）
- 广播参数：
  - 可连接、可发现（通用）
  - 使用快速广播间隔（BLE_GAP_ADV_FAST_INTERVAL1）
  - 信道：0x07（3 个广播信道）
  - 超时：永久（BLE_HS_FOREVER）
- 连接与广播事件通过回调：`ble_gap_event()` 处理

### 4.3 连接建立（BLE_GAP_EVENT_CONNECT）

当手机 APP 发起连接且 status == 0 时：

1. 置 `is_connected = true`
2. 保存 `conn_handle = event->connect.conn_handle`
3. 置系统事件：`set_system_event(BLE_CONNECTED_BIT)`
4. 可选：`ble_gap_conn_find()` 打印连接间隔/延迟/超时

若 status != 0（连接失败），则重新调用 `ble_app_advertise()` 继续广播。

---

## 五、连接后的业务处理流程

### 5.1 事件传递链

```
BLE 连接成功 (ble_gap_event)
  → set_system_event(BLE_CONNECTED_BIT)

main_task (main.c) 中 wait_system_event(..., BLE_CONNECTED_BIT, ...)
  → 收到 BLE_CONNECTED_BIT
  → xTaskNotify(notification_task_handle, BLE_SEND_VERSION, eSetBits)
  → xTaskNotify(notification_task_handle, BLE_SEND_EMOJI_USING, eSetBits)
```

即：连接成功只置位事件位；由主任务统一检测后，通过任务通知让“通知任务”发送“首次连接”的数据。

### 5.2 通知任务（notification_task）对 BLE_SEND_VERSION 的处理

当收到 BLE_SEND_VERSION 时，依次发送（协议帧，见《蓝牙指令测试文档》）：

1. **get_system_ok 帧（2.1A）**：系统就绪
2. **brightness 帧（2.2A）**：当前亮度（默认 50，0–100）
3. **version 帧（2.3A）**：固件版本号

发送前会置 `notify_enabled = 1`，以便通过 `send_protocol_frame()` 走 NOTIFY 特征下发。若 APP 尚未订阅 NOTIFY，底层可能发送失败或 APP 收不到，通常建议 APP 在连接后尽快订阅 NOTIFY 再请求或等待上述三条。

### 5.3 APP 主动请求系统信息（get_sys_info 0x0010）

- APP 通过 **TX (0xFF01)** 下发 get_sys_info 指令。
- 车机在 `ble_data_ansy.c` 中解析到 `get_sys_info` 后，同样通过：
  - `xTaskNotify(notification_task_handle, BLE_SEND_VERSION, eSetBits)`
- 通知任务再次发送上述 2.1A / 2.2A / 2.3A 三帧，实现“按需上报”版本与亮度。

### 5.4 订阅通知（BLE_GAP_EVENT_SUBSCRIBE）

- APP 对 NOTIFY 特征的 CCCD(0x2902) 写入 0x0001 时，会触发 BLE_GAP_EVENT_SUBSCRIBE。
- 代码中根据 `attr_handle == notify_char_handle` 更新：`notify_enabled = (cur_notify || cur_indicate)`。
- 此后所有通过 `send_protocol_frame()` 的下发（版本、亮度、OTA 进度、WiFi 状态等）才会真正通过 NOTIFY 推送到 APP。

---

## 六、连接断开与重连

### 6.1 断开（BLE_GAP_EVENT_DISCONNECT）

1. 置 `is_connected = false`、`notify_enabled = false`、`conn_handle = 0`
2. 根据 `event->disconnect.reason` 打日志（如认证失败、超时、用户断开等）
3. 再次调用 `ble_app_advertise()` 开始广播，等待下次连接

### 6.2 广播结束（BLE_GAP_EVENT_ADV_COMPLETE）

若当前未连接（`!is_connected`），会再次调用 `ble_app_advertise()`，保证持续可被发现、可连接。

---

## 七、流程简图（连接与首次上报）

```
[ 车机 ]                           [ 手机 APP ]

  ble_main()
    → 注册 GATT (0xFFFF, TX/RX/NOTIFY)
    → 启动 NimBLE 主机任务
    → 创建 notification_task / sentinel_task

  ble_app_on_sync()
    → 设置设备名 "ESP32"
    → ble_app_advertise()  // 开始广播

  ------------ 手机扫描并发起连接 ------------

  BLE_GAP_EVENT_CONNECT (status=0)
    → is_connected = true, conn_handle 保存
    → set_system_event(BLE_CONNECTED_BIT)

  ------------ 主任务事件循环 ------------

  main_task: wait_system_event() 得到 BLE_CONNECTED_BIT
    → xTaskNotify(BLE_SEND_VERSION)
    → xTaskNotify(BLE_SEND_EMOJI_USING)

  notification_task: 收到 BLE_SEND_VERSION
    → notify_enabled = 1
    → send get_system_ok 帧
    → send brightness 帧
    → send version 帧
    （通过 NOTIFY 特征 0xFF03 发送，需 APP 已订阅 CCCD）

  ------------ 之后 ------------

  APP 写 TX(0xFF01) 下发指令
    → gatt_svr_chr_access(W RITE) → ble_data_ansy()
    → 解析协议并执行（表情/亮度/日期/OTA/哨兵等）

  车机需要上报时（OTA 进度、WiFi 状态等）
    → notification_task 收到对应 Notify 位
    → send_xxx_frame() → send_protocol_frame() → NOTIFY(0xFF03)
```

---

## 八、关键代码位置（便于对照）

| 流程环节           | 文件         | 函数/位置说明 |
|--------------------|-------------|----------------|
| BLE 入口           | main.c      | app_main() 中调用 ble_main() |
| BLE 初始化与 GATT 注册 | ble.c       | ble_main() |
| 主机同步与开始广播 | ble.c       | ble_app_on_sync() → ble_app_advertise() |
| 广播参数与启动     | ble.c       | ble_app_advertise()，ble_gap_adv_start(..., ble_gap_event, ...) |
| 连接/断开/订阅事件 | ble.c       | ble_gap_event()，case BLE_GAP_EVENT_* |
| 连接成功置位事件   | ble.c       | BLE_GAP_EVENT_CONNECT 内 set_system_event(BLE_CONNECTED_BIT) |
| 主任务处理连接事件 | main.c      | main_task() 中 event_bits & BLE_CONNECTED_BIT → xTaskNotify(BLE_SEND_VERSION / BLE_SEND_EMOJI_USING) |
| 首次版本/亮度上报  | ble.c       | notification_task() 中 bits & BLE_SEND_VERSION |
| APP 写 TX 收数据   | ble.c       | gatt_svr_chr_access()，BLE_CHAR_UUID_TX 的 WRITE → ble_data_ansy() |
| get_sys_info 触发上报 | ble_data_ansy.c | get_sys_info 分支中 xTaskNotify(..., BLE_SEND_VERSION) |
| CCCD 订阅更新      | ble.c       | gatt_svr_chr_access() 写 CCCD(0x2902)，以及 BLE_GAP_EVENT_SUBSCRIBE 中更新 notify_enabled |

---

## 九、小结

- 车机作为 BLE 从机，上电后完成 NimBLE 与 GATT 注册，在主机同步完成后开始可连接广播。
- 手机连接后，通过事件位 BLE_CONNECTED_BIT 驱动主任务通知 notification_task，发送版本、亮度、get_system_ok；APP 也可通过 get_sys_info 指令再次请求同一套上报。
- 所有车机→APP 的协议帧均通过 NOTIFY 特征(0xFF03) 发送，依赖 APP 订阅 CCCD；APP→车机指令通过写 TX 特征(0xFF01) 下发，由 ble_data_ansy 解析并执行。

如需调整“连接后何时发版本/亮度”或“是否在订阅后再发”，只需修改 main_task 对 BLE_CONNECTED_BIT 的处理，或增加在 BLE_GAP_EVENT_SUBSCRIBE 中触发 BLE_SEND_VERSION 的逻辑即可。