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. The key is properly mapping the USB device and setting up persistent storage.

1. Overview

The Z-Wave JS UI acts as the bridge between your ZWA-2 and Home Assistant via a WebSocket connection.

2. About the Hardware

Home Assistant Connect ZWA-2

The Connect ZWA-2 is built on Home Assistant's second-generation platform, which prioritizes high performance and openness. It represents a significant leap from the first-generation Connect ZBT-1 (Zigbee). Note that there is no ZWA-1—the "2" designation represents the second generation of technology platform, not the product iteration. All future Connect line products will use this new platform.

Prerequisites

• Ugreen NAS with Docker installed
• SSH access to your NAS
• Home Assistant Connect ZWA-2 USB stick
• USB extension cable (recommended for better signal)

3. Hardware Setup

Step 1: Connect the ZWA-2

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 potential interference sources.

Step 2: Identify the Device Path

SSH into your NAS and locate your Z-Wave device:

ls /dev/serial/by-id/

You should see something like:

usb-Nabu_Casa_ZWA-XXXXXXXXXX-if00

This is your device identifier. The exact string will differ based on your hardware's serial number.

4. Docker Container Setup

Step 3: Create Persistent Storage Directory

Ensure your persistent storage directory exists:

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.

Step 4: Run Z-Wave JS UI Container

Execute this Docker command (replace the device ID with yours from Step 2):

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 breakdown:

• 8091: Z-Wave JS UI web interface
• 3000: WebSocket server for Home Assistant integration

Device mapping:

• Maps the physical USB device to /dev/zwave inside the container

Volume mount:

• Persists configuration to /volume1/docker/zwave-store

If you see Unable to find image 'zwavejs/zwave-js-ui:latest' locally, that's normal—Docker downloads it automatically.

Step 5: Wait for Startup

The container needs a moment to initialize. Watch for log messages indicating the web server is ready.

5. Z-Wave JS UI Configuration

Step 6: Access the Web Interface

Open your browser and navigate to:

http://<YOUR_NAS_IP>:8091/

Replace <YOUR_NAS_IP> with your NAS's actual IP address.

Step 7: Configure Serial Port

In the UI, go to Settings → Z-Wave:

1. Set Serial Port to /dev/zwave
2. Click Save

This tells Z-Wave JS where to find the USB controller.

Step 8: Generate Security Keys

Navigate to Settings → Z-Wave → Security Keys:

1. Click Generate for each key type (S0, S2 Access Control, S2 Authenticated, S2 Unauthenticated)
2. 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.

Step 9: Set RF Region

Go to Settings → Z-Wave → RF Manager:

1. Set RF Region to your location (e.g., USA, EU, ANZ)
2. Click Save

This ensures legal compliance and optimal performance. Using the wrong region can cause communication issues or violate regulations.

Step 10: Verify Controller Status

In the Z-Wave JS UI dashboard, confirm:

• Controller shows as Ready
• Serial port connection is Active
• No error messages in the logs

6. Home Assistant Integration

Step 11: Enable WebSocket Server

In Z-Wave JS UI, navigate to Settings → Home Assistant:

1. Enable WS Server
2. Note the WebSocket URL: ws://<YOUR_NAS_IP>:3000

Step 12: Add Z-Wave JS Integration in Home Assistant

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for Z-Wave JS
4. Select Z-Wave JS
5. Enter WebSocket URL: ws://<YOUR_NAS_IP>:3000
6. Click Submit

Home Assistant will connect to your Z-Wave JS UI instance and begin discovering devices.

7. Pairing Z-Wave Devices

In Z-Wave JS UI:

1. Click Control Panel
2. Click Add Node (or Include)
3. Follow your device's pairing instructions (usually triple-press a button)
4. Wait for device to appear in the UI
5. Name and configure the device

Devices will automatically appear in Home Assistant once paired.

8. Backup Strategy

Critical Data to Backup

1. Security keys: Settings → Z-Wave → Security Keys (export as JSON)
2. Z-Wave network database: The entire /volume1/docker/zwave-store directory
3. Home Assistant config: Standard Home Assistant backup

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

Automated Backup

Add to your NAS backup routine:

tar -czf zwave-backup-$(date +%Y%m%d).tar.gz /volume1/docker/zwave-store

9. Troubleshooting

Device Not Found

# Check if USB device is visible
ls -la /dev/serial/by-id/

# Check kernel logs
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

1. Verify serial port setting: /dev/zwave
2. Check container logs: docker logs <container-id>
3. Restart container
4. Check USB cable connection

Home Assistant Can't Connect

1. Verify WebSocket server is enabled in Z-Wave JS UI
2. Check firewall rules on NAS allow port 3000
3. Confirm Home Assistant can reach NAS IP
4. Try ws:// instead of wss:// for local network

You're now ready to build your Z-Wave smart home network. Start pairing devices through the Z-Wave JS UI control panel, and they'll automatically appear in Home Assistant for automation.