impress_sig_mesh_hacs/docs/UI 使用指南.md

# SigMesh Gateway UI 使用指南

## 概述

SigMesh Gateway 集成提供完整的 Web UI 界面，所有配网和分组管理功能都可以通过 UI 完成，无需使用服务调用或命令行。

## UI 访问方式

### 方式 1: Lovelace Dashboard 卡片（推荐）

将 SigMesh Gateway 面板添加到 Lovelace Dashboard：

1. **复制前端文件**
   ```bash
   # 在 HAOS 上执行
   mkdir -p /config/www/sigmesh_gateway
   cp -r custom_components/sigmesh_gateway/sigmesh-gateway-panel.js /config/www/sigmesh_gateway/
   ```

2. **添加前端模块**

   在 `configuration.yaml` 中添加：
   ```yaml
   frontend:
     extra_module_url:
       - /local/sigmesh_gateway/sigmesh-gateway-panel.js
   ```

3. **重启 Home Assistant**

4. **添加卡片到 Dashboard**
   - 打开 Lovelace Dashboard
   - 点击右下角"编辑仪表板"
   - 点击"+"添加卡片
   - 选择"自定义卡片"
   - 输入卡片类型：`custom:sigmesh-gateway-panel`

### 方式 2: 直接访问 API

配网管理 API 端点：

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/sigmesh_gateway/status` | GET | 获取配网状态和设备列表 |
| `/api/sigmesh_gateway/scan` | POST | 开始扫描设备 |
| `/api/sigmesh_gateway/provisioning` | POST | 配网操作（开始/停止/绑定） |
| `/api/sigmesh_gateway/group` | POST | 分组管理（添加/移除） |
| `/api/sigmesh_gateway/devices` | GET | 获取所有设备详情 |

## UI 界面说明

### 主界面布局

```
┌─────────────────────────────────────────────┐
│ SigMesh Gateway 配网管理        [状态徽章]  │
├─────────────────────────────────────────────┤
│ 设备扫描                                     │
│ [开始扫描] [刷新设备列表]                    │
├─────────────────────────────────────────────┤
│ 已发现设备 (3)                               │
│ ┌─────────────────────────────────────┐    │
│ │ 设备 AA:BB:CC:DD:EE:FF              │    │
│ │ 元素数：2 | 地址：未分配            │    │
│ └─────────────────────────────────────┘    │
│ ┌─────────────────────────────────────┐    │
│ │ 设备 11:22:33:44:55:66              │    │
│ │ 元素数：1 | 地址：0001              │    │
│ └─────────────────────────────────────┘    │
├─────────────────────────────────────────────┤
│ 配网操作 - AA:BB:CC:DD:EE:FF                │
│ [设备地址输入框]                             │
│ [开始配网] [停止配网] [绑定 App Key]        │
├─────────────────────────────────────────────┤
│ 分组管理                                     │
│ [目标地址] [组地址 C001] [Model ID 4352]   │
│ [添加到组] [从组移除]                        │
├─────────────────────────────────────────────┤
│ 组配置 (2)                                   │
│ 组地址：0xC001 | 元素：0000 | Model: 0x1100│
│ 组地址：0xC002 | 元素：0000 | Model: 0x1000│
└─────────────────────────────────────────────┘
```

### 状态说明

| 状态 | 颜色 | 说明 |
|------|------|------|
| idle | 绿色 | 空闲，无配网操作 |
| scanning | 蓝色 | 正在扫描设备 |
| prov_starting | 橙色 | 配网启动中 |
| prov_in_progress | 橙色 | 配网进行中 |
| prov_completed | 绿色 | 配网完成 |
| prov_failed | 红色 | 配网失败 |
| timeout | 红色 | 配网超时 |

## 操作步骤

### 1. 扫描设备

1. 点击"开始扫描"按钮
2. 等待设备上报（扫描中的设备需要处于配网模式）
3. 扫描到的设备会显示在"已发现设备"列表中

### 2. 配网设备

1. 在"已发现设备"列表中点击要配网的设备（选中后高亮）
2. 点击"开始配网"按钮
3. 等待配网完成（状态变为 prov_completed）
4. 可选：点击"绑定 App Key"完成密钥绑定

### 3. 添加到组

1. 选中要配置的设备
2. 在"分组管理"区域配置：
   - 目标地址：自动填充为选中设备的地址
   - 组地址：输入组地址（如 C001）
   - Model ID：输入设备的 Model ID
3. 点击"添加到组"按钮

### 4. 从组移除

1. 选中要配置的设备
2. 配置组地址和 Model ID
3. 点击"从组移除"按钮

## API 使用示例

### 获取状态

```bash
curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8123/api/sigmesh_gateway/status
```

响应示例：
```json
{
  "state": "idle",
  "devices": [
    {"mac": "AA:BB:CC:DD:EE:FF", "elements": 2, "address": null}
  ],
  "groups": [
    {"address": "0xc001", "element_address": "0x0", "model_id": "0x1100"}
  ]
}
```

### 开始扫描

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  http://localhost:8123/api/sigmesh_gateway/scan
```

### 开始配网

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "start", "device_address": "001A"}' \
  http://localhost:8123/api/sigmesh_gateway/provisioning
```

### 添加到组

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "target_address": "001A",
    "group_address": "C001",
    "model_id": 4352,
    "is_sig": true
  }' \
  http://localhost:8123/api/sigmesh_gateway/group
```

## 故障排查

### UI 不显示

**检查步骤**:
1. 确认 JS 文件已复制到正确位置
2. 检查 configuration.yaml 配置
3. 清除浏览器缓存
4. 查看浏览器控制台错误

### API 返回 401

**原因**: 认证失败

**解决**:
1. 确保使用有效的 access token
2. 在 HA Profile 页面生成新的 long-lived token

### 配网超时

**可能原因**:
- 设备未进入配网模式
- 网络密钥配置不正确

**解决**:
1. 参考设备说明书将设备置于配网模式
2. 检查集成配置中的 Network Key

## 配置检查清单

配网前确认以下配置：

- [ ] 串口连接正常
- [ ] Network Key 配置正确（32 字符十六进制）
- [ ] App Key 配置正确（32 字符十六进制）
- [ ] 设备已进入配网模式
- [ ] 组地址在有效范围（0xC000-0xCFFF）

---

**文档版本**: 1.0
**最后更新**: 2026-04-16