This is a straightforward guide to getting the Home Assistant Connect ZWA-2 working with Home Assistant by running Z-Wave JS UI on a Ugreen NAS via Docker. I wrote this primarily as documentation for myself, but figured the knowledge might help someone else working through the same setup.

Hardware Setup

The Connect ZWA-2 is built on Home Assistant's second-generation platform, prioritizing high performance and openness. It's the first Z-Wave product in the 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 your Connect ZWA-2 into the NAS. Use a USB extension cable if possible—this improves signal quality by positioning the stick away from interference sources.

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: Ensure your persistent storage directory exists with mkdir -p /volume1/docker/zwave-store. This directory stores your Z-Wave network configuration, device database, security keys, and settings. Without it, you'll lose configuration 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 is the Z-Wave JS UI web interface. Port 3000 is the WebSocket server for Home Assistant integration. The device mapping connects the physical USB device to /dev/zwave inside the container. The volume mount persists configuration to your NAS.

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.

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.). This ensures legal compliance and optimal performance. Using the wrong region can cause communication issues or violate regulations.

Connect to Home Assistant: In Z-Wave JS UI, navigate to Settings → Home Assistant and enable WS Server. Note the WebSocket URL: ws://<YOUR_NAS_IP>:3000. In Home Assistant, go to Settings → Devices & Services, click Add Integration, search for Z-Wave JS, and enter the WebSocket URL. Home Assistant will connect and begin discovering devices.

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). Devices will automatically appear in Home Assistant once paired.

Troubleshooting & Maintenance

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. Without backups, you'll need to re-pair all devices if the container is lost. 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.

You're now ready to build your Z-Wave smart home network. The Z-Wave JS UI acts as the bridge between your ZWA-2 and Home Assistant via WebSocket, handling all the mesh network communication while Home Assistant provides the automation platform.