dohertj2
80 lines
4.0 KiB
Markdown
80 lines
4.0 KiB
Markdown
# Migrate Z-Wave JS from Raspberry Pi to Home Assistant
|
|
|
|
## Context
|
|
|
|
Z-Wave JS UI currently runs on a Raspberry Pi (10.200.0.190) as a Docker container, connecting to the Z-Net G8 controller at `tcp://10.200.0.106:2001`. Home Assistant then connects to the Raspi's websocket on port 3000. This adds an unnecessary hop and dependency on the Raspi. Since the Z-Net G8 is network-based, HA can connect to it directly.
|
|
|
|
**Current**: HA → ws:3000 → Raspi (Z-Wave JS UI Docker) → tcp:2001 → Z-Net G8
|
|
**Target**: HA → Z-Wave JS add-on (local) → tcp:2001 → Z-Net G8
|
|
|
|
## Current State
|
|
|
|
- **219 Z-Wave entities** in HA
|
|
- **~23 Z-Wave nodes** with custom names (DownstairsBathroomFan, GarageSensor1, etc.)
|
|
- **Security keys** (S0, S2 Auth/Unauth/Access Control, LR) configured in Z-Wave JS UI
|
|
- Device pairings stored in Z-Net G8 NVM (persist regardless of software change)
|
|
- Raspi also runs: zigbee2mqtt, portainer_agent, ouroboros (these stay on the Raspi)
|
|
|
|
## Recommended Approach: Z-Wave JS UI Add-on on HAOS
|
|
|
|
Install the **Z-Wave JS UI community add-on** on HAOS rather than the official Z-Wave JS add-on. Reasons:
|
|
- Same software as current setup → minimal risk
|
|
- Keeps the full web UI for network management
|
|
- HomeSeer docs specifically recommend Z-Wave JS UI for Z-Net controllers
|
|
- Security keys and node names can be migrated directly
|
|
|
|
## Steps
|
|
|
|
### 1. Backup current Z-Wave JS UI on Raspi
|
|
- Create NVM backup from the Z-Wave JS UI web interface (http://10.200.0.190:8091)
|
|
- Copy the store directory from the Raspi container: `sudo docker exec zwavejs2mqtt tar czf /tmp/zwave-store-backup.tar.gz /usr/src/app/store/`
|
|
- Copy backup locally: `scp dohertj2@10.200.0.190:/tmp/zwave-store-backup.tar.gz ./`
|
|
- Save the settings.json (contains security keys and TCP port config)
|
|
|
|
### 2. Stop Z-Wave JS UI on Raspi
|
|
- `ssh dohertj2@10.200.0.190 "sudo docker stop zwavejs2mqtt"`
|
|
- This releases the TCP connection to the Z-Net G8 (only one client can hold it)
|
|
|
|
### 3. Install Z-Wave JS UI add-on on HAOS
|
|
- Via HA web UI: Settings → Add-ons → Add-on Store → search "Z-Wave JS UI" (community add-on)
|
|
- OR via API if possible: add the community add-on repository and install
|
|
|
|
### 4. Configure the add-on
|
|
- Set serial port to `tcp://10.200.0.106:2001`
|
|
- Enter the existing security keys:
|
|
- S2_Unauthenticated: `015BD790CCDB08172CBD12754C73E4D3`
|
|
- S2_AccessControl: `B3F99B99EE958BFAE813A84FD3586E2A`
|
|
- S0_Legacy: `FBF63F5E6515286C3AB8CC9E5F275B46`
|
|
- S2_Authenticated: `67E9ECD830733A1E1BEB22DC0EAA2739`
|
|
- S2_Authenticated_LR: `2176EE246C67320A42F2C0A23932E9B5`
|
|
- S2_AccessControl_LR: `E534F94FCD0BE8B42F056F2F3548002E`
|
|
- Start the add-on
|
|
|
|
### 5. Reconfigure HA Z-Wave JS integration
|
|
- Remove the current zwave_js integration (pointing to ws://10.200.0.190:3000)
|
|
- Re-add it pointing to the local add-on's websocket (ws://localhost:3000 or the add-on's internal URL)
|
|
- Verify all 219 entities are rediscovered with correct names/device assignments
|
|
|
|
### 6. Verify
|
|
- Check all Z-Wave nodes are online in the Z-Wave JS UI add-on
|
|
- Confirm entity count matches (~219)
|
|
- Test a few devices (turn a light on/off, check a sensor reading)
|
|
- Verify automations that use Z-Wave devices still work
|
|
|
|
### 7. Cleanup
|
|
- Remove the zwavejs2mqtt container from the Raspi: `sudo docker rm zwavejs2mqtt`
|
|
- Update `raspi_zwave.md` to reflect new architecture
|
|
|
|
## Risk Mitigation
|
|
|
|
- **Rollback**: If anything goes wrong, stop the HA add-on, restart the Raspi container, and re-point the integration back
|
|
- **Entity IDs**: Removing and re-adding the integration may change entity IDs. HA should re-discover them with the same unique IDs from Z-Wave JS, but automations/dashboards may need updating if not
|
|
- **Cross-VLAN**: HA (10.100.0.40, VLAN 100) must be able to reach Z-Net G8 (10.200.0.106, VLAN 200) on TCP port 2001 — confirmed allowed
|
|
|
|
## Verification
|
|
|
|
1. Entity count: `curl -s http://10.100.0.40:8123/api/template -d '{"template":"{{ integration_entities(\"zwave_js\") | list | length }}"}' ` should return ~219
|
|
2. Z-Wave JS UI web interface accessible from HA add-on
|
|
3. Test device control via HA
|
|
4. Check HA logs for Z-Wave errors
|