Setting up ZigDash

ZigDash connects to the MQTT broker that your Zigbee2MQTT already uses. Most people are done in a minute.

What you need

• Zigbee2MQTT, running, with at least one device paired.
• An MQTT broker that Zigbee2MQTT uses, usually Mosquitto. It can run on Home Assistant, a Raspberry Pi, a server or an SMLIGHT hub. No hub yet? See the hubs we recommend.
• An Android phone or tablet on the same Wi-Fi as that hub.

No Zigbee2MQTT yet? Open ZigDash and try the demo home first.

1. Let ZigDash find it

1. Connect your phone to your home Wi-Fi. Not a guest network, and turn mobile data off while you set up.
2. Open ZigDash and tap Find my setup. While it looks, tell it where Zigbee2MQTT runs: Home Assistant, an SMLIGHT hub, a Raspberry Pi or Docker, or not sure.
3. ZigDash looks for an MQTT broker on your network, then checks that Zigbee2MQTT is on it.
4. Pick the devices you want and you have a dashboard.

2. Nothing found? Connect by address

The scan can miss a hub behind a second router, on a mesh network, or one that answers slowly. Type its address instead:

1. Find the hub's address: in your router's app, or the address you open Home Assistant or the hub's web page with. It looks like 192.168.1.20.
2. Type it in ZigDash and tap Check this address. You can paste the link from your browser too.

In manual setup the usual settings are TCP, port 1883. Use 8883 only if your broker is set up for TLS. Port 8080 or 80 is the hub's web page, not MQTT.

3. The login

If the broker asks for a login, it wants the MQTT login, not the password of your hub's web page.

• Home Assistant: a Home Assistant user. See the Home Assistant guide.
• Raspberry Pi or Docker: the user from Mosquitto's password file. It's the same one in Zigbee2MQTT's configuration.yaml under mqtt.
• SMLIGHT: the login shown on the hub's web page under Settings › MQTT.

Zigbee2MQTT already logs in to this broker, so its web page shows the username under Settings › MQTT. Copying a password can add a space at the end; check for one.

Notes for your hub

Home Assistant

Needs the Mosquitto broker add-on and the Zigbee2MQTT add-on, both running. Full steps in the Home Assistant guide.

Raspberry Pi, Linux or Docker

Mosquitto 2 only accepts connections from the machine it runs on until you tell it to listen on the network. Add this to mosquitto.conf and restart Mosquitto:

listener 1883
password_file /etc/mosquitto/passwd
allow_anonymous false

Create the user with mosquitto_passwd -c /etc/mosquitto/passwd zigdash (leave out -c if the file already exists).

SMLIGHT (SMHUB, SLZB)

Open the hub's web page, go to Settings › MQTT and turn on Allow External, so your phone can reach the broker. Check that Zigbee2MQTT shows as running.

Away from home

At home ZigDash talks to your hub directly. To use it away from home, install Tailscale on the hub and the phone, then add the hub's Tailscale address (100.x.y.z) as the home's remote host. Nothing is opened to the internet and no port forwarding is needed.