595 lines
22 KiB
Markdown
595 lines
22 KiB
Markdown
# BLE 蓝牙传图接口说明
|
||
|
||
> 本文档供 APP 开发工程师参考，描述手机端与 ESP32-S3 设备端的 BLE 图片传输协议。
|
||
> 设备固件：ESP-IDF 5.4 + Bluedroid BLE GATT Server
|
||
> 适用平台：Android + iOS（Flutter 跨平台框架）
|
||
> 更新日期：2026-02-27
|
||
|
||
---
|
||
|
||
## 一、设备信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 设备名称 | `Airhub_xx:xx:xx:xx:xx:xx`（动态名称，后缀为 BLE MAC 地址） |
|
||
| 广播类型 | ADV_IND（可连接、可扫描） |
|
||
| 广播间隔 | 20ms |
|
||
| MTU | 512 字节（设备端已设置，APP 端连接后必须协商） |
|
||
| 屏幕分辨率 | 360×360 圆形 LCD |
|
||
| 图片格式 | JPEG（Baseline） |
|
||
| 存储空间 | SPIFFS 2MB |
|
||
| 厂商标识 | Scan Response 厂商字段 Company ID `0x4C44` + ASCII `dzbj` |
|
||
|
||
### 广播数据结构
|
||
|
||
设备广播分为两部分：
|
||
|
||
**ADV 数据（主广播包）：**
|
||
```
|
||
02 01 06 — Flags: LE General Discoverable + BR/EDR Not Supported
|
||
1C 09 41 69 72 68 75 62 5F xx xx ... — 完整设备名: "Airhub_xx:xx:xx:xx:xx:xx"（长度动态）
|
||
```
|
||
|
||
**Scan Response 数据（扫描响应包）：**
|
||
```
|
||
07 FF 4C 44 64 7A 62 6A — 厂商数据: Company ID 0x4C44 + "dzbj"
|
||
03 03 00 0B — 16-bit 服务 UUID: 0x0B00
|
||
```
|
||
|
||
**设备识别方法**：解析 Scan Response 厂商数据段，跳过前 2 字节 Company ID，取后 4 字节判断是否为 ASCII `dzbj`（`0x64 0x7A 0x62 0x6A`）。也可通过设备名称前缀 `Airhub_` 辅助识别。
|
||
|
||
---
|
||
|
||
## 二、BLE 服务与特征
|
||
|
||
设备仅注册一个自定义服务：
|
||
|
||
```
|
||
图片传输服务 (Service UUID: 0x0B00)
|
||
│
|
||
├── 图片写入特征 (Characteristic UUID: 0x0B01)
|
||
│ ├── 属性: Write + Write Without Response
|
||
│ ├── 最大长度: 512 字节
|
||
│ └── 用途: 传输图片数据（前序帧 + 分包数据帧）
|
||
│
|
||
└── 图片管理特征 (Characteristic UUID: 0x0B02)
|
||
├── 属性: Write + Write Without Response
|
||
├── 最大长度: 24 字节
|
||
└── 用途: 管理命令（设置当前表盘 / 删除图片）
|
||
```
|
||
|
||
> **重要**：
|
||
> - 两个特征均支持 Write 和 Write Without Response，**推荐使用 Write Without Response（writeNoResponse）** 以提升传输速度
|
||
> - APP 端发现服务和特征时，**必须通过 UUID 匹配**（`0x0B00` / `0x0B01` / `0x0B02`），不要用数组索引，不同固件版本的服务/特征顺序可能不同
|
||
> - 16-bit UUID 在 BLE 协议栈中会被扩展为 128-bit 格式，例如 `0x0B00` → `00000b00-0000-1000-8000-00805f9b34fb`
|
||
|
||
---
|
||
|
||
## 三、连接流程
|
||
|
||
```
|
||
1. 初始化蓝牙适配器（openBluetoothAdapter）
|
||
2. 扫描设备（通过厂商数据 "dzbj" 或设备名前缀 "Airhub_" 识别目标设备）
|
||
3. 建立 BLE 连接（createBLEConnection）
|
||
4. 协商 MTU = 512（setBLEMTU） ← 必须！否则每包只能发 20 字节
|
||
5. 发现服务，通过 UUID 匹配 0x0B00
|
||
6. 发现特征，通过 UUID 匹配 0x0B01（写入）和 0x0B02（管理）
|
||
7. 就绪，可以传输图片或发送管理命令
|
||
```
|
||
|
||
---
|
||
|
||
## 四、图片传输协议（写入特征 0x0B01）
|
||
|
||
### 4.1 关键参数
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| MTU | 512 | 设备端设置，APP 端连接后协商 |
|
||
| ATT 有效载荷 | **509** | MTU - 3（ATT 协议头占 3 字节） |
|
||
| 帧头大小 | 2 | 包序号(1) + 结束标志(1) |
|
||
| **CHUNK_SIZE** | **507** | 509 - 2 = 每包最大图片数据 |
|
||
| 写入方式 | writeNoResponse | Write Without Response，不等 ACK |
|
||
| 包间延时 | **5ms** | 防止 Android BLE 队列溢出 |
|
||
| 前序帧延时 | **50ms** | 前序帧后等待设备端建立接收通道 |
|
||
|
||
> **严格约束：每个 BLE 数据包总长不得超过 509 字节（MTU - 3）**
|
||
> 超出此限制时，Android 系统会**静默截断**数据包（不报错），导致设备端接收到的数据不完整，JPEG 解码失败。
|
||
|
||
### 4.2 前序帧（固定 26 字节，每次传图发 1 次）
|
||
|
||
| 字节偏移 | 长度 | 内容 | 说明 |
|
||
|----------|------|------|------|
|
||
| 0 | 1 | `0xFD` | 固定标识：开始图片传输 |
|
||
| 1 ~ 22 | 22 | 文件名 | UTF-8/ASCII 编码，不足 22 字节补 `0x00` |
|
||
| 23 | 1 | `(len >> 16) & 0xFF` | 图片总大小 - 高字节 |
|
||
| 24 | 1 | `(len >> 8) & 0xFF` | 图片总大小 - 中字节 |
|
||
| 25 | 1 | `len & 0xFF` | 图片总大小 - 低字节 |
|
||
|
||
> - 图片大小为 3 字节大端序，最大支持 16,777,215 字节（~16MB）
|
||
> - 文件名**必须以 `.jpg` 结尾**，示例：`face_1708012345.jpg`
|
||
> - 文件名不能超过 22 字节（含扩展名），建议用 `face_时间戳.jpg` 格式
|
||
|
||
### 4.3 数据帧（循环发送直到传完）
|
||
|
||
| 字节偏移 | 长度 | 内容 | 说明 |
|
||
|----------|------|------|------|
|
||
| 0 | 1 | 包序号 | 从 0 递增，溢出后回绕（0~255 循环） |
|
||
| 1 | 1 | 结束标志 | `0x00` = 后续还有数据；`非0` = 最后一包 |
|
||
| 2 ~ N | 最大 **507** | 图片数据 | 实际负载 = 本包总长 - 2 |
|
||
|
||
> 每个数据帧总长 = 2（帧头） + 图片数据 ≤ **509 字节**
|
||
|
||
### 4.4 传输示例
|
||
|
||
以一张 1521 字节的图片 `face_170801.jpg` 为例（CHUNK_SIZE = 507）：
|
||
|
||
```
|
||
第 1 包（前序帧，26 字节）:
|
||
FD 66 61 63 65 5F 31 37 30 38 30 31 2E 6A 70 67 00 ... 00 05 F1
|
||
│ └─────── "face_170801.jpg" + 补零 ──────────────┘ └── 1521 大端序
|
||
└─ 标识符 0xFD
|
||
|
||
[等待 50ms]
|
||
|
||
第 2 包（数据帧，509 字节 = 2 + 507）:
|
||
00 00 [507 字节图片数据]
|
||
│ └─ 未结束
|
||
└─ 包序号 0
|
||
|
||
[等待 5ms]
|
||
|
||
第 3 包（数据帧，509 字节 = 2 + 507）:
|
||
01 00 [507 字节图片数据]
|
||
│ └─ 未结束
|
||
└─ 包序号 1
|
||
|
||
[等待 5ms]
|
||
|
||
第 4 包（数据帧，最后一包，509 字节 = 2 + 507）:
|
||
02 01 [507 字节图片数据]
|
||
│ └─ 结束标志 = 1
|
||
└─ 包序号 2
|
||
```
|
||
|
||
设备端收到结束帧后，自动：写入 SPIFFS → 更新 NVS → 跳转到图片浏览界面显示新图片。
|
||
|
||
---
|
||
|
||
## 五、图片管理命令（管理特征 0x0B02）
|
||
|
||
### 5.1 设置为当前表盘
|
||
|
||
| 字节偏移 | 长度 | 内容 | 说明 |
|
||
|----------|------|------|------|
|
||
| 0 ~ 22 | 23 | 文件名 | 与传输时使用的文件名一致，不足补 `0x00` |
|
||
| 23 | 1 | `0xFF` | 命令标识：设置为当前表盘 |
|
||
|
||
设备端收到后：更新 NVS 记录 → 跳转到图片浏览界面显示指定图片。
|
||
|
||
### 5.2 删除图片
|
||
|
||
| 字节偏移 | 长度 | 内容 | 说明 |
|
||
|----------|------|------|------|
|
||
| 0 ~ 22 | 23 | 文件名 | 要删除的文件名 |
|
||
| 23 | 1 | `0xF1` | 命令标识：删除该图片 |
|
||
|
||
设备端收到后从 SPIFFS 中物理删除该文件。
|
||
|
||
---
|
||
|
||
## 六、APP 端图片处理流程
|
||
|
||
APP 端在传输前**必须对图片进行预处理**，确保设备端能正确解码显示：
|
||
|
||
```
|
||
用户选图/拍照
|
||
│
|
||
▼
|
||
裁剪为 360×360（必须！设备屏幕分辨率）
|
||
│
|
||
▼
|
||
保存为 .jpg 文件（文件名后缀必须是 .jpg）
|
||
│
|
||
▼
|
||
JPEG 压缩（quality: 80~100）
|
||
│
|
||
▼
|
||
读取为 ArrayBuffer
|
||
│
|
||
▼
|
||
BLE 分包传输
|
||
```
|
||
|
||
### 6.1 关键约束
|
||
|
||
| 约束项 | 要求 | 原因 |
|
||
|--------|------|------|
|
||
| 分辨率 | **裁剪**为 360×360 | 设备屏幕为 360×360 圆形 LCD |
|
||
| 格式 | JPEG（Baseline） | 设备端 `esp_jpeg` 仅支持 Baseline JPEG 解码 |
|
||
| 文件后缀 | `.jpg` | 文件后缀决定设备端解码方式 |
|
||
| 压缩质量 | 80~100 | quality < 70 在 360×360 屏幕上画质明显模糊 |
|
||
| 单张大小 | 建议 < 100KB | SPIFFS 总容量 2MB，兼顾传输速度和存储 |
|
||
|
||
> **踩坑提醒**：
|
||
> - 裁剪 ≠ 缩放。使用 `crop` 参数进行裁剪，不要使用 `compressedWidth/compressedHeight`（那是缩放，会变形）
|
||
> - 文件保存时后缀必须是 `.jpg`，如果用 `.png` 后缀，压缩工具会输出 PNG 格式而非 JPEG，设备端无法解码
|
||
> - 不支持 Progressive JPEG，仅支持 Baseline JPEG
|
||
|
||
---
|
||
|
||
## 七、APP 端实现参考代码
|
||
|
||
### 7.1 通过 UUID 匹配服务和特征
|
||
|
||
```javascript
|
||
// 16-bit UUID 在 BLE 协议栈中会被扩展为 128-bit 格式
|
||
// 例如 0x0B00 → "00000b00-0000-1000-8000-00805f9b34fb"
|
||
// Android 和 iOS 均返回 128-bit 格式，统一用小写匹配
|
||
function findByUuid16(list, uuid16) {
|
||
const target = `0000${uuid16.toString(16).padStart(4, '0')}-0000-1000-8000-00805f9b34fb`;
|
||
return list.find(item => item.uuid.toLowerCase() === target.toLowerCase());
|
||
}
|
||
|
||
// 使用示例
|
||
uni.getBLEDeviceServices({
|
||
deviceId: deviceId,
|
||
success(res) {
|
||
const imageService = findByUuid16(res.services, 0x0B00);
|
||
if (!imageService) { console.error('未找到图片服务'); return; }
|
||
|
||
uni.getBLEDeviceCharacteristics({
|
||
deviceId: deviceId,
|
||
serviceId: imageService.uuid,
|
||
success(charRes) {
|
||
const writeChar = findByUuid16(charRes.characteristics, 0x0B01);
|
||
const editChar = findByUuid16(charRes.characteristics, 0x0B02);
|
||
// writeChar.uuid → 用于图片传输
|
||
// editChar.uuid → 用于管理命令
|
||
}
|
||
});
|
||
}
|
||
});
|
||
```
|
||
|
||
### 7.2 BLE 写入封装
|
||
|
||
```javascript
|
||
// 必须使用 writeNoResponse，传输速度更快
|
||
function bleWrite(deviceId, serviceId, characteristicId, buffer) {
|
||
return new Promise((resolve, reject) => {
|
||
uni.writeBLECharacteristicValue({
|
||
deviceId,
|
||
serviceId,
|
||
characteristicId,
|
||
value: buffer,
|
||
writeType: 'writeNoResponse', // 关键！Write Without Response
|
||
success: resolve,
|
||
fail: reject
|
||
});
|
||
});
|
||
}
|
||
|
||
function delay(ms) {
|
||
return new Promise(resolve => setTimeout(resolve, ms));
|
||
}
|
||
```
|
||
|
||
### 7.3 图片选择与预处理
|
||
|
||
```javascript
|
||
// 1. 选择图片并裁剪为 360×360
|
||
function chooseAndCropImage() {
|
||
return new Promise((resolve, reject) => {
|
||
uni.chooseImage({
|
||
count: 1,
|
||
sizeType: ['compressed'],
|
||
sourceType: ['album', 'camera'],
|
||
crop: {
|
||
quality: 100, // 裁剪时不压缩
|
||
width: 360, // 裁剪宽度
|
||
height: 360, // 裁剪高度
|
||
resize: true
|
||
},
|
||
success: (res) => resolve(res.tempFilePaths[0]),
|
||
fail: reject
|
||
});
|
||
});
|
||
}
|
||
|
||
// 2. 保存为 .jpg 后缀文件（关键！决定 compressImage 输出格式）
|
||
function saveAsJpg(tempPath, targetDir) {
|
||
const fileName = `face_${Date.now()}.jpg`; // 必须 .jpg 后缀
|
||
// APP-PLUS 使用 plus.io 复制文件
|
||
// 小程序端使用 getFileSystemManager
|
||
// ... 平台相关实现
|
||
return { fileName, filePath };
|
||
}
|
||
|
||
// 3. JPEG 压缩（输入文件后缀必须是 .jpg）
|
||
function compressToJpeg(srcPath) {
|
||
return new Promise((resolve, reject) => {
|
||
uni.compressImage({
|
||
src: srcPath, // 输入路径后缀必须是 .jpg
|
||
quality: 80, // 80~100 推荐，兼顾画质和体积
|
||
success: (res) => resolve(res.tempFilePath),
|
||
fail: reject
|
||
});
|
||
});
|
||
}
|
||
|
||
// 4. 读取文件为 ArrayBuffer（APP-PLUS 平台）
|
||
function readImageAsArrayBuffer(filePath) {
|
||
return new Promise((resolve, reject) => {
|
||
plus.io.resolveLocalFileSystemURL(filePath, (fileEntry) => {
|
||
fileEntry.file((file) => {
|
||
const reader = new FileReader();
|
||
reader.onloadend = (e) => {
|
||
if (e.target.result) {
|
||
resolve(e.target.result);
|
||
} else {
|
||
reject(new Error('读取文件失败'));
|
||
}
|
||
};
|
||
reader.readAsArrayBuffer(file);
|
||
});
|
||
}, reject);
|
||
});
|
||
}
|
||
```
|
||
|
||
### 7.4 图片分包传输
|
||
|
||
```javascript
|
||
/**
|
||
* 发送图片到设备
|
||
* @param {string} deviceId - BLE 设备 ID
|
||
* @param {string} serviceUuid - 图片服务 UUID (0x0B00 的 128-bit 形式)
|
||
* @param {string} writeUuid - 写入特征 UUID (0x0B01 的 128-bit 形式)
|
||
* @param {string} filename - 文件名（须 .jpg 后缀，最长 22 字节）
|
||
* @param {ArrayBuffer} imageData - JPEG 图片二进制数据
|
||
* @param {function} onProgress - 进度回调 (0~100)
|
||
*/
|
||
async function sendImage(deviceId, serviceUuid, writeUuid, filename, imageData, onProgress) {
|
||
const data = new Uint8Array(imageData);
|
||
const len = data.length;
|
||
|
||
// 1. 发送前序帧（26 字节）
|
||
const header = new Uint8Array(26);
|
||
header[0] = 0xFD;
|
||
for (let i = 0; i < Math.min(filename.length, 22); i++) {
|
||
header[i + 1] = filename.charCodeAt(i);
|
||
}
|
||
header[23] = (len >> 16) & 0xFF;
|
||
header[24] = (len >> 8) & 0xFF;
|
||
header[25] = len & 0xFF;
|
||
|
||
await bleWrite(deviceId, serviceUuid, writeUuid, header.buffer);
|
||
await delay(50); // 等待设备端建立接收通道
|
||
|
||
// 2. 分包发送图片数据
|
||
const CHUNK_SIZE = 507; // (MTU-3) - 2字节帧头 = 509 - 2
|
||
let offset = 0;
|
||
let packetNo = 0;
|
||
|
||
while (offset < len) {
|
||
const remaining = len - offset;
|
||
const chunkLen = Math.min(CHUNK_SIZE, remaining);
|
||
const isEnd = (offset + chunkLen >= len) ? 0x01 : 0x00;
|
||
|
||
const packet = new Uint8Array(2 + chunkLen);
|
||
packet[0] = packetNo & 0xFF;
|
||
packet[1] = isEnd;
|
||
packet.set(data.slice(offset, offset + chunkLen), 2);
|
||
|
||
await bleWrite(deviceId, serviceUuid, writeUuid, packet.buffer);
|
||
await delay(5); // 每包间隔 5ms，防止 Android BLE 队列溢出
|
||
|
||
offset += chunkLen;
|
||
packetNo++;
|
||
|
||
if (onProgress) {
|
||
onProgress(Math.floor(offset / len * 100));
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.5 发送管理命令
|
||
|
||
```javascript
|
||
// 设置为当前表盘
|
||
async function setCurrentFace(deviceId, serviceUuid, editUuid, filename) {
|
||
const cmd = new Uint8Array(24);
|
||
for (let i = 0; i < Math.min(filename.length, 23); i++) {
|
||
cmd[i] = filename.charCodeAt(i);
|
||
}
|
||
cmd[23] = 0xFF;
|
||
await bleWrite(deviceId, serviceUuid, editUuid, cmd.buffer);
|
||
}
|
||
|
||
// 删除图片
|
||
async function deleteImage(deviceId, serviceUuid, editUuid, filename) {
|
||
const cmd = new Uint8Array(24);
|
||
for (let i = 0; i < Math.min(filename.length, 23); i++) {
|
||
cmd[i] = filename.charCodeAt(i);
|
||
}
|
||
cmd[23] = 0xF1;
|
||
await bleWrite(deviceId, serviceUuid, editUuid, cmd.buffer);
|
||
}
|
||
```
|
||
|
||
### 7.6 完整传输流程示例
|
||
|
||
```javascript
|
||
async function uploadWatchFace(deviceId, serviceUuid, writeUuid) {
|
||
// 1. 选图并裁剪为 360×360
|
||
const tempPath = await chooseAndCropImage();
|
||
|
||
// 2. 保存为 .jpg 后缀（关键！）
|
||
const { fileName, filePath } = saveAsJpg(tempPath, imageDir);
|
||
|
||
// 3. JPEG 压缩
|
||
const jpegPath = await compressToJpeg(filePath);
|
||
|
||
// 4. 读取为 ArrayBuffer
|
||
const buffer = await readImageAsArrayBuffer(jpegPath);
|
||
console.log('JPEG 大小:', buffer.byteLength, '字节');
|
||
|
||
// 5. BLE 分包传输
|
||
await sendImage(deviceId, serviceUuid, writeUuid, fileName, buffer, (progress) => {
|
||
console.log('传输进度:', progress + '%');
|
||
});
|
||
|
||
console.log('传输完成，设备将自动显示新图片');
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 八、Android / iOS 兼容注意事项
|
||
|
||
### 8.1 BLE 差异汇总
|
||
|
||
| 差异项 | Android | iOS |
|
||
|--------|---------|-----|
|
||
| MTU 协商 | `setBLEMTU(512)` 通常成功 | 系统自动协商，可能返回不同值，需检查实际 MTU |
|
||
| 广播数据 | 厂商数据在 `advertisData` 中 | 厂商数据可能在 `advertisData` 或其他字段中 |
|
||
| 设备 ID 格式 | MAC 地址格式（如 `D0:CF:13:03:BB:F2`） | UUID 格式（每次配对可能不同） |
|
||
| BLE 队列 | **队列有限，发送过快触发 10007 错误** | 队列较深，但仍建议加延时 |
|
||
| writeNoResponse | 必须加 5ms+ 包间延时 | 可适当减少延时 |
|
||
| 蓝牙缓存 | 无明显缓存问题 | **系统缓存服务/特征列表，设备固件更新后可能读到旧数据** |
|
||
|
||
### 8.2 Android 特别注意
|
||
|
||
1. **BLE 队列溢出（错误码 10007）**：Android 的 BLE 写入队列有限，使用 `writeNoResponse` 时如果发送速度过快，队列满后会返回错误码 10007。**必须在每包之间加 5ms 延时**。
|
||
2. **MTU 协商**：部分 Android 设备可能协商到低于 512 的 MTU。建议协商后读取实际 MTU 值，动态调整 CHUNK_SIZE = `实际MTU - 3 - 2`。
|
||
3. **数据包截断**：如果单包超过 `MTU - 3` 字节，Android **不会报错**，而是**静默截断**数据。这会导致设备端数据不完整，JPEG 解码报错（错误码 6 = JDR_FMT1）。
|
||
|
||
### 8.3 iOS 特别注意
|
||
|
||
1. **蓝牙缓存**：iOS 会缓存 BLE 设备的服务和特征信息。如果设备固件更新了 UUID 或服务结构，iOS 可能仍使用旧缓存。解决方法：关闭 iOS 蓝牙 → 重新打开 → 重连设备。
|
||
2. **设备 ID 不固定**：iOS 返回的 `deviceId` 是系统分配的 UUID，**不是 MAC 地址**，且取消配对后可能变化。不要用 `deviceId` 做设备持久化标识。
|
||
3. **MTU 自动协商**：iOS 不支持手动设置 MTU（`setBLEMTU` 可能不生效），系统自动协商。通常 iOS 12+ 协商到 185~512 之间。
|
||
|
||
### 8.4 统一兼容建议
|
||
|
||
```javascript
|
||
// 连接后获取实际 MTU（兼容 Android/iOS）
|
||
let actualMtu = 512;
|
||
|
||
// Android: 手动协商
|
||
// #ifdef APP-PLUS
|
||
if (uni.getSystemInfoSync().platform === 'android') {
|
||
await new Promise((resolve) => {
|
||
uni.setBLEMTU({
|
||
deviceId,
|
||
mtu: 512,
|
||
success: (res) => { actualMtu = 512; resolve(); },
|
||
fail: () => { actualMtu = 23; resolve(); } // 协商失败用默认 MTU
|
||
});
|
||
});
|
||
}
|
||
// #endif
|
||
|
||
// 动态计算 CHUNK_SIZE
|
||
const CHUNK_SIZE = actualMtu - 3 - 2; // MTU - ATT头(3) - 帧头(2)
|
||
```
|
||
|
||
---
|
||
|
||
## 九、错误排查指南
|
||
|
||
| 现象 | 可能原因 | 解决方案 |
|
||
|------|----------|----------|
|
||
| 设备端 JPEG 解码失败（错误码 6） | 数据包超过 MTU-3 被截断 | 确认 CHUNK_SIZE = MTU-3-2 = 507 |
|
||
| Android 报错 10007 | BLE 写入队列溢出 | 每包间隔加 `await delay(5)` |
|
||
| 设备收到的不是 JPEG | 文件后缀为 `.png` | 保存文件时后缀改为 `.jpg` |
|
||
| 图片模糊 | JPEG quality 过低 | 提高 quality 至 80~100 |
|
||
| 图片变形拉伸 | 使用了缩放而非裁剪 | 使用 `crop` 参数裁剪 360×360 |
|
||
| 传输完成但设备无反应 | 前序帧 `type` 不是 `0xFD` | 检查前序帧第 0 字节 |
|
||
| 找不到服务/特征 | UUID 匹配逻辑错误 | 16-bit UUID 需扩展为 128-bit 后比较 |
|
||
| iOS 发现旧的服务结构 | iOS 蓝牙缓存 | 关闭/重开 iOS 蓝牙后重连 |
|
||
| 传输中断无法恢复 | 无断点续传机制 | 需从头重新传输整张图片 |
|
||
|
||
---
|
||
|
||
## 十、完整时序图
|
||
|
||
```
|
||
APP 端 设备端 (ESP32-S3)
|
||
| |
|
||
|--- BLE 扫描（过滤厂商数据 "dzbj" | 广播中
|
||
| 或设备名前缀 "Airhub_"）------------------->|
|
||
| |
|
||
|--- createBLEConnection --------------------->|
|
||
|<-- 连接成功 ----------------------------------|
|
||
| |
|
||
|--- setBLEMTU(512) [Android] ---------------->|
|
||
|<-- MTU 协商完成 -------------------------------|
|
||
| |
|
||
|--- getBLEDeviceServices -------------------->|
|
||
|<-- 服务列表（匹配 UUID 0x0B00）----------------|
|
||
| |
|
||
|--- getBLEDeviceCharacteristics -------------->|
|
||
|<-- 特征列表（0x0B01 写入 + 0x0B02 管理）--------|
|
||
| |
|
||
|=========== 图片预处理 ==========================|
|
||
| |
|
||
| 裁剪 360×360 → 保存 .jpg → JPEG 压缩 |
|
||
| → 读取为 ArrayBuffer |
|
||
| |
|
||
|=========== 传输图片 ============================|
|
||
| |
|
||
|--- writeNoResponse 0x0B01: |
|
||
| [0xFD + 文件名 + 大小] (26 字节) | 解析前序帧
|
||
| | → malloc 接收缓冲区
|
||
| [等待 50ms] | → fopen 创建文件
|
||
| |
|
||
|--- writeNoResponse 0x0B01: |
|
||
| [0 + 0x00 + 507字节数据] (≤509字节) | 数据帧 1
|
||
| [等待 5ms] |
|
||
|--- writeNoResponse 0x0B01: |
|
||
| [1 + 0x00 + 507字节数据] (≤509字节) | 数据帧 2
|
||
| [等待 5ms] |
|
||
|--- ... |
|
||
|--- writeNoResponse 0x0B01: |
|
||
| [N + 0x01 + 剩余数据] (≤509字节) | 末尾帧
|
||
| | → fwrite 写入 SPIFFS
|
||
| | → 更新 NVS 当前表盘
|
||
| | → 自动跳转图片浏览界面
|
||
| |
|
||
|=========== 管理命令 ============================|
|
||
| |
|
||
|--- writeNoResponse 0x0B02: |
|
||
| [文件名 + 0xFF] (24字节) | 设置为当前表盘
|
||
| | → 跳转图片浏览界面
|
||
| |
|
||
|--- writeNoResponse 0x0B02: |
|
||
| [文件名 + 0xF1] (24字节) | 删除指定图片
|
||
| |
|
||
|--- closeBLEConnection ---------------------->| → 自动恢复广播
|
||
| |
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：协议参数速查
|
||
|
||
```
|
||
设备名称: Airhub_xx:xx:xx:xx:xx:xx（动态，后缀为BLE MAC）
|
||
服务 UUID: 0x0B00 (00000b00-0000-1000-8000-00805f9b34fb)
|
||
写入特征 UUID: 0x0B01 (00000b01-0000-1000-8000-00805f9b34fb)
|
||
管理特征 UUID: 0x0B02 (00000b02-0000-1000-8000-00805f9b34fb)
|
||
MTU: 512
|
||
单包最大值: 509 字节 (MTU - 3)
|
||
CHUNK_SIZE: 507 字节 (509 - 2字节帧头)
|
||
前序帧标识: 0xFD
|
||
设置表盘命令: 0xFF
|
||
删除图片命令: 0xF1
|
||
图片格式: JPEG (Baseline)
|
||
图片分辨率: 360 × 360
|
||
写入方式: writeNoResponse
|
||
包间延时: 5ms (数据帧) / 50ms (前序帧后)
|
||
```
|