Z-Wave JS UI 管理面板使用
什么是 Z-Wave JS UI
Z-Wave JS Integration 在 Home Assistant 里跑在后台，但它有一个独立的 Web UI 来管理 Z-Wave 网络。这个 UI 叫 Z-Wave JS UI（有时也叫 Z-Wave JS Admin），功能包括：
- 可视化网络拓扑图
- 设备实时状态监控
- 手动触发配对/移除设备
- 配置设备参数（Parameter）
- 固件 OTA 升级
- 网络健康检查
- 日志查看
打开 Z-Wave JS UI
Home Assistant OS 用户：
- Settings → Apps → Z-Wave JS → 点击 Open Z-Wave JS UI（或在 App 卡片上点击 Open Web UI）
- 如果 App 没启动，先点 Start
URL：默认是 http://homeassistant.local:8091（如果你改过端口就用你配的端口）
界面总览
Z-Wave JS UI 左侧有几个主要菜单：
- Devices：设备列表（最重要的页面）
- Groups：设备组
- Scenes：场景
- Network map：网络拓扑图（Mesh 网络的可视化）
- Firmware updates：待升级固件列表
- Settings：Z-Wave JS Server 配置
- Logs：实时日志
设备列表页面
每个设备卡片显示：
| 信息 | 含义 |
|---|---|
| 设备名称 | 可编辑 |
| 状态 | Online / Sleeping / Dead |
| 安全 | S0 / S2 Authenticated / S2 Access Control |
| 最后看到的时间 | 设备最后一次通信的时间 |
| LQI | Link Quality Indicator，0~255，数值越低越好 |
设备详情页
点击一个设备进入详情，可以做：
- Basic commands：测试命令（开灯关灯、开门锁等）
- Configuration：设备参数（不同设备有不同配置项）
- Associations：设备组关联（Z-Wave 的直接关联）
- Inclusion information：设备固件版本、协议版本
- Remove device from network：从 Z-Wave 网络移除
网络拓扑图
Network map 是最直观的页面——可以看到整个 Z-Wave Mesh 网络的结构：
- 每个圆点 = 一个设备
- 中心大圆点 = Z-Wave USB 适配器
- 连线 = 设备之间的 Mesh 路由关系
- 颜色 = 信号质量（绿色=好、黄色=中、红色=差）
- 虚线 = 电池设备（终端节点，不能路由）
通过拓扑图可以快速发现信号差的设备、孤立设备、以及路由节点覆盖盲区。
手动添加 / 移除设备
添加
- 左侧菜单 → Devices → 右上角 + Add device
- 选择安全级别（推荐 S2 Authenticated）
- Z-Wave JS 进入 Inclusion 模式（60 秒）
- 设备按出厂说明进入 Pairing 模式
- Z-Wave JS 发现设备 → 弹出 PIN 输入框 → 完成
移除
- Devices 列表 → 找到要移除的设备 → 点击 Remove device
- Z-Wave JS 进入 Exclusion 模式
- 设备按出厂说明进入 Remove from network 模式
- Z-Wave JS 确认移除 → 设备从网络和 Home Assistant 里消失
手动触发（Force Remove）
如果一个设备坏了、找不到了，但还残留在网络列表里，可以 Force Remove：
- Devices → 找到目标设备 → 右上角菜单 → Force Remove
- Z-Wave JS 从网络拓扑里移除它（不要求设备在线）
重要：Force Remove 后这个设备的 Z-Wave 节点 ID 被释放，不能再用这个 ID 重配旧设备。
固件升级
很多 Z-Wave 设备有固件升级能力：
- 左侧菜单 → Firmware updates
- 查看有哪些设备有新固件
- 点击设备 → 可以选择从本地文件升级或 OTA 升级
- 升级过程 3~15 分钟，期间设备离线
升级建议：升级前先备份（Settings → Backup），升级后等待设备重新上线再操作。
常见问题
Z-Wave JS UI 打不开
检查 Z-Wave JS App 是否在 Home Assistant 里运行中。OS 用户去 Settings → Apps 看状态。如果 App 挂了，重启一下。
Z-Wave JS UI 打开但无法连接 Server
Z-Wave JS App 的 Server 地址和端口配错了。Home Assistant OS 默认是 ws://host.docker.internal:3000，Container 部署时要改成 ws://127.0.0.1:3000 或 ws://localhost:3000。
设备状态一直显示 Dead
Dead 表示 Z-Wave JS 连续 N 次（默认 3 次）没有收到设备的通信。常见原因：
- 设备坏了 / 电池死了
- 设备搬到太远的地方
- USB 适配器的天线被遮挡
先尝试把适配器换个位置，或者用 Z-Wave JS UI 的 Force Remove 清理这个节点。