Beginner's Guide to Z-Wave JS in Home Assistant
Z-Wave JS is the official way to add Z-Wave devices to Home Assistant. This guide will help you set up your Z-Wave network step-by-step and covers the important terminology along the way. What Is Z-Wave?
Z-Wave is a wireless smart home protocol designed for reliability, low power usage, and good range. It's commonly used for things like smart switches, wall plugs, sensors, thermostats, and door locks. Z-Wave devices create a mesh network - each device can relay messages for others, extending the range and improving reliability.
- Mesh network: Each powered device boosts the network, helping signals reach further.
- Low interference: Works on a frequency different from Wi-Fi, so it doesn't clog your network.
- Interoperability: Most Z-Wave devices work together, regardless of brand (as long as you use the same frequency region).
What Is Z-Wave JS?
Z-Wave JS is the official integration for Z-Wave in Home Assistant. It's the software that lets Home Assistant "talk" to your Z-Wave USB stick and devices. It replaced older Z-Wave integrations and is faster, more reliable, and supports more devices.
- JS = JavaScript: Z-Wave JS is written in JavaScript (the "JS"), but you don't need to know code to use it.
- Two parts: There's a "Z-Wave JS server" (which handles Z-Wave commands) and the Home Assistant integration (which connects HA to the server).
- Automatic discovery: Z-Wave JS automatically discovers and adds your Z-Wave devices in Home Assistant.
What You'll Need
- A Z-Wave USB stick or controller: This is the hardware that lets your Home Assistant talk to Z-Wave devices. Make sure the frequency (EU/US/AU) matches your region.
- Home Assistant OS or Supervised install: (Other install types can work but setup differs.)
- Z-Wave JS add-on: This is the Z-Wave "server" and must be installed before the Z-Wave JS integration!
Step 1: Plug In Your Z-Wave Controller
- Insert the Z-Wave USB stick into your Home Assistant server (Raspberry Pi, NUC, Home Assistant Yellow, etc.).
-
Home Assistant should detect it automatically, but note the device path if you need to select it manually (e.g.,
/dev/ttyACM0).
Step 2: Install the Z-Wave JS Add-on
- Go to Settings → Add-ons in the Home Assistant sidebar.
- Click Add-on Store and search for "Z-Wave JS".
- Click the add-on, then Install.
- After installation, go to the add-on's Configuration tab, and set the device path to your USB stick (if not auto-detected).
- Start the add-on.
Note: Home Assistant OS/Supervised users should always use the add-on. Only advanced users (Docker/Core) might run the Z-Wave JS server separately.
Step 3: Add the Z-Wave JS Integration
- Go to Settings → Devices & Services.
- Click Add Integration and select "Z-Wave JS".
- Select "Use the Z-Wave JS add-on" when prompted.
- Home Assistant should find your Z-Wave controller and finish the setup automatically.
If you're asked about security keys (for secure devices like locks), Home Assistant can generate them for you if you're setting up for the first time. Save these keys in a safe place.
Step 4: Add Your First Z-Wave Device
- Go to Settings → Devices & Services → Z-Wave JS integration.
- Click Configure and then Add Device.
- Follow the prompts. Put your Z-Wave device in pairing/inclusion mode (check your device manual).
- Home Assistant will automatically discover and add your device. Wait a few moments - battery devices may need to be woken up manually.
SmartStart support: If your device supports SmartStart, you can scan its QR code instead of manually including it.
Basic Terminology (HA vs Z-Wave)
| Z-Wave Term | Home Assistant Term | Definition |
|---|
| Inclusion | Add | Adding a device to your Z-Wave network |
| Exclusion | Remove | Removing a device from your network |
| Replication | Copy | Copying network info between controllers (not supported in HA) |
| Multilevel switch | Light, fan, etc. | Devices with variable output (e.g., dimmers, fans) |
| Barrier operator, window covering | Cover | Garage doors, blinds, etc. |
Troubleshooting and Tips
- Exclusion: If a device won't add, try removing it first - even if brand new.
- Never move the controller: Always include/exclude devices with the controller in its normal place to maintain a healthy mesh network.
- Heal the network: If devices aren't responding, try healing the mesh from the add-on or Z-Wave JS UI.
- Back up your network: Use the integration's backup feature before migrating or making major changes.
Need More?
With the Z-Wave JS add-on and integration installed, you're ready to add, control, and automate your Z-Wave devices in Home Assistant!