docs: 添加协议格式文档
根据亿佰特官方配置文件 (tl_node_gateway.ini) 分析： - 网关配置命令：E9 FF 格式 - Mesh 数据命令：E8 FF 格式 - 响应格式：91 开头 包含完整的操作码列表、配网流程、组地址规划
This commit is contained in:
impressionyang
parent
8fa6198d38
commit
a790d6247f
@ -3,9 +3,10 @@
|
||||
根据亿佰特 E104-BT12USP 网关的 HCI 协议实现通信。
|
||||
该网关使用 HCI 数据包格式，不是 AT 命令。
|
||||
|
||||
协议格式根据 danglo 工具日志分析：
|
||||
- 命令：E9 FF [OPCODE(1)]
|
||||
- 响应：91 [OPCODE(1)] [LEN(1)] [PAYLOAD...]
|
||||
协议格式根据 danglo 工具配置文件分析：
|
||||
- 网关配置命令：E9 FF [OPCODE(1)] [LEN(1)] [PAYLOAD...]
|
||||
- Mesh 数据命令：E8 FF [固定字段 (6)] [目标地址 (2)] [OPCODE(2)] [参数...]
|
||||
- 网关响应：91 [OPCODE(1)] [LEN(1)] [PAYLOAD...]
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@ -18,7 +19,7 @@ _LOGGER = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class HciGatewayOp(IntEnum):
|
||||
"""HCI 网关操作码."""
|
||||
"""HCI 网关操作码（E9 FF 格式）."""
|
||||
|
||||
# 网关控制
|
||||
GATEWAY_RESET = 0x01
|
||||
@ -34,22 +35,11 @@ class HciGatewayOp(IntEnum):
|
||||
CFG_NETKEY = 0x20 # 配置网络密钥
|
||||
CFG_APPKEY = 0x21 # 配置应用密钥
|
||||
|
||||
# 数据发送
|
||||
MESH_SEND = 0x30 # 发送 Mesh 数据
|
||||
MESH_RECV = 0x31 # 接收 Mesh 数据
|
||||
|
||||
# 事件
|
||||
EVENT_PROV_DEVICE = 0x40 # 配网设备事件
|
||||
EVENT_MESH_DATA = 0x41 # Mesh 数据事件
|
||||
|
||||
|
||||
# HCI 数据包格式根据 danglo 工具日志：
|
||||
# 命令：E9 FF [OPCODE(1)]
|
||||
# 响应：91 [OPCODE(1)] [LEN(1)] [PAYLOAD...]
|
||||
|
||||
HCI_CMD_PREFIX = b"\xe9\xff"
|
||||
HCI_RSP_PREFIX = b"\x91"
|
||||
HCI_EVT_PREFIX = b"\xe8\xff"
|
||||
# HCI 数据包格式
|
||||
HCI_CMD_PREFIX = b"\xe9\xff" # 网关配置命令头
|
||||
HCI_RSP_PREFIX = b"\x91" # 网关响应头
|
||||
HCI_MESH_PREFIX = b"\xe8\xff" # Mesh 数据命令头
|
||||
|
||||
|
||||
def build_hci_command(opcode: int, payload: bytes = b"") -> bytes:
|
||||
|
||||
172
docs/协议格式.md
Normal file
172
docs/协议格式.md
Normal file
@ -0,0 +1,172 @@
|
||||
# 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 (亿佰特官方配置文件)
|
||||
Loading…
Reference in New Issue
Block a user