forked from yudi_xiao/expo-ble-app-demo
347 lines
9.2 KiB
Markdown
347 lines
9.2 KiB
Markdown
# 项目初始化
|
||
|
||
安装 bun https://bun.com/docs/installation#windows
|
||
|
||
```powershell
|
||
powershell -c "irm bun.sh/install.ps1|iex"
|
||
```
|
||
|
||
检查bun是否正确安装
|
||
|
||
```powershell
|
||
& "$env:USERPROFILE\.bun\bin\bun" --version
|
||
```
|
||
|
||
添加bun到系统路径
|
||
|
||
```powershell
|
||
[System.Environment]::SetEnvironmentVariable(
|
||
"Path",
|
||
[System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
|
||
[System.EnvironmentVariableTarget]::User
|
||
)
|
||
```
|
||
|
||
安装项目依赖
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
运行 dev项目
|
||
|
||
```bash
|
||
bun run start
|
||
`````
|
||
|
||
# 协议三端通信说明
|
||
|
||
## 1. 数据格式
|
||
|
||
### 1.1 基本帧结构
|
||
|
||
所有数据包遵循以下格式（通常为大端序）：
|
||
|
||
| 字段 (Field) | 长度 (Bytes) | 值 / 说明 |
|
||
|:-------------|:-----------|:----------------|
|
||
| **HEADER** | 3 | `FEDCBA` |
|
||
| **CMD** | 2 | 命令字 (如 `E100`) |
|
||
| **DATA** | n | 数据内容 (0 ~ n 字节) |
|
||
| **CHECKSUM** | 1 | 校验和 |
|
||
| **TAIL** | 2 | `00EF` |
|
||
|
||
### 1.2 错误反馈 (系统级)
|
||
|
||
当接收到的数据包格式错误时，设备会返回以下错误码：
|
||
|
||
| 错误类型 | CMD (上报) | 参数 (DATA) | 完整 HEX 示例 |
|
||
|:------------|:---------|:----------|:----------------------------|
|
||
| HEADER 错误 | `E0E0` | `C0` | `FEDCBA E0E0 C0 00EF` |
|
||
| TAIL 错误 | `E0E0` | `C1` | `FEDCBA E0E0 C1 00EF` |
|
||
| CHECKSUM 错误 | `E0E2` | `C0` | `FEDCBA E0E2 C0 00EF` |
|
||
| CMD 不支持 | `E0E3` | `[CMD]` | `FEDCBA E0E3 [CMD] XX 00EF` |
|
||
|
||
---
|
||
|
||
## 2. 蓝牙通道说明
|
||
|
||
* **OTA 通道**:
|
||
* Write: `ae01`
|
||
* Notify: `ai02` (或 `ae02`)
|
||
* **APP 通信通道**:
|
||
* Write: `ae10` (MTU 建议设置为 517)
|
||
* Notify: `ae02`
|
||
|
||
---
|
||
|
||
## 3. 命令详解
|
||
|
||
### 3.1 绑定 (0xE100)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA E100 E1 00EF`
|
||
* **返回**:
|
||
|
||
| 状态 | CMD | 参数 | 完整 HEX 示例 |
|
||
|:---|:-------|:-----|:----------------------|
|
||
| 成功 | `E1A0` | `81` | `FEDCBA E1A0 81 00EF` |
|
||
| 失败 | `E1A1` | `82` | `FEDCBA E1A1 82 00EF` |
|
||
| 异常 | `E1A2` | `83` | `FEDCBA E1A2 83 00EF` |
|
||
|
||
### 3.2 绑定失败上报 (0xE200)
|
||
|
||
**方向**: APP -> 设备 (通常用于APP端绑定失败后通知设备)
|
||
|
||
* **发送**: `FEDCBA E200 XX 00EF`
|
||
* **返回**:
|
||
|
||
| 状态 | CMD | 参数 | 完整 HEX 示例 |
|
||
|:---|:-------|:-----|:----------------------|
|
||
| 成功 | `E2A0` | `XX` | `FEDCBA E2A0 XX 00EF` |
|
||
| 失败 | `E2A1` | `XX` | `FEDCBA E2A1 XX 00EF` |
|
||
| 异常 | `E2A2` | `XX` | `FEDCBA E2A2 XX 00EF` |
|
||
|
||
### 3.3 写用户 ID (0xE300)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA E300 [UserID] XX 00EF`
|
||
* `UserID`: 用户ID数据
|
||
* **返回**:
|
||
|
||
| 状态 | CMD | 参数 | 完整 HEX 示例 |
|
||
|:------|:-------|:-----|:----------------------|
|
||
| 成功 | `E3A0` | `83` | `FEDCBA E3A0 83 00EF` |
|
||
| 失败 | `E3A1` | `84` | `FEDCBA E3A1 84 00EF` |
|
||
| 异常(空) | `E3A3` | `85` | `FEDCBA E3A3 85 00EF` |
|
||
|
||
### 3.4 查询密锁 (0xE400)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA E400 E4 00EF`
|
||
* **返回**: `FEDCBA E4A0 [TOKEN] XX 00EF`
|
||
* `TOKEN`: 32位 (4字节) 密锁数据。
|
||
|
||
### 3.5 设置时间 (0xE500)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA E500 [Time] XX 00EF`
|
||
* `Time`: 格式 `yyyymmddhhmmss` (14字节 ASCII)
|
||
* **返回**:
|
||
|
||
| 状态 | CMD | 参数 | 完整 HEX 示例 |
|
||
|:---|:-------|:-----|:----------------------|
|
||
| 成功 | `E5A0` | `85` | `FEDCBA E5A0 85 00EF` |
|
||
| 失败 | `E5A1` | `86` | `FEDCBA E5A1 86 00EF` |
|
||
| 异常 | `E5A2` | `87` | `FEDCBA E5A2 87 00EF` |
|
||
|
||
### 3.6 查询固件版本号 (0xE600)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA E600 E6 00EF`
|
||
* **返回**: `FEDCBA E6A0 [Version] XX 00EF`
|
||
* `Version`: 格式 `yyyymmddhh` (10字节 ASCII)
|
||
|
||
### 3.7 查询资源版本号 (0xE700 / 0xD700)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **版本 < V4.0**:
|
||
* 发送: `FEDCBA E700 E7 00EF`
|
||
* 返回: `FEDCBA E7A0 [ResVersion] XX 00EF`
|
||
* **版本 >= V4.0**:
|
||
* 发送: `FEDCBA D700 E7 00EF`
|
||
* 返回: `FEDCBA D7A0 [ResVersion] XX 00EF`
|
||
|
||
### 3.8 设置资源版本号 (0xE800)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA E800 [TT] [ResVersion] XX 00EF`
|
||
* **返回**:
|
||
|
||
| 状态 | CMD | 参数 | 完整 HEX 示例 |
|
||
|:---|:-------|:-----|:----------------------|
|
||
| 成功 | `E8A0` | `88` | `FEDCBA E8A0 88 00EF` |
|
||
| 失败 | `E8A1` | `89` | `FEDCBA E8A1 89 00EF` |
|
||
| 异常 | `E8A2` | `8A` | `FEDCBA E8A2 8A 00EF` |
|
||
|
||
### 3.9 解绑 (0xE900)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA E900 E0 00EF`
|
||
* **返回**: `FEDCBA E9A0 F3 00EF` (解绑成功)
|
||
|
||
### 3.10 下载文件 / OTA (0xEA00)
|
||
|
||
**方向**: APP -> 设备
|
||
此命令流程包含请求传输、数据传输、传输结束、取消传输等状态。
|
||
|
||
#### A. 启动传输请求
|
||
|
||
* **发送**: `FEDCBA EA00 [Type] [NameLen] [Name] [MD5] [Size] XX 00EF`
|
||
* `Type`: 文件类型 (1字节)
|
||
* `NameLen`: 文件名长度 (1字节)
|
||
* `Name`: 文件名 (N字节)
|
||
* `MD5`: 文件校验 (8字节)
|
||
* `Size`: 文件大小 (4字节, 16进制)
|
||
* **返回**:
|
||
|
||
| 状态 | CMD | 说明 | 附加数据 |
|
||
|:------|:-------|:----------|:---------------|
|
||
| 同意传输 | `EAA0` | 准备接收 | `8A` |
|
||
| 失败 | `EAA1` | 拒绝/错误 | `8B` |
|
||
| 异常 | `EAA2` | 参数错误 | `8C` |
|
||
| 文件相同 | `EAA3` | 无需传输 | `8D` |
|
||
| 断点续传 | `EAA4` | 从Offset开始 | `[Offset(4B)]` |
|
||
| OTA回复 | `EAA5` | OTA 错误码 | `[ErrCode]` |
|
||
|
||
#### B. 文件数据传输 (Packet)
|
||
|
||
* **发送**: `FEDCBA EA01 [Seq] [Len] [Data] XX 00EF`
|
||
* `Seq`: 序列号 (2字节)
|
||
* `Len`: 数据长度 (2字节)
|
||
* `Data`: 数据内容
|
||
* **返回 (每包/批量确认)**: `FEDCBA EAA6 [ErrCode] [Seq] [TotalLen] XX 00EF`
|
||
|
||
#### C. 传输完成
|
||
|
||
* **发送**: `FEDCBA EA02 EC 00EF`
|
||
* **返回**:
|
||
* 成功: `FEDCBA EAA7 91 00EF`
|
||
* 失败: `FEDCBA EAA8 [ErrCode] XX 00EF`
|
||
|
||
#### D. 取消传输
|
||
|
||
* **发送**: `FEDCBA EA03 ED 00EF`
|
||
* **返回**: `FEDCBA EAA9 [ErrCode] 8D 00EF`
|
||
|
||
### 3.11 查询设备 OTA 信息 (0xEB00)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **查询 OTA 信息**:
|
||
* 发送: `FEDCBA EB00 E0 00EF`
|
||
* 返回: `FEDCBA EBA0 [Err] [Ver] XX 00EF`
|
||
* **清除 OTA 状态**:
|
||
* 发送: `FEDCBA EB01 EC 00EF`
|
||
* 返回: `FEDCBA EBA7 92 00EF`
|
||
|
||
### 3.12 设备信息查询 (0xED00)
|
||
|
||
**方向**: APP -> 设备
|
||
|
||
* **发送**: `FEDCBA ED00 [TypeMask] XX 00EF`
|
||
* `TypeMask`: 2字节位掩码，每一位代表请求的信息类型。
|
||
* **返回**:
|
||
* 成功: `FEDCBA EDA0 [Data] XX 00EF`
|
||
* 失败: `FEDCBA EDA1 ...`
|
||
* 异常: `FEDCBA EDA2 ...`
|
||
|
||
**支持的信息类型 (Bit定义)**:
|
||
|
||
| Bit | 信息内容 | 长度 (Bytes) | 说明 |
|
||
|:----|:-----------|:-----------|:------------|
|
||
| 0 | 当前电量 | 1 | 0~100 |
|
||
| 1 | 当前音量 | 1 | 0~3 |
|
||
| 2 | SD卡挂载状态 | 1 | 0:未挂载, 1:挂载 |
|
||
| 3 | SD卡总容量 | 4 | 单位 KB |
|
||
| 4 | SD卡剩余容量 | 4 | 单位 KB |
|
||
| 5 | BLE MAC 地址 | 6 | Hex format |
|
||
|
||
---
|
||
|
||
## 4. JSON 协议 (V2)
|
||
|
||
新版协议在原有基础上增加了 JSON 数据传输模式，支持更丰富的信息交互。
|
||
|
||
### 4.1 帧结构 (Frame Structure)
|
||
|
||
V2 协议使用特定的帧头 `0xC7` (App发) / `0xB0` (设备发) 包裹 JSON 数据。
|
||
|
||
| 字段 | 长度 (Bytes) | 说明 |
|
||
|:------------------|:-----------|:--------------------------------------|
|
||
| **HEAD** | 1 | `0xC7` (App->Dev) / `0xB0` (Dev->App) |
|
||
| **TYPE** | 1 | 命令字 (如 `0x0D`) |
|
||
| **Subpage Total** | 2 | 分包总数 (大端) |
|
||
| **Current Page** | 2 | 当前包序号 (大端) |
|
||
| **Data Len** | 2 | 数据长度 (大端) |
|
||
| **DATA** | N | JSON 字符串 (UTF-8) |
|
||
| **CHECKSUM** | 1 | 校验和 (0 - Sum(0...End-1)) |
|
||
|
||
### 4.2 命令定义 (JSON Payload)
|
||
|
||
以下为 Data 字段中的 JSON 内容示例。
|
||
|
||
#### 4.2.1 激活状态 (0x01)
|
||
|
||
* **APP -> 设备**: (查询)
|
||
* **设备 -> APP**:
|
||
```json
|
||
{
|
||
"type": 0x01,
|
||
"state": 0x00 // 0:未激活, 1:已激活
|
||
}
|
||
```
|
||
|
||
#### 4.2.2 协议版本 (0x07)
|
||
|
||
* **设备 -> APP**:
|
||
```json
|
||
{
|
||
"type": 0x07,
|
||
"version": "2024.01"
|
||
}
|
||
```
|
||
|
||
#### 4.2.3 时间同步 (0x08)
|
||
|
||
* **APP -> 设备**:
|
||
```json
|
||
{
|
||
"type": 0x08,
|
||
"year": 2024,
|
||
"mon": 1,
|
||
"day": 1,
|
||
"hour": 12,
|
||
"min": 0,
|
||
"mes": 0
|
||
}
|
||
```
|
||
|
||
#### 4.2.4 设备信息上报 (0x0D)
|
||
|
||
* **设备 -> APP**:
|
||
```json
|
||
{
|
||
"type": 0x0d,
|
||
"allspace": 1000,
|
||
"freespace": 500,
|
||
"devname": "Loom",
|
||
"size": 0, // 0:圆屏, 1:方屏
|
||
"brand": 5
|
||
}
|
||
```
|
||
|
||
#### 4.2.5 身份核对 (0x0E)
|
||
|
||
* **APP -> 设备** (发送 12位码):
|
||
```json
|
||
{
|
||
"type": 0x0e,
|
||
"IdCheck": "xxxxxxxxxxxx"
|
||
}
|
||
```
|
||
* **设备 -> APP** (返回结果):
|
||
```json
|
||
{
|
||
"type": 0x0e,
|
||
"Ret": 1 // 0:错误, 1:正确
|
||
}
|
||
```
|