# E104-BT12USP 网关协议文档

## 协议格式

根据亿佰特官方 danglo 工具配置文件分析，网关使用两种 HCI 协议格式：

### 1. 网关配置命令（E9 FF 格式）

用于网关本身的配置和管理。

**格式**：
```
E9 FF [OPCODE(1)] [LEN(1)] [PAYLOAD...]
```

**响应格式**：
```
91 [OPCODE(1)] [LEN(1)] [PAYLOAD...]
```

**网关配置操作码**：
| OPCODE | 功能 | 说明 |
|--------|------|------|
| 0x01 | GATEWAY_RESET | 网关复位 |
| 0x02 | GATEWAY_VERSION | 获取版本 |
| 0x0C | PROV_GET_STS | 获取配网状态 |
| 0x10 | PROV_START | 开始配网 |
| 0x11 | PROV_STOP | 停止配网 |
| 0x12 | PROV_SCAN | 扫描设备 |
| 0x20 | CFG_NETKEY | 配置网络密钥 |
| 0x21 | CFG_APPKEY | 配置应用密钥 |

### 2. Mesh 数据命令（E8 FF 格式）

用于发送和接收 Mesh 网络数据。

**格式**：
```
E8 FF [固定字段 (6 字节)] [目标地址 (2)] [操作码 (2)] [参数...]
```

**固定字段**：通常为 `00 00 00 00 00 00` 或 `00 00 00 00 02 01`

**示例**：
```
# 获取开关状态（单播地址 0x0000）
E8 FF 00 00 00 00 00 00 02 00 82 01

# 配置 NetKey（添加到索引 0x000）
E8 FF 00 00 00 00 00 00 02 00 80 40 00 00 [16 字节网络密钥]
```

## Mesh 操作码

### 通用开关（Generic OnOff）
| 操作码 | 功能 |
|--------|------|
| 0x8201 | ONOFF_GET |
| 0x8202 | ONOFF_SET |
| 0x8203 | ONOFF_SET_UNACK |
| 0x8204 | ONOFF_STATUS |

### 灯光（Light Lightness）
| 操作码 | 功能 |
|--------|------|
| 0x824B | LIGHTNESS_GET |
| 0x824C | LIGHTNESS_SET |
| 0x824F | LIGHTNESS_LINEAR_GET |
| 0x8250 | LIGHTNESS_LINEAR_SET |
| 0x8257 | LIGHTNESS_RANGE_GET |
| 0x825B | LIGHTNESS_RANGE_SET |

### 配置（Configuration）
| 操作码 | 功能 |
|--------|------|
| 0x8040 | CFG_NETKEY_ADD |
| 0x8041 | CFG_NETKEY_DEL |
| 0x8045 | CFG_NETKEY_UPDATE |
| 0x8000 | CFG_APPKEY_ADD |
| 0x8003 | CFG_APPKEY_UPDATE |
| 0x803D | CFG_MODEL_APP_BIND |
| 0x801B | CFG_SUB_ADD (订阅组) |
| 0x801C | CFG_SUB_DEL (删除订阅) |

### VENDOR 命令（亿佰特自定义）
| 操作码 | 功能 |
|--------|------|
| 0xC111 | VENDOR_ONOFF_GET |
| 0xC211 | VENDOR_ONOFF_SET |
| 0xC311 | VENDOR_ONOFF_SET_UNACK |

**VENDOR 命令格式**：
```
E8 FF [固定字段] [目标地址] [元素地址] C2 11 02 C4 02 [01/00] 00
                                                         ^
                                                         |
                                                    01=ON, 00=OFF
```

## 配网流程

### 步骤 1: 配置网关（使用 danglo 工具）

网关首次使用时，必须通过 danglo 工具配置配网参数：
1. 连接网关
2. 进入 PROV 选项卡
3. 设置 Network Key、App Key、Network ID、IV Index
4. 点击 PROV 写入网关

### 步骤 2: 在 HA 中配置

在 HA 集成配置中输入与 danglo 工具相同的参数。

### 步骤 3: 扫描设备

发送扫描命令后，网关会广播配网信标，设备响应后上报：
```
+EVENT=PROV,device_joined,<mac>,<element_count>
```

### 步骤 4: 配网设备

对扫描到的设备发送配网启动命令。

### 步骤 5: 绑定 App Key

配网完成后，绑定 App Key 到设备。

### 步骤 6: 配置订阅（分组）

将设备的 Model 订阅到组地址，实现组控制。

## 组地址规划

| 用途 | 地址范围 | 说明 |
|------|----------|------|
| 全局广播 | 0xFFFF | 所有设备 |
| 未使用 | 0x0000-0xBFFF | 预留给单播地址 |
| 自定义组 | 0xC000-0xCFFF | 用户自定义分组 |
| SIG 组 | 0xD000-0xDFFF | SIG 标准组 |
| 虚拟地址 | 0xF000-0xFFFF | 虚拟地址 |

## 常见问题

### 1. 扫描不到设备

- 确认设备已进入配网模式（通常是设备上电后或长按重置按钮）
- 确认网关已配置配网参数（使用 danglo 工具）
- 确认网关和设备在有效范围内（建议 1-3 米）

### 2. 设备无法控制

- 确认设备已完成配网
- 确认 App Key 已绑定
- 确认 Model 已订阅组地址或单播地址正确

### 3. 低功耗设备无法接收组消息

低功耗设备需要将 Lightness Model 和 Vendor Model 分配到同一组：
```
# 添加 Lightness Model 到组
E8 FF 00 00 00 00 00 00 02 00 80 1B 02 00 01 C0 00 10

# 添加 Vendor Model 到同一组
E8 FF 00 00 00 00 00 00 02 00 80 1B 02 00 01 C0 11 02 00 00
```

---

**文档版本**: 1.0
**最后更新**: 2026-04-17
**参考**: tl_node_gateway.ini (亿佰特官方配置文件)