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. 

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

    Raspberry Pi 3 

    Raspberry Pi 4

  5. Save config.txt
  6. Exit config.txt
  7. Now safely eject your Flash drive or microSD and remove it from your PC
  8. Install your Flash drive or microSD into your RPi and power it up.
  9. Wait a few minutes before moving onto the next following steps.

2. Software Steps
  1. Click Supervisor
  2. Click Add-on Store
  3. Search for "ZWave"
  4. Click Z-Wave JS to MQTT
  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 to MQTT
  8. Click "Open Web UI"
  9. Click "Gear Icon"
  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.
  13. Click Save
  14. Click 4 box icon, and see if the driver boots up properly.
  15. Click Supervisor
  16. Click Z-Wave JS to MQTT
  17. Click Documentation
  18. Copy "ws://a0d7b954-zwavejs2mqtt:3000"
  19. Click Configuration
  20. Click Integrations
  21. Click + Add Integrations
  22. Search ZWave
  23. Click Z-Wave JS
  24. Uncheck "Use the Z-Wave JS Supervisor add-on"
  25. Click Submit
  26. Paste "ws://a0d7b954-zwavejs2mqtt:3000"
  27. Click Submit
  28. Set your devices to the areas they are installed in, then click Finish

Change to Z-Wave JS to MQTT if you've already installed Z-Wave JS.

You may change from Z-Wave JS over to Z-Wave JS to MQTT but will require a bit of extra setup to finalize it. Once you have both Z-WaveJS default integration installed and MQTT, you can swap between MQTT and the original Z-WaveJS to MQTT integrations as you like.

You can follow the steps below to change from Z-Wave JS -> Z-Wave JS to MQTT. 

  1. Go to Configuration -> Integrations
  2. Under Z-WaveJS click on the More Options icon (3 dot) then select Disable -> OK
  3. Click on Supervisor -> Z-Wave JS -> STOP
  4. Wait a moment for Z-Wave JS to stop, once that stops loading, click on the back arrow
  5. If you haven't installed Z-Wave JS to MQTT:
    1. Click on Add-on Store tab
    2. Find Z-Wave JS to MQTT and Install this
    3. Now click INSTALL, give it about 2-3 minutes to finish the installation.
    4. Click START, then wait about 10 seconds before continuing these steps. 
    5. When ready, click on OPEN WEB UI
    6. Click Menu (hamburger icon) -> Settings
    7. Click Zwave to expand it
    8. Click Serial port and select /dev/ttyAMA0 
    9. Next to Network Key, add the original network key you used in the original ZWaveJS add-on, if you didn't previously have a network key, go ahead and press the Refresh button to randomly generate a key.
    10. Click Save
  6. Go to Configuration -> Integrations
  7. At the top right, you'll notice "1 disabled" click on SHOW. (if you have more unenabled integrations, you may have more than 1 disabled option, we only care about Z-Wave JS here). 
  8. Click ENABLE on Z-Wave JS and it should connect automatically. 
  9. You may need to reboot your Home Assistant to finalize the changes.