# BLE 蓝牙通信接口文档

## MQ2TKill_Project

---

## 一、BLE 基础参数

| 参数 | 值 |
|---|---|
| **Service UUID** | `0000ffe0-0000-1000-8000-00805f9b34fb` |
| **Write Characteristic UUID** | `0000ffe1-0000-1000-8000-00805f9b34fb` |
| **Notify Characteristic UUID** | `0000ffe1-0000-1000-8000-00805f9b34fb` |
| **MTU 请求值** | 512 字节 |
| **连接优先级** | High |

---

## 二、通信帧结构

### 2.1 帧格式 (7+N 字节)

| 字节偏移 | 字段 | 长度 | 说明 |
|---|---|---|---|
| 0 | Header1 | 1B | 帧头1，固定 `0xAA` |
| 1 | Header2 | 1B | 帧头2，固定 `0x55` |
| 2 | Command | 1B | 命令码 |
| 3 | ReadWrite | 1B | 读写标识 |
| 4 | Length | 1B | 数据字段长度 |
| 5 ~ 5+N-1 | Data | NB | 数据字段（可变长度，可空） |
| 5+N ~ 6+N | CRC16 | 2B | CRC16 校验（小端序，校验范围：帧头到数据字段末尾） |

### 2.2 读写标识

| 值 | 含义 |
|---|---|
| `0x00` | 读操作（App 请求读取设备数据） |
| `0x01` | 写操作（App 向设备写入数据） |
| `0x02` | 通知（设备主动向 App 推送数据） |

### 2.3 响应与状态码

设备响应帧中，Data[0] 为状态码：

| 状态码 | 含义 |
|---|---|
| `0x00` | 成功 |
| `0x01` | 参数错误 |
| `0x02` | 权限错误（需管理员权限） |
| `0x03` | 设备忙 |
| `0x04` | 命令不支持 |
| `0x05` | 数据校验失败 |
| `0x06` | 超时 |
| `0x07` | 设备错误 |

---

## 三、命令码详细定义

### 3.1 设备注册与认证类 (0x01-0x0F)

#### 0x01 — 查询设备注册状态

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读（App→设备）** | 无（Length=0） | 查询设备是否已注册 |
| **响应（设备→App）** | 1-2 字节 | `[状态码]` 或 `[状态码][注册标志]` |
| | | 注册标志：`0x00`=未注册, `0x01`=已注册 |

#### 0x02 — 设备注册绑定

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **写（App→设备）** | 用户名(16B ASCII，不足补 `0x00`) | 只发送用户名，不发送密码 |
| **响应** | 状态码 | |

#### 0x03 — 用户登录

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **写（App→设备）** | 用户名(16B) + 解锁状态(1B，固定 `0x01`) | 解锁状态固定为1 |
| **响应** | 状态码 | |

#### 0x04 — 指纹登录使能设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **写（App→设备）** | 用户名(16B) + 使能状态(1B) | `0x00`=禁用, `0x01`=使能 |
| **响应** | 状态码 | |

#### 0x05 — 指纹录制请求

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **写（App→设备）** | 用户名(16B) | 启动硬件指纹注册流程 |
| **响应** | 状态码 | |

#### 0x07 — 查询用户列表

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读（App→设备）** | 无 | |
| **响应（设备→App）** | 用户数量(1-2B) + [用户名(16B) + 指纹ID(1B) + 指纹有效标志(1B)] × N | 每个用户18B |

#### 0x08 — 注销用户

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **写（App→设备）** | 用户名(16B) | |
| **响应** | 状态码 | |

---

### 3.2 设备设置类 (0x10-0x1F)

#### 0x10 — 语言设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读（App→设备）** | 无 | |
| **写（App→设备）** | 1B | `0x00`=英文, `0x01`=中文 |
| **响应** | 状态码 | |

#### 0x11 — 时间设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读（App→设备）** | 无 | |
| **写（App→设备）** | 6B | 年偏移(1) + 月(1) + 日(1) + 时(1) + 分(1) + 秒(1) |
| | | 年 = 实际年份 - 2000（如 2026年 → 0x1A） |
| **响应** | 状态码 | |

#### 0x12 — 定时任务设置

固定 5 个任务槽位（TaskId 0-4），每条任务 7 字节。

每条任务格式：

| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | 开关 | `0x00`=禁用, `0x01`=启用 |
| 1 | 开始小时 | 0-23 |
| 2 | 开始分钟 | 0-59 |
| 3 | 结束小时 | 0-23 |
| 4 | 结束分钟 | 0-59 |
| 5 | 模式 | `0x00`=待机, `0x01`=扫描, `0x02`=消杀 |
| 6 | 重复 | 按位表示星期几（见下表） |

重复位定义：

| 位 | 值 | 含义 |
|---|---|---|
| Bit 0 | `0x01` | 周一 |
| Bit 1 | `0x02` | 周二 |
| Bit 2 | `0x04` | 周三 |
| Bit 3 | `0x08` | 周四 |
| Bit 4 | `0x10` | 周五 |
| Bit 5 | `0x20` | 周六 |
| Bit 6 | `0x40` | 周日 |

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读（App→设备）** | 无 | 返回 35B（7B × 5条任务，按 TaskId 0-4 顺序排列） |
| **写（App→设备）** | 7B/条，可写入1-5条 | 每条写入格式同上（7B，不包含 TaskId）。按 TaskId 0-4 顺序写入，单次最多5条 |
| **响应** | 状态码 | |

---

### 3.3 外设控制类 (0x20-0x3F)

#### 0x20 — LCD 休眠设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 2B | 休眠开关(1) + 休眠时间(1) |
| 休眠开关 | `0x00`=关闭, `0x01`=开启 | |
| 休眠时间 | `0x01`=1分钟, `0x05`=5分钟, `0x0A`=10分钟, `0x1E`=30分钟 | |

#### 0x21 — LCD 亮度设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 2B | 自适应开关(1) + 亮度值(1) |
| 自适应开关 | `0x00`=关闭, `0x01`=开启 | |
| 亮度值 | 10-100（%） | 仅在自适应关闭时有效 |

#### 0x22 — RGB 指示灯控制

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 5B | 开关(1) + R(1) + G(1) + B(1) + 效果模式(1) |

效果模式：

| 值 | 含义 |
|---|---|
| `0x00` | 闪烁 |
| `0x01` | 常亮 |
| `0x02` | 警示 |

#### 0x23 — WIFI 控制

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 65B | 开关(1) + SSID(32B) + 密码(32B) |
| **写** | 动态长度 | 开关(1) + SSID + `\0` + Password + `\0` |

#### 0x24 — BLE 控制（设置广播名称）

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回可变长度 | 设备名称（ASCII，以 `\0` 结尾） |
| **写** | 动态长度 | 设备名称（ASCII） + `\0` |

#### 0x25 — 多媒体控制

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 5B | 视频录制开关(1) + 录制时长(1) + 音效开关(1) + 音效类型(1) + 音量(1, 0-15) |

录制时长：`0x03`=3秒, `0x05`=5秒, `0x0A`=10秒

音效类型：

| 值 | 含义 |
|---|---|
| `0x00` | Arc |
| `0x01` | Hardlight |
| `0x02` | Ion |
| `0x03` | Plasma |
| `0x04` | Quantum |
| `0x05` | Sonic |

#### 0x26 — 补光灯控制

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 3B | 开关(1) + 补光类型(1) + 光照强度(1) |

补光类型：`0x00`=红外光, `0x01`=白光

光照强度：`0x00`=低, `0x01`=中, `0x02`=高

#### 0x27 — 查询补光灯连接状态

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 1B | `0x00`=未连接, `0x01`=已连接 |

#### 0x28 — 可见光激光器控制

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 1B | `0x00`=关闭, `0x01`=开启 |

#### 0x29 — 设备锁定/解锁

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 1B | `0x00`=解锁, `0x01`=锁定 |

---

### 3.4 害虫消灭控制类 (0x40-0x4F)

#### 0x40 — 角度控制

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 2B 小端序 | 角度范围(ushort)，单位 0.1度，范围 1-900（即 0.1° ~ 90°） |

示例：`0x0A 0x00` = 10 = 1.0°

#### 0x41 — 距离控制

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 4B 小端序 | 检测距离(ushort, 0.1米) + 瞄准距离(ushort, 0.1米) |

---

### 3.5 安全设置类 (0x50-0x5F)

#### 0x50 — 毫米波雷达设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 4B | 开关(1) + 灵敏度(1) + 安全距离(2B 小端序) |

灵敏度：`0x00`=低, `0x01`=中, `0x02`=高

安全距离：单位 0.1米，范围 1-100（即 0.1米 ~ 10米）

#### 0x51 — 视觉检测设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 2B | 开关(1) + 灵敏度(1) |

灵敏度：`0x00`=低, `0x01`=中, `0x02`=高

#### 0x52 — 加速度传感器设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 3B | 开关(1) + 灵敏度(1) + 振动阈值(1, 1-255) |

#### 0x53 — 查询加速度传感器数据

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 6B 小端序 | X轴(short, mg) + Y轴(short, mg) + Z轴(short, mg) |

#### 0x55 — 温度监控设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 3B | 告警阈值(1, °C) + 停止阈值(1, °C) + 开关(1) |

#### 0x56 — 环境变化检测 / 激光试射

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 1B | 环境变化状态：`0x00`=无变化, `0x01`=发生变化 |
| **写** | 1B = `0x01` | 触发激光试射测试（3次试射，每次间隔1秒，每次持续10ms） |

---

### 3.6 设备管理类 (0x60-0x6F)

#### 0x60 — 恢复出厂设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **写** | 1B = `0x01` | 需要管理员权限，否则返回状态码 `0x02`（权限错误） |

---

### 3.7 状态查询类 (0xA0-0xBF)

#### 0xA0 — 工作模式设置

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读/写** | 1B | `0x00`=待机, `0x01`=扫描, `0x02`=消杀 |

#### 0xA1 — 查询硬件状态

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 7B | 温度错误(1) + 电机错误(1) + 激光器错误(1) + 视觉错误(1) + 加速度错误(1) + 毫米波错误(1) + 激光雷达错误(1) |

每个错误字段：`0x00`=正常，非0=具体错误类型。

#### 0xA2 — 设备信息

**读操作**返回 72 字节：

| 偏移 | 长度 | 字段 | 说明 |
|---|---|---|---|
| 0-15 | 16B | 设备序列号 | ASCII编码 |
| 16-31 | 16B | 设备型号 | ASCII编码 |
| 32-47 | 16B | 设备ID | ASCII编码 |
| 48-53 | 6B | BLE MAC地址 | |
| 54-59 | 6B | WiFi MAC地址 | |
| 60-63 | 4B 小端序 | 固件版本 | uint32，每位一个数字段，如 1.0.2.3 |
| 64-67 | 4B 小端序 | 硬件版本 | uint32 |
| 68-71 | 4B 小端序 | OTA版本 | uint32 |

**写操作**发送 56 字节：

| 偏移 | 长度 | 字段 | 说明 |
|---|---|---|---|
| 0-15 | 16B | 设备序列号 | |
| 16-31 | 16B | 设备型号 | |
| 32-47 | 16B | 设备ID | |
| 48-51 | 4B 小端序 | 固件版本 | |
| 52-55 | 4B 小端序 | 硬件版本 | |

#### 0xA3 — 查询统计数据

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 28B | 7个 uint32 小端序 |

字段顺序：灭虫数量 + 总工作时间(秒) + 今日工作时间(秒) + 扫描次数 + 激光发射次数 + 蚊虫数据数量 + 日志数量

#### 0xA4 — 蚊虫数据查询

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 4B 小端序 | 数据条数(uint32) |
| **写**（变体1） | 4B 小端序 | 请求最近的 N 条数据，count(uint32) |
| **写**（变体2） | 8B 小端序 | 请求指定范围的数据，StartIndex(uint32) + EndIndex(uint32) |

写操作成功后，设备通过通知（ReadWrite=`0x02`）逐条下发蚊虫数据。

#### 0xA5 — 查询传感器数据

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **读** | 返回 10B 小端序 | 温度(ushort, 0.1°C) + X轴(short, mg) + Y轴(short, mg) + Z轴(short, mg) + 电容电压(ushort, 0.01V) |

---

### 3.8 连接管理类 (0x70-0x7F)

#### 0x70 — 主动断开连接

| 方向 | 数据格式 | 说明 |
|---|---|---|
| **写** | 无（Length=0） | 设备收到此命令后应立即断开 BLE 连接。无响应，因为断开后无法回传 |

---

### 3.9 设备主动通知 (ReadWrite = 0x02)

#### 0x0B — 蚊虫数据通知

通知数据格式：21 字节

| 偏移 | 长度 | 字段 | 说明 |
|---|---|---|---|
| 0 | 1B | 通知类型 | 固定 `0x0B` |
| 1-4 | 4B 小端序 | 数据索引 | uint32 |
| 5-8 | 4B 小端序 | 角度 | int，单位：千分之一度（如 90000 = 90.000°） |
| 9-10 | 2B 小端序 | 距离 | ushort，单位：毫米 |
| 11-12 | 2B 小端序 | 大小 | ushort，单位：毫米 |
| 13-18 | 6B | 时间 | 年(偏移) + 月 + 日 + 时 + 分 + 秒 |
| 19-20 | 2B | 保留 | |

---

### 3.10 OTA 升级类 (0x80-0x9F)

| 命令码 | 名称 | 说明 |
|---|---|---|
| `0x80` | 查询OTA版本信息 | |
| `0x81` | 开始升级 | 启动OTA升级流程 |
| `0x82` | 传输固件数据 | 分片传输固件二进制数据 |
| `0x83` | 结束传输 | 结束OTA数据传输 |
| `0x85` | 取消升级 | 取消当前OTA升级 |

---

## 四、连接流程

```
App                                     Device
 │                                        │
 ├── Initialize Bluetooth ────────────────┤
 │                                        │
 ├── Scan (扫描所有设备) ──────────────────►│
 │◄── 广播数据 ────────────────────────────┤
 │    (Name + Address + RSSI + 制造商数据)   │
 │                                        │
 ├── ConnectToPeripheral ────────────────►│
 │◄── 连接成功 (Connected) ─────────────────┤
 │◄── 发现 Service ────────────────────────┤
 │◄── 发现 Characteristic ─────────────────┤
 │                                        │
 ├── RequestMtu (MTU=512) ───────────────►│
 │◄── MTU 回复 ────────────────────────────┤
 ├── BluetoothConnectionPriority (High) ─►│
 │                                        │
 ├── SubscribeCharacteristic ────────────►│
 │◄── 订阅成功 ────────────────────────────┤
 │                                        │
 ├── 发送指令（队列顺序执行） ───────────────►│
 │◄── 响应 ────────────────────────────────┤
 │                                        │
 │  ...（命令队列继续）...                    │
 │                                        │
 ├── 断开连接 Disconnect ─────────────────►│
 │   先发 0x70 命令                        │
 │◄── 设备主动断开 BLE 连接 ────────────────┤
```

---

## 五、广播数据说明

### MAC 地址解析

广播数据（制造商数据）中，第 2-7 字节包含真实 MAC 地址：

```
bytes[0-1]: 头部（2字节）
bytes[2-7]: MAC 地址（6字节），如 XX:XX:XX:XX:XX:XX
```

> **注意：** iOS 端扫描到的 Address 为系统分配的 UUID，需要通过广播数据中的 MAC 地址来识别设备。Android 端 Address 即是 MAC 地址。

---

## 六、通用约定

1. **字节序**：所有多字节数值均为 **小端序（Little Endian）**，低字节在前。
2. **用户名**：最大长度 **16 字节**，ASCII 编码，不足补 `0x00`。
3. **CRC16**：校验范围从帧头(Header1)到数据字段末尾(Data)，使用标准 CRC16 算法。
4. **指令队列**：App 端使用指令队列顺序执行，上一条指令收到响应（或超时）后才发送下一条。
5. **响应超时**：默认 10 秒。
6. **断开连接流程**：App 先发送 `0x70` 命令 → 设备收到后主动断开 BLE 连接。此命令**无响应帧**。