Setting Up Home Assistant Connect ZWA-2

This guide covers how I set up Home Assistant Connect ZWA-2 with Z-Wave JS UI on a Ugreen NAS using Docker.

Hardware Setup

The Connect ZWA-2 is the first Z-Wave product in Home Assistant's Connect line. The "2" refers to the second-generation technology platform, not a previous ZWA-1 model.

Prerequisites: Ugreen NAS with Docker installed, SSH access to your NAS, Home Assistant Connect ZWA-2 USB stick, and a USB extension cable (recommended for better signal).

Connect the hardware: Plug the ZWA-2 into the NAS. A USB extension cable helps — it positions the stick away from interference.

Identify the device path: SSH into your NAS and locate your Z-Wave device with ls /dev/serial/by-id/. You should see something like usb-Nabu_Casa_ZWA-XXXXXXXXXX-if00. This is your device identifier.

Create persistent storage: Run mkdir -p /volume1/docker/zwave-store. This directory stores your Z-Wave network config, device database, and security keys. Without it, you lose everything on container restart.

Run the Docker container:

docker run --rm -it \
  -p 8091:8091 -p 3000:3000 \
  --device=/dev/serial/by-id/usb-Nabu_Casa_ZWA-XXXXXXXXXX-if00:/dev/zwave \
  -v /volume1/docker/zwave-store:/usr/src/app/store \
  zwavejs/zwave-js-ui:latest

Port 8091 serves the Z-Wave JS UI web interface. Port 3000 runs the WebSocket server for Home Assistant. The device mapping connects the physical USB to /dev/zwave inside the container.

Software Configuration

Access the web interface: Open http://<YOUR_NAS_IP>:8091/ in your browser. In Settings → Z-Wave, set Serial Port to /dev/zwave and click Save.

Important

Generate security keys: Navigate to Settings → Z-Wave → Security Keys and click Generate for each key type (S0, S2 Access Control, S2 Authenticated, S2 Unauthenticated). Save these keys securely—you'll need them to re-pair devices if you rebuild the container. Without these keys, secure devices cannot be added to your network.

Set RF region: Go to Settings → Z-Wave → RF Manager and set RF Region to your location (USA, EU, ANZ, etc.). Wrong region means communication failures and potential regulatory violations.

Caution

Setting the wrong RF region is not just a configuration error. Z-Wave devices on mismatched frequencies will pair but drop commands intermittently, making debugging extremely frustrating.

Connect to Home Assistant: In Z-Wave JS UI, go to Settings → Home Assistant and enable WS Server. The WebSocket URL is ws://<YOUR_NAS_IP>:3000. In Home Assistant, go to Settings → Devices & Services, add the Z-Wave JS integration, and enter that URL.

Pair Z-Wave devices: In Z-Wave JS UI, click Control Panel → Add Node (or Include), then follow your device's pairing instructions (usually triple-press a button). Paired devices appear in Home Assistant automatically.

Troubleshooting & Maintenance

Warning

Without backups, you'll need to re-pair all devices if the container is lost.

Backup strategy: Back up security keys (Settings → Z-Wave → Security Keys, export as JSON), the entire /volume1/docker/zwave-store directory, and your Home Assistant config. Automate backups with: tar -czf zwave-backup-$(date +%Y%m%d).tar.gz /volume1/docker/zwave-store

Common issues:

Device not found: Check if USB device is visible with ls -la /dev/serial/by-id/ and review kernel logs with dmesg | tail -n 50.

Permission denied: The container needs access to the USB device. Ensure Docker has proper permissions or run with --privileged flag (less secure).

Controller offline: Verify serial port setting is /dev/zwave, check container logs with docker logs <container-id>, restart container, or check USB cable connection.

Home Assistant can't connect: Verify WebSocket server is enabled in Z-Wave JS UI, check firewall rules on NAS allow port 3000, confirm Home Assistant can reach NAS IP, and try ws:// instead of wss:// for local network.

Z-Wave JS UI bridges the ZWA-2 and Home Assistant via WebSocket, handling mesh network communication while Home Assistant handles automation.