impress_sig_mesh_hacs/docs/UI 使用指南.md

SigMesh Gateway UI 使用指南

概述

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

UI 访问方式

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

将 SigMesh Gateway 面板添加到 Lovelace Dashboard：

1. 复制前端文件

   # 在 HAOS 上执行
   mkdir -p /config/www/sigmesh_gateway
   cp -r custom_components/sigmesh_gateway/sigmesh-gateway-panel.js /config/www/sigmesh_gateway/
   

2. 添加前端模块

   在 configuration.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 使用示例

获取状态

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

响应示例：

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

开始扫描

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

开始配网

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

添加到组

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