715921b9f2
1. 新增多服务器API地址配置 2. 添加OTA推送请求数据结构 3. 实现WiFi模式下直接推送OTA指令逻辑 4. 新增多语言提示文本 5. 补充BLE通信接口文档 6. 修复部分代码格式和跳转逻辑问题
504 lines
15 KiB
Markdown
504 lines
15 KiB
Markdown
# 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 连接。此命令**无响应帧**。
|