Migrate to Z-Wave 800 Series GPIO HAT Controller (Zooz ZAC93) on RPI5 without manually reacquiring devices and maintain on-board Bluetooth

Configuration Z-Wave
, , ,
1

Once the new RPi5 was released, I migrated my HassOS installation from my previous Odroid-N2 over to it. When I built that N2 some years ago, I did so using a Nortek HUSBZB-1 for both Zigbee and Z-Wave. However, the Z-Wave is only a 500 series controller so although there’s been some issues with 700/800 series Z-Wave controllers, a lot of that was established a few years ago now so I figured it’s time to upgrade. I had already ordered a couple of ZBDongle-E USB dongle and flashed one of them with Thread firmware. The other I used for Zigbee2MQTT. So now its time to upgrade the last remaining component.

That’s where things get confusing. There were really two problems I found.

  1. It doesn’t matter whether you upgrade to a 700 or 700 series controller, it seemed like many folks on the forums have been advocating for rebuilding your entire Z-Wave network for a so-called “migration”. That’s no fun!
  2. It’s really easy to use USB Z-Wave dongles with HA, but GPIO, well that’s another story. Sure, there’s documentation to support it in the forums as well. However, with the UART changes to the RPi5, it’s all outdated, OR a bit confusing. Some folks were saying that you’d still need to disable Bluetooth to use the UART for the Z-Wave HAT but that didn’t make much sense to me since the RPi5 uses a dedicated UART(s) for BT and console.

Below is the process to migrate from an older USB Z-Wave Dongle to a new 800 series dongle. The migration steps will work regardless of whether you want to use a GPIO based controller or a USB dongle. That said, the GPIO option is a bit more work, but I liked the idea of removing some external USB devices.

  1. Take a backup of HA and then simply power it down. Remove the old Z-Wave Dongle and connect it to a Windows PC. You’re going to need Simplicity Studio to integrate the new controller into your existing network and then set the new controller as the primary. There’s also a bit of tedious busy work you have to go through to get the new controller assigned as node 1 so that it matches the prior controller’s topology. There’s a YouTube vide here that explains this process well. Keep in mind that if you’re upgrading from a 500 series controller, some of the features in the Simplicity Studio Z-Wave Controller manager won’t be available. In my case, I wasn’t able to take a backup of the HUSBZB-1 prior to adding the new Zooz ZAC93 into the network. I was able to back up the config from the ZAC93 after it was in the network alongside the HUSBZB-1.

    • Also, if you’re using a GPIO-based controller, you’re going to need your own USB to UART adapter. You don’t need SPI. I used a $20 FTDI based adapter, but you must make sure that its 3.3V only. The EFR32ZG23 IC on the ZAC93 can’t handle 5V, per the datasheet. Also, you need to connect both grounds on the 10-pin GPIO connector to your UART adapter. I had connection errors and Simplicity Studio would crash until I did that. So you should have two grounds connected, TX, RX, and 3V3 DC between your UART adapter and the Z-Wave GPIO HAT.
    • Lastly on this part, if you’re migrating from the HUSBZB-1 as well, you’ll need to install the modified CP210x VCP drivers for the dongle’s internal UART IC from here. I found that the same driver works for both Win10 and Win11.

  2. If all went well from the steps laid out in that video, you should now have a USB 800 controller with all of your nodes on it and the controller should be node 1. Now there’s some modification to do in HA to get it to accept the GPIO Z-Wave controller once its installed in the RPi5. If you’re using a USB controller, you can skip to #3.

    • These instructions are specific to Raspberry Pi 5 since previous models have this well documented. Pi 5 no longer includes mini-UART. It also uses separate, dedicated UARTS (each of them PL011) for Bluetooth and the new Debug (Console) port. That said, in HassOS, the GPIO pins we need aren’t enabled for UART for the RPi5 by default. Neither is the SPI interface needed to do firmware upgrades of the Z-Wave controller directly from HA.
    • To enable the UART for the controller without sacrificing BT unnecessarily, you’ll need to add a few modified lines to the /boot/config.txt file in HassOS. To do this, you can:
      2A. Connect KVM directly to your RPi5
      2B. Use the HassOS SSH port 22222 Configurator via HACS to allow you to ssh into the OS. Info on this here.
      2C. Follow the official HA developers guide here to enable root SSH access (most difficult of the three but doable).
    • Once you’ve SSH’d into your HA build, edit the boot configuration via:
      vi /mnt/boot/config.txt
    • Look for the commented-out line:
      # Uncomment this to enable GPIO support for RPI-RF-MOD/HM-MOD-RPI-PCB
    • Uncomment the first two lines underneath that:
      enable_uart=1
dtparam=i2c_arm=on
    • If there, let the following two lines remain commented out:
      #dtoverlay=rpi-rf-mod
#dtoverlay=miniuart-bt
    • Add the following two lines immediately after that section:
      overlay_prefix=slot-A/overlays/                                                
dtoverlay=uart0-pi5,ctsrts
    • Save the config file via the Escape key, then type :wq! and hit Enter. Then reboot the machine. Be sure the Z-Wave controller is connected to the RPi5.

  3. Once HA has booted, it’s time to reconfigure the Z-Wave JS Add-On (NOT the integration) to use the new controller. Go to Settings > Add-ons > Z-Wave JS and then select the “Configure” tab up top. The GPIO controller will be /dev/ttyAMA0. If you’re using a USB stick, use the /dev/by-id/ value if available.

    • If you’re using a GPIO controller, I found that there’s a bug here where if I simply selected the radial next to /dev/ttyAMA0 and then clicked Save at the bottom, the Z-Wave JS integration wouldn’t load properly. Instead, select the hamburger menu towards the top-right and choose Edit in YAML. Next to the device line at the top, modify the line with "/dev/ttyAMA0", being sure to enclose it in double quotes. Then choose Save. Leave the other settings alone. Your S2 key config, if available, should be retained from the prior controller.
    • From here, you need only to wait a short while whilst the Z-Wave JS Add-On checks with your new controller and reinitializes the network. The Z-Wave Integration should automatically start once the Z-Wave JS Add-on is finished. After that, I would recommend rebooting HA, to make sure that it boots cleanly and still recognizes the controller.
    • If all is well, then the final step I’d recommend is to relearn the network routes. Go to Settings > Devices & services > Z-Wave > Configure. Then choose “Rebuild Network Routes”.

With any luck, you should now be cleanly migrated to a Z-Wave 800 Series controller without having had manually rebuild the network.

Cheers!

4 Likes