项目初始化

安装 bun https://bun.com/docs/installation#windows

powershell -c "irm bun.sh/install.ps1|iex"

检查bun是否正确安装

& "$env:USERPROFILE\.bun\bin\bun" --version

添加bun到系统路径

[System.Environment]::SetEnvironmentVariable(
  "Path",
  [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
  [System.EnvironmentVariableTarget]::User
)

安装项目依赖

bun install

运行 dev项目

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:

  {
    "type": 0x01,
    "state": 0x00 // 0:未激活, 1:已激活
  }
  

4.2.2 协议版本 (0x07)

• 设备 -> APP:

  {
    "type": 0x07,
    "version": "2024.01"
  }
  

4.2.3 时间同步 (0x08)

• APP -> 设备:

  {
    "type": 0x08,
    "year": 2024,
    "mon": 1,
    "day": 1,
    "hour": 12,
    "min": 0,
    "mes": 0
  }
  

4.2.4 设备信息上报 (0x0D)

• 设备 -> APP:

  {
    "type": 0x0d,
    "allspace": 1000,
    "freespace": 500,
    "devname": "Loom",
    "size": 0,           // 0:圆屏, 1:方屏
    "brand": 5
  }
  

4.2.5 身份核对 (0x0E)

• APP -> 设备 (发送 12位码):

  {
    "type": 0x0e,
    "IdCheck": "xxxxxxxxxxxx"
  }
  

• 设备 -> APP (返回结果):

  {
    "type": 0x0e,
    "Ret": 1 // 0:错误, 1:正确
  }