Zigbee

The Cruiser’s built-in ESP32-C6 module can be the Zigbee radio for Home Assistant, with no USB dongle. PoE control and monitoring keep working while Zigbee runs.

Zigbee is an optional firmware. Boards ship with the WiFi + Bluetooth firmware, and you switch to Zigbee with one command.

How it fits together

Two pieces work together:

• Zigbee radio firmware on the ESP32-C6. It handles the radio and PoE control.
• The Zigbee server (exaviz-ziggurat, service name ziggurat) on the CM5. It runs the Zigbee network, and Home Assistant connects to it over the network.

sudo exaviz-flash zigbee installs both. Home Assistant’s Zigbee Home Automation (ZHA) integration then uses the Ziggurat radio type to talk to the server.

What you need

Antenna

The ESP32-C6 uses an external antenna connector and the board ships without an antenna. Zigbee needs one attached. Use a W.FL (MHF III) to RP-SMA pigtail and a 2.4 GHz antenna. This is not the larger U.FL / MHF1 connector, which will not mate. Part details and pictures are on the ESP32 page.

Fit the antenna before you pair devices. A module with no antenna hears devices poorly, and commands to them time out.

Install

On the Cruiser:

sudo apt update
sudo apt install exaviz-tools
sudo exaviz-flash zigbee

Run it once. It prepares the board and reboots it once, and the board finishes by itself when it comes back: it writes the firmware, installs the Zigbee server and starts it. Allow about five minutes. Watch progress, and read the Home Assistant address it prints, with journalctl -u exaviz-flash-resume; the result is in /var/log/exaviz-flash.log. The full explanation of the reboot is in Installing the Zigbee firmware.

When it finishes it prints the address to give Home Assistant, along these lines:

The Zigbee server is running. In Home Assistant, go to Settings > Devices &
services > Add integration > Zigbee Home Automation, choose the Ziggurat radio
type, and enter this address:
  ws://<board address>:9999
Home Assistant 2026.7 or newer is required.

This installs Zigbee firmware 1.2.0 (PoE + Zigbee) with exaviz-tools 1.0.21 or newer.

Connect Home Assistant

1. Go to Settings > Devices & services > Add integration.
2. Choose Zigbee Home Automation.
3. Choose the Ziggurat radio type.
4. Enter the address the install printed, ws://<board address>:9999.
5. Finish the wizard.

Pair devices

Use Home Assistant’s normal ZHA flow: open the ZHA integration, choose Add device, then put the device into pairing mode (usually by holding its button, or power-cycling a bulb). Pair devices with the antenna fitted and the device within a few metres of the board, then move it to its final place.

A mains-powered device (plug, bulb) also acts as a router and extends the network, so place those between the board and any battery sensors that sit far away.

The Zigbee status in the Exaviz Home Assistant integration

With the Exaviz Home Assistant integration (ha-poe-plugin) installed, a Zigbee Coordinator entry on the Cruiser shows whether the Zigbee firmware is installed. When it is not, it shows this message:

Zigbee firmware isn’t installed on this Cruiser board. Install it with the Exaviz tools to use Zigbee.

The plugin’s configuration page describes the entity. That message means the board is running the WiFi + Bluetooth firmware. Run sudo exaviz-flash zigbee as described above. The message does not mean anything is broken.

Network access to the Zigbee server

The Zigbee server has no password. Anyone who can reach port 9999 can control your Zigbee network, so it only answers from private networks: loopback, link-local, multicast, and the ranges 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and fc00::/7. A public internet address is refused, but anyone on your LAN can reach it.

If Home Assistant runs on the same board, listen on loopback only. Edit /etc/default/exaviz-ziggurat, set:

ZIGGURAT_LISTEN=127.0.0.1:9999

then restart the server with sudo systemctl restart ziggurat and enter ws://127.0.0.1:9999 in Home Assistant.

By default it listens on all interfaces (0.0.0.0:9999). To reach it over a VPN range, run sudo systemctl edit ziggurat and add the range to the unit’s allow list, for example:

[Service]
IPAddressAllow=100.64.0.0/10

Go back to WiFi + Bluetooth

sudo exaviz-flash stock

This restores the standard firmware and stops and disables the Zigbee server. Restart the board afterwards: the standard device tree only takes effect on the next boot.

Troubleshooting

Home Assistant has no Ziggurat radio type. Home Assistant is older than 2026.7. Update it.

The install printed that the firmware is installed but exaviz-ziggurat could not be. The firmware is fine. Finish the setup with the two commands the tool printed:

sudo apt update && sudo apt install exaviz-ziggurat
sudo systemctl enable --now ziggurat

Home Assistant cannot connect. Check that the server is running, then check the address:

systemctl status ziggurat
journalctl -u ziggurat -n 50
hostname -I

The address in Home Assistant must be ws:// followed by one of the board’s addresses and :9999. If Home Assistant is on a different network that is not private (for example a cloud host), the server refuses it by design.

Devices pair but commands are slow or time out. Messages like route discovery timed out or did not ACK in journalctl -u ziggurat mean the radio is not hearing the device reliably. Check, in order:

1. The antenna is attached, and fully seated on the W.FL connector.
2. The device is not far from the board or behind metal or thick walls.
3. Add a mains-powered Zigbee device as a router between the board and the far device.

The Zigbee server is not running after a firmware change. sudo exaviz-flash stops the server while it writes firmware and starts it again afterwards. If you are on the Zigbee firmware and it is not running, start it with sudo systemctl start ziggurat. After exaviz-flash stock it is disabled on purpose.

sudo exaviz-flash --about reports the installed tool version, the board serial and which firmware types the service can provide. It changes nothing. Send its output with any support request to support@exaviz.com.

Last modified October 14, 2026