# BLE JSON 通讯模块开发计划

> 新增功能，保留原有 BluFi 配网等全部功能不变。

---

## 一、功能定位

在现有 BluFi 蓝牙配网基础上，**新增**一个自定义 BLE GATT Service，使用 JSON 格式进行设备与 App 之间的双向通讯。

- BluFi 配网模块（`bluetooth_provisioning.*`）：**完全保留，不做任何修改**
- 新 BLE JSON 通讯模块（`ble_service.*`）：独立注册 GATTS App，与 BluFi 共存

### 共存原理

```
Bluedroid GATTS 栈（已配置 max_profiles=8）
  ├── App 0: BluFi Service (UUID: 0xFFFF)    ← 已有，不动
  └── App 1: JSON Service  (UUID: 0xAB00)    ← 新增
```

两个 App 独立回调、独立 handle，共享同一个 Bluedroid 栈和 BLE 连接。

---

## 二、底层传输参数约束

| 参数 | 值 | 说明 |
|------|-----|------|
| 默认 MTU | 23 bytes | BLE 标准默认值 |
| 协商目标 MTU | **512 bytes** | `esp_ble_gatt_set_local_mtu(512)` |
| ATT 协议头开销 | 3 bytes | 固定开销 |
| **单包最大有效载荷** | **509 bytes** | 512 - 3 |
| 广播包最大长度 | 31 + 31 bytes | ADV + SCAN RSP |
| BLE 协议版本 | 4.2 | BLE 5.0 已关闭（BluFi 兼容） |
| 最大连接数 | 4 (CONFIG_BT_ACL_CONNECTIONS) | 当前 BluFi 占 1 |

---

## 三、GATT Service 设计

```
Custom JSON Communication Service
│
├── Service UUID: 0xAB00 (Primary Service)
│
├── Characteristic 1: JSON_WRITE (App → 设备)
│   ├── UUID:        0xAB01
│   ├── Properties:  WRITE
│   ├── Permissions: ESP_GATT_PERM_WRITE
│   └── Max Value:   512 bytes
│
├── Characteristic 2: JSON_NOTIFY (设备 → App)
│   ├── UUID:        0xAB02
│   ├── Properties:  NOTIFY | READ
│   ├── Permissions: ESP_GATT_PERM_READ
│   ├── Max Value:   512 bytes
│   └── Descriptor:  CCCD (0x2902, 2 bytes, 用于开启/关闭 NOTIFY)
│
└── Characteristic 3: JSON_STATUS (设备状态被动读取，可选)
    ├── UUID:        0xAB03
    ├── Properties:  READ
    ├── Permissions: ESP_GATT_PERM_READ
    └── Max Value:   512 bytes
```

---

## 四、JSON 消息格式

### 4.1 公共格式

**请求（App → 设备）：**
```json
{"cmd":"xxx","id":1,"data":{...}}
```

**响应（设备 → App）：**
```json
{"cmd":"xxx","id":1,"code":0,"data":{...}}
```

**主动推送（设备 → App，无 id）：**
```json
{"cmd":"event","data":{"type":"xxx",...}}
```

### 4.2 固定开销

| 字段 | 占用 | 说明 |
|------|------|------|
| `{"cmd":""}` | 10 bytes | 命令名空壳 |
| `,"id":1` | 7 bytes | 消息 ID（1~999） |
| `,"data":{}` | 10 bytes | 数据域空壳 |
| `,"code":0` | 9 bytes | 响应码（仅响应） |
| **请求固定开销** | **~27 bytes** | 留给 data 约 482 bytes |
| **响应固定开销** | **~36 bytes** | 留给 data 约 473 bytes |

---

## 五、逐条命令参数与大小计算

### 5.1 set_wifi — WiFi 配置

**方向：** App → 设备

**请求：**
```json
{"cmd":"set_wifi","id":1,"data":{"ssid":"MyHomeWiFi_5G","pass":"myP@ssw0rd123"}}
```

| 字段 | 类型 | 最大长度 | 来源 |
|------|------|---------|------|
| ssid | string | 32 bytes | IEEE 802.11 标准 |
| pass | string | 64 bytes | WPA2 标准 |

**最大请求大小：** 55(框架) + 32(ssid) + 64(pass) = **151 bytes** → 单包 ✅

**响应：**
```json
{"cmd":"set_wifi","id":1,"code":0,"data":{"status":"connecting"}}
```
**大小：** ~60 bytes → 单包 ✅

---

### 5.2 wifi_list — 获取 WiFi 列表

**方向：** App → 设备

**请求：**
```json
{"cmd":"wifi_list","id":2}
```
**大小：** 24 bytes → 单包 ✅

**响应：**
```json
{"cmd":"wifi_list","id":2,"code":0,"data":{"list":[{"s":"MyWiFi","r":-40},{"s":"Office","r":-55}]}}
```

| 字段 | 类型 | 最大长度 | 说明 |
|------|------|---------|------|
| s | string | 32 bytes | SSID 名称 |
| r | number | 4 bytes | RSSI 值 (-100~0) |

**单条记录最大：** ~46 bytes（SSID 32字符时）

**容量计算（可用空间 = 509 - 58 = 451 bytes）：**

| 场景 | 每条大小 | 单包可容纳 |
|------|---------|-----------|
| 典型（SSID ~10字符） | ~25 bytes | ~17 条 |
| 最坏（SSID 32字符） | ~46 bytes | ~9 条 |
| **设计限制** | — | **最多返回 8 条** |

**最大响应大小：** 58(框架) + 8 × 46 = **426 bytes** → 单包 ✅

---

### 5.3 dev_info — 获取设备信息

**方向：** App → 设备

**请求：**
```json
{"cmd":"dev_info","id":3}
```
**大小：** 23 bytes → 单包 ✅

**响应：**
```json
{"cmd":"dev_info","id":3,"code":0,"data":{"model":"Kapi_Rtc","fw":"1.0.0","mac":"AA:BB:CC:DD:EE:FF","board":"movecall-moji-esp32s3","uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}}
```

| 字段 | 类型 | 最大长度 | 说明 |
|------|------|---------|------|
| model | string | 20 bytes | 产品型号 |
| fw | string | 12 bytes | 固件版本 x.x.x |
| mac | string | 17 bytes | MAC 地址 AA:BB:CC:DD:EE:FF |
| board | string | 30 bytes | 板型名称 |
| uuid | string | 36 bytes | 设备 UUID |

**最大响应大小：** ~180 bytes → 单包 ✅

---

### 5.4 status — 获取设备运行状态

**方向：** App → 设备

**请求：**
```json
{"cmd":"status","id":4}
```
**大小：** 21 bytes → 单包 ✅

**响应：**
```json
{"cmd":"status","id":4,"code":0,"data":{"state":"idle","bat":85,"chg":false,"rssi":-45,"vol":70}}
```

| 字段 | 类型 | 最大长度 | 说明 |
|------|------|---------|------|
| state | string | 11 bytes | 设备状态（见状态枚举表） |
| bat | number | 3 bytes | 电池电量 0~100 |
| chg | boolean | 5 bytes | 是否充电中 |
| rssi | number | 4 bytes | WiFi 信号 -100~0 |
| vol | number | 3 bytes | 音量 0~100 |

**设备状态枚举对照：**

| DeviceState 枚举 | JSON 值 | 字节数 |
|------------------|---------|--------|
| kDeviceStateUnknown | `"unknown"` | 7 |
| kDeviceStateStarting | `"starting"` | 8 |
| kDeviceStateWifiConfiguring | `"wifi_config"` | 11 |
| kDeviceStateIdle | `"idle"` | 4 |
| kDeviceStateConnecting | `"connecting"` | 10 |
| kDeviceStateListening | `"listening"` | 9 |
| kDeviceStateSpeaking | `"speaking"` | 8 |
| kDeviceStateDialog | `"dialog"` | 6 |
| kDeviceStateUpgrading | `"upgrading"` | 9 |
| kDeviceStateActivating | `"activating"` | 10 |
| kDeviceStateFatalError | `"error"` | 5 |

**最大响应大小：** ~105 bytes → 单包 ✅

---

### 5.5 set_vol — 设置音量

**方向：** App → 设备

**请求：**
```json
{"cmd":"set_vol","id":5,"data":{"vol":80}}
```

| 字段 | 类型 | 范围 | 说明 |
|------|------|------|------|
| vol | number | 0~100 | 音量百分比 |

**最大请求大小：** 37 bytes → 单包 ✅

**响应：**
```json
{"cmd":"set_vol","id":5,"code":0}
```
**大小：** 30 bytes → 单包 ✅

---

### 5.6 iot — 控制 IoT 设备属性

**方向：** App → 设备

**请求：**
```json
{"cmd":"iot","id":6,"data":{"thing":"lamp","prop":"brightness","val":50}}
```

| 字段 | 类型 | 最大长度 | 说明 |
|------|------|---------|------|
| thing | string | 20 bytes | IoT 设备名 (speaker/lamp/screen 等) |
| prop | string | 20 bytes | 属性名 |
| val | number/string/bool | 20 bytes | 属性值 |

**最大请求大小：** ~95 bytes → 单包 ✅

**响应：**
```json
{"cmd":"iot","id":6,"code":0}
```
**大小：** 27 bytes → 单包 ✅

---

### 5.7 reboot — 重启设备

**方向：** App → 设备

**请求：**
```json
{"cmd":"reboot","id":7}
```
**大小：** 22 bytes → 单包 ✅

**响应：**
```json
{"cmd":"reboot","id":7,"code":0}
```
**大小：** 29 bytes → 单包 ✅

---

### 5.8 ota — 检查固件更新

**方向：** App → 设备

**请求：**
```json
{"cmd":"ota","id":8}
```
**大小：** 19 bytes → 单包 ✅

**响应：**
```json
{"cmd":"ota","id":8,"code":0,"data":{"cur":"1.0.0","new":"1.1.0","has_update":true}}
```

| 字段 | 类型 | 最大长度 | 说明 |
|------|------|---------|------|
| cur | string | 12 bytes | 当前版本 |
| new | string | 12 bytes | 最新版本 |
| has_update | boolean | 5 bytes | 是否有更新 |

**最大响应大小：** ~78 bytes → 单包 ✅

---

### 5.9 ping — 心跳保活

**方向：** 双向

**请求：**
```json
{"cmd":"ping","id":9}
```
**大小：** 20 bytes → 单包 ✅

**响应：**
```json
{"cmd":"ping","id":9,"code":0}
```
**大小：** 28 bytes → 单包 ✅

---

### 5.10 event — 设备主动推送

**方向：** 设备 → App（通过 NOTIFY，无 id）

**WiFi 连接成功：**
```json
{"cmd":"event","data":{"type":"wifi_connected","ssid":"Home","ip":"192.168.1.100","rssi":-40}}
```
**最大大小：** ~125 bytes → 单包 ✅

**WiFi 断开：**
```json
{"cmd":"event","data":{"type":"wifi_disconnected","reason":201}}
```
**大小：** ~58 bytes → 单包 ✅

**电池低电量：**
```json
{"cmd":"event","data":{"type":"low_battery","bat":10}}
```
**大小：** ~51 bytes → 单包 ✅

**设备状态变化：**
```json
{"cmd":"event","data":{"type":"state_changed","state":"listening"}}
```
**大小：** ~62 bytes → 单包 ✅

---

## 六、总览表

| # | 命令 | 方向 | 请求最大 | 响应最大 | 单包? |
|---|------|------|---------|---------|-------|
| 1 | `set_wifi` | App→设备 | **151 B** | 60 B | ✅ |
| 2 | `wifi_list` | App→设备 | 24 B | **426 B** (限8条) | ✅ |
| 3 | `dev_info` | App→设备 | 23 B | **180 B** | ✅ |
| 4 | `status` | App→设备 | 21 B | **105 B** | ✅ |
| 5 | `set_vol` | App→设备 | 37 B | 30 B | ✅ |
| 6 | `iot` | App→设备 | 95 B | 27 B | ✅ |
| 7 | `reboot` | App→设备 | 22 B | 29 B | ✅ |
| 8 | `ota` | App→设备 | 19 B | 78 B | ✅ |
| 9 | `ping` | 双向 | 20 B | 28 B | ✅ |
| 10 | `event` | 设备→App | — | **≤125 B** | ✅ |

**结论：MTU=512 时，所有命令均可单包传输，不需要分包机制。**

---

## 七、错误码定义

| code | 含义 | 示例场景 |
|------|------|---------|
| 0 | 成功 | 所有正常响应 |
| 1 | 参数错误 | JSON 格式错误 / 缺少必要字段 |
| 2 | 命令不支持 | 未知的 cmd |
| 3 | 设备忙 | 正在 OTA / 正在配网 |
| 4 | WiFi 连接失败 | SSID 不存在 / 密码错误 |
| 5 | 超时 | 操作超时 |
| 6 | 内部错误 | 设备内部异常 |

**错误响应示例：**
```json
{"cmd":"set_wifi","id":1,"code":4,"msg":"wrong password"}
```

---

## 八、通讯时序示例

### 场景：App 配置 WiFi

```
App                                          设备
 │                                            │
 │──── BLE Connect ──────────────────────────>│
 │<─── MTU Exchange (512) ───────────────────>│
 │──── Enable NOTIFY (write CCCD=0x0001) ───>│
 │                                            │
 │──── WRITE: {"cmd":"status","id":1}        │
 │<─── NOTIFY: {"cmd":"status","id":1,       │
 │       "code":0,"data":{"state":"idle",    │
 │       "bat":85,"chg":false,"rssi":0,      │
 │       "vol":70}}                           │
 │                                            │
 │──── WRITE: {"cmd":"wifi_list","id":2}     │
 │                                   [设备扫描WiFi]
 │<─── NOTIFY: {"cmd":"wifi_list","id":2,    │
 │       "code":0,"data":{"list":[           │
 │       {"s":"Home","r":-40},               │
 │       {"s":"Office","r":-55}]}}           │
 │                                            │
 │──── WRITE: {"cmd":"set_wifi","id":3,      │
 │       "data":{"ssid":"Home",              │
 │       "pass":"123456"}}                   │
 │<─── NOTIFY: {"cmd":"set_wifi","id":3,     │
 │       "code":0,"data":{                   │
 │       "status":"connecting"}}             │
 │                                   [设备连接WiFi]
 │<─── NOTIFY: {"cmd":"event","data":        │
 │       {"type":"wifi_connected",           │
 │       "ssid":"Home",                      │
 │       "ip":"192.168.1.100","rssi":-40}}   │
 │                                            │
```

---

## 九、实现文件清单

| 文件 | 动作 | 说明 |
|------|------|------|
| `main/ble_service.h` | **新增** | BleJsonService 类定义 |
| `main/ble_service.cc` | **新增** | GATT Server 实现 + JSON 收发 |
| `main/ble_service_config.h` | **新增** | UUID / MTU / 超时等配置宏 |
| `main/application.cc` | **修改** | 集成 BleJsonService，注册命令处理回调 |
| `main/application.h` | **修改** | 添加 BleJsonService 成员指针 |
| `main/CMakeLists.txt` | **修改** | 添加 ble_service.cc 到编译列表 |
| `sdkconfig.defaults` | **可能修改** | 若需调整 GATT profile 数量 |
| `bluetooth_provisioning.*` | **不动** | BluFi 配网保持原样 |
| `bluetooth_provisioning_config.h` | **不动** | BluFi 配置保持原样 |

---

## 十、备用分包协议（当前不需要实现）

若未来某条消息超过 509 字节，可启用以下分包协议：

```
分包头 (2 bytes):
  Byte 0: [7:4] 总包数(1~15), [3:0] 当前包号(0~14)
  Byte 1: 0x00=中间包, 0x01=最后一包
  Byte 2~N: JSON 片段

单包判断: 首字节为 '{' (0x7B) → 完整 JSON，无分包头
          首字节非 '{' → 分包数据，需重组
```

当前设计下 WiFi 列表限制 8 条，所有消息均 ≤509 字节，**无需实现分包**。

---

## 十一、依赖与约束

- **JSON 库：** cJSON（项目已有，无需引入新依赖）
- **BLE 栈：** Bluedroid（已启用，与 BluFi 共用）
- **GATT 资源：** max_profiles=8（BluFi 占 1，新模块占 1，富余 6 个）
- **内存：** 8MB PSRAM + 320KB DRAM（JSON 解析开销可忽略）
- **输出格式：** 使用 `cJSON_PrintUnformatted()` 紧凑输出，无空格无换行
- **BLE 回调线程安全：** GATTS 回调中不直接解析 JSON，通过 FreeRTOS 队列转发到应用任务处理