# CYD BLE 基础

面向 **ESP32-2432S028（CYD）** 的可复用 BLE 外设模块。显示/触控沿用 [tftest](../tftest) 的 LVGL9 + SoftSPI XPT2046 方案；工程约定见 [CYD_PROJECT_GUIDE.md](../CYD_PROJECT_GUIDE.md)。

## 为什么这样设计

| 方案 | 优点 | 缺点 | 本项目 |
|------|------|------|--------|
| **NimBLE + Nordic UART (NUS)** | 省内存；手机 App 生态成熟；Espressif / Arduino 主流 | 需理解 GATT | **主路径** |
| Bluedroid（Arduino 自带 BLE） | API 常见 | RAM/Flash 占用大，和 WiFi/LVGL 难挤 | 未采用 |
| Espressif BLE Provisioning | 官方配网、可加密 | 要专用 App；本仓 WiFi 已有屏上配网 | 后续可选扩展 |
| Improv WiFi over BLE | Web Bluetooth 友好 | 偏配网场景 | 后续可选 |

对标 [wifitest](../wifitest)：`ble_core` 无 UI 依赖，可拷到任意工程；`ble_ui` 为屏上演示。

## 手机怎么连

1. 安装 **nRF Connect**（Nordic）或 **Serial Bluetooth Terminal** / LightBlue。
2. 扫描广播名 **`CYD-BLE`**，连接。
3. 找到 Nordic UART Service：
   - RX `6E400002-…`：手机 → 板子（Write）
   - TX `6E400003-…`：板子 → 手机（Notify，先 Enable）
4. 默认 **Echo ON**：手机发什么，板子原样 Notify 回来；屏上 **Ping** 会发 `Hello from CYD`。

## 刷写（无需每次编译）

预编译包在 [`firmware/cyd/`](firmware/cyd/)：

```powershell
cd firmware\cyd
.\flash.ps1
# 或
.\flash.ps1 -Port COM3
```

重新打包：

```powershell
.\firmware\export_from_build.ps1
.\firmware\export_from_build.ps1 -SkipBuild
```

源码直接烧录：`pio run -e cyd -t upload`  
串口监视：`pio device monitor -b 460800`

## 接到其它项目

只需带走这些文件（无业务耦合）：

```
include/ble_core.h     # 核心 API（无 LVGL）
src/ble_core.cpp
include/ble_ui.h       # 可选：屏上 UI
src/ble_ui.cpp
```

`platformio.ini` 增加：

```ini
lib_deps =
  h2zero/NimBLE-Arduino@^2.3.2
```

有屏时的最小接入：

```cpp
ble_core_begin();   // 默认广播 CYD-BLE
ble_ui_create();

void loop() {
  ble_core_loop();
  ble_ui_tick();
  // ...
}
```

无屏 / 只要管道：

```cpp
ble_core_begin("MyDevice");
ble_core_set_rx_cb([](const uint8_t *data, size_t len, void *) {
  ble_core_send(data, len);  // 或自己的协议
}, nullptr);
// loop 里 ble_core_loop();
```

宏可覆盖（`build_flags`）：

- `BLE_CORE_DEVICE_NAME` — 默认 `CYD-BLE`
- `BLE_CORE_RX_QUEUE` / `BLE_CORE_RX_MAX` — 收包队列

## 模块划分

- `touch.*` / `pins.h` — CYD 硬件（与 tftest 同校准）
- `ble_core.*` — NimBLE、NUS、广播、收发、断线重广播
- `ble_ui.*` — LVGL 状态页 + Adv / Echo / Ping
- `main.cpp` — 演示入口

## 与 WiFi 的关系

当前演示里 `ble_core_begin()` 会 `WiFi.mode(WIFI_OFF)`，把射频留给 BLE。后续作为基础功能与 WiFi 同开时，参考 Espressif `bleprph_wifi_coex` 与 NimBLE 共存配置，再去掉强制关 WiFi。

## 分区

使用 `min_spiffs.csv`（约 1.9MB APP），避免默认 1.2MB 在 LVGL+NimBLE 下顶满，并为后续 WiFi 共存留余量。

## 硬件

CYD ESP32-2432S028R：ILI9341 240×320，横屏 `LV_DISPLAY_ROTATION_270`（逻辑 320×240）。板载 BLE 4.2，无需外接模块。