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 地址。
六、通用约定
- 字节序：所有多字节数值均为 小端序（Little Endian），低字节在前。
- 用户名：最大长度 16 字节，ASCII 编码，不足补
0x00。
- CRC16：校验范围从帧头(Header1)到数据字段末尾(Data)，使用标准 CRC16 算法。
- 指令队列：App 端使用指令队列顺序执行，上一条指令收到响应（或超时）后才发送下一条。
- 响应超时：默认 10 秒。
- 断开连接流程：App 先发送
0x70 命令 → 设备收到后主动断开 BLE 连接。此命令无响应帧。
715921b9f2