docs: 添加协议格式文档

根据亿佰特官方配置文件 (tl_node_gateway.ini) 分析：
- 网关配置命令：E9 FF 格式
- Mesh 数据命令：E8 FF 格式
- 响应格式：91 开头

包含完整的操作码列表、配网流程、组地址规划

custom_components/sigmesh_gateway/hci_gateway.py

@@ -3,9 +3,10 @@
 根据亿佰特 E104-BT12USP 网关的 HCI 协议实现通信。
 该网关使用 HCI 数据包格式，不是 AT 命令。
 
-协议格式根据 danglo 工具日志分析：
+协议格式根据 danglo 工具配置文件分析：
-- 命令：E9 FF [OPCODE(1)]
+- 网关配置命令：E9 FF [OPCODE(1)] [LEN(1)] [PAYLOAD...]
-- 响应：91 [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 数据
 
-    # 事件
+# HCI 数据包格式
-    EVENT_PROV_DEVICE = 0x40  # 配网设备事件
+HCI_CMD_PREFIX = b"\xe9\xff"  # 网关配置命令头
-    EVENT_MESH_DATA = 0x41  # Mesh 数据事件
+HCI_RSP_PREFIX = b"\x91"  # 网关响应头
-
+HCI_MESH_PREFIX = b"\xe8\xff"  # 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"
 
 
 def build_hci_command(opcode: int, payload: bytes = b"") -> bytes:

docs/协议格式.md

@@ -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 (亿佰特官方配置文件)