Z-Wave 与 Z-Wave JS 接入指南
Z-Wave 是什么
Z-Wave 是和 Zigbee 类似的低功耗 Mesh 网络协议，但专注于安全性和可靠性——尤其适合门锁、安防传感器这类必须 100% 可靠的设备。
Home Assistant 通过 Z-Wave JS Integration 接入 Z-Wave 设备。2023 年起 Z-Wave JS 是 Home Assistant 官方唯一支持的 Z-Wave 方案（旧的 zwave 集成已废弃）。
Z-Wave vs. Zigbee vs. Matter
| 特性 | Z-Wave | Zigbee | Matter (Thread) |
|---|---|---|---|
| 频率 | 908MHz / 800MHz | 2.4GHz | 2.4GHz Thread |
| Mesh | ✅ | ✅ | ✅ |
| 品牌 | 几千家 | 很多 | 跨生态 |
| 安装 | Z-Wave JS | ZHA / Z2M | Matter Server |
| Home Assistant 支持 | Z-Wave JS | ZHA / Z2M | Matter Server |
| 适合 | 门锁/安防 | 通用 | 通用 |
| 带宽 | 低 | 中等 | 中等 |
Home Assistant ZWA-2 适配器（官方推荐）
Home Assistant Connect ZWA-2 是官方出品的 Z-Wave 800 系列 USB 适配器：
- Z-Wave 800 系列芯片（比上一代 700 快 30%）
- 支持 S2 加密
- 支持 SmartStart（预配对）
- Home Assistant OS 上即插即用
其他常用 Z-Wave 适配器
| 适配器 | 芯片 | 特点 |
|---|---|---|
| Aeotec Z-Stick Gen5+ | 500 系列 | 最老牌，稳定但老 |
| Aeotec Z-Wave 700 Stick | 700 系列 | 性价比不错 |
| Zooz ZST10 | 700 系列 | 社区口碑好 |
| Nortek GoControl HUSBZB-1 | 500 系列 | 同时支持 Zigbee 和 Z-Wave |
注意：选适配器时注意支持的 Z-Wave 地区频率——美国 908MHz、欧洲 868MHz、中国 800MHz。买错地区的适配器在本国用不了。
安装 Z-Wave JS
Home Assistant OS 用户：
- Settings → Apps → 搜索 Z-Wave JS
- 安装并启动 Z-Wave JS App（这个 App 是 Z-Wave JS Server，Home Assistant 通过它和适配器通信）
- 等 App 启动完成
- Settings → Devices & services → Add integration → 搜索 Z-Wave JS → Configure
- Server 地址填 Z-Wave JS App 显示的地址（默认
ws://host.docker.internal:3000）
Container 用户：需要单独运行 Z-Wave JS Server 容器，然后 Home Assistant 连上去。参考 Z-Wave JS 官方文档。
添加 Z-Wave 设备
Z-Wave JS 内置 Web UI 来管理网络和设备：
- 打开 Z-Wave JS App → Open Z-Wave JS UI
- 左侧菜单 → Devices → + Add device
- 选择 Security Level（推荐 S2 Authenticated）
- Z-Wave JS 进入 Pairing 模式
- 把 Z-Wave 设备放在距离适配器 1 米内（Z-Wave 首次配对必须近场）
- 按设备说明进入 Pairing 模式（通常是按一下重置按钮或插电）
- Z-Wave JS 发现设备 → 弹出安全码输入框（某些设备需要 S2 PIN 码，在说明书上能找到）
- 输入 PIN → 完成配对 → Z-Wave JS 把设备信息推送给 Home Assistant
迁移旧 Z-Wave 网络
如果你之前用的是旧 zwave 集成，可以把网络迁移到 Z-Wave JS：
- 先备份旧 zwave 集成的
network_key（在configuration.yaml里找） - 在 Z-Wave JS 设置里恢复这个 network key
- Home Assistant 重启后设备会自动重新出现（不需要重新配对）
常见问题
Z-Wave 适配器在 Linux 上被识别但 Z-Wave JS 连接不上
Z-Wave JS 需要访问串口设备。Container 部署时确保：
/dev/ttyUSB*或/dev/ttyACM*被正确挂载到容器- 容器有权限访问（
--privileged或--device /dev/ttyUSB0）
Z-Wave 设备响应慢
- 换个位置靠近适配器，第一次配对时一定要近场
- 检查电池——低电量设备响应会变慢
- 700 系列芯片比 500 系列快很多。旧设备可以考虑升级硬件
和 Matter/Zigbee 共存
Z-Wave 是独立的网络，和 Matter、Zigbee 互不干扰——你可以同时用 Z-Wave 门锁 + Zigbee 灯 + Matter 传感器，Home Assistant 全部统一管理。