This article describes the setup of the Z-Pi 7 in Home Assistant with a Raspberry Pi 3 or 4 with ZWaveJS to MQTT and forms part of the larger Z-Pi 7 user guide.


If you're installing Z-Wave JS to MQTT on a fresh installation. 

These steps assume that you have a fresh install of Home Assistant and have not yet installed Z-WaveJS to MQTT. If you've already installed Z-Wave JS default integration and want to install MQTT, please follow the section "Change to Z-Wave JS to MQTT if you've already installed Z-Wave JS" at the bottom of this article.  

If you have a fresh install, you may follow the steps below to fully install Z-Wave JS to MQTT. 

1. Disable Bluetooth

This is required since both Bluetooth and Z-Pi 7 utilize the same serial port dev/ttyAMA0, in order for Z-Pi 7 to form a connection to your RPi, you must disable Bluetooth.

Before doing this, make sure you've installed Home Assistant OS onto your USB flash drive or microSD card. 

  • Plug your USB flash drive or microSD card with Home Assistant installed into your PC.
  • Open up your Home Assistant drive.
  • Look for "config.txt" and open it.
  • Add this command to the text file depending on the RPi version you have.

    Raspberry Pi 3 

        *Some have reported that this may be "dtoverlay=disable-bt" use this command if the above command isn't working. 

    Raspberry Pi 4

  • Save config.txt
  • Exit config.txt
  • Now safely eject your Flash drive or microSD and remove it from your PC
  • Install your Flash drive or microSD into your RPi and power it up.
  • Wait a few minutes before moving on to the next following steps.

2. Gain access to the Home Assistant community repository first (if you don't have access to ZWaveJS UI already).

  1. Click Setting -> Add-on -> ADD-ON STORE (button at bottom-right)
  2. Click top-right icon (vertical 3 dot icon)
  3. Select Repositories
  4. Input: 
  5. Then click ADD

3. Z-WaveJS UI installation Steps in Home Assistant Add-ons
  1. Click Setting
  2. Click Add-on Store -> ADD-ON STORE (button at bottom-right)
  3. Search for "ZWave"
  4. Click Z-Wave JS UI

  5. Click Install, then wait about 2 minutes and 45 seconds for the installation to complete
  6. Click Start, takes about 24 seconds.
  7. Wait 1 minute for HASS to boot up Z-Wave JS UI
  8. Click "Open Web UI"
  9. Click 3-line icon (Menu) -> Gear Icon (Settings)
  10. Click Zwave
  11. Click Serial port and select /dev/ttyAMA0
  12. Next to Network Key, click the refresh button to add a random security key for S0 Legacy, S2 Authenticated, S2 Unauthenticated, and S2 Access control.

    image 1 - randomize key buttons.

    image 2 - randomized network keys generated.

  13. Click Save (scroll to the very bottom of the settings page)
  14. Click 4 box icon (Control Panel), and see if the driver boots up properly. If your network is ready, you'll see your controller as Node ID 01. 

    (Note - Steps 16-24 will only work if your Z-Wave network is setup properly with the controller shown in Control Panel)

4. Setup ZWaveJS UI to Home Assistant ZWaveJS integration
  1. Click Settings -> Device & Services

  2. Click + Add Integrations
  3. Search ZWave
  4. Click Z-Wave JS
  5. Uncheck "Use the Z-Wave JS Supervisor add-on"
  6. Click Submit
  7. Paste "ws://a0d7b954-zwavejs2mqtt:3000"
  8. Click Submit
  9. Set your devices to the areas they are installed in, then click Finish

5. Update Z-Pi 7 using Z-WaveJS UI
  1. Your Z-Wave Frequency may change, so make sure that it is on the correct Z-Wave Frequency after firmware updating.