# 项目初始化

安装 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:正确
  }
  ```