Home Assistant Guide

Simple tutorials for powerful automations

Getting Started with ZHA (Zigbee Home Automation)

ZHA is the official Zigbee integration for Home Assistant, allowing you to connect and control Zigbee devices like smart bulbs, sensors, switches, and more - directly from Home Assistant, with no extra software needed. If you want to add Zigbee devices to your smart home and prefer a simple, straightforward setup, ZHA is usually the best starting point.

What is ZHA?

ZHA stands for Zigbee Home Automation. It's a built-in integration in Home Assistant that lets you connect Zigbee devices using a compatible USB radio (sometimes called a "coordinator" or "Zigbee stick"). ZHA handles device pairing, control, and monitoring entirely within Home Assistant, so you don't need to run any extra apps or services.

ZHA vs Zigbee2MQTT: Which Should You Choose?

When you add Zigbee devices to Home Assistant, there are two main ways to control and manage them:

  • ZHA (Zigbee Home Automation) is the simplest option for most users. It's built directly into Home Assistant, so you don't need to install or configure anything extra. All device pairing, control, and management happens inside Home Assistant itself.
  • Zigbee2MQTT is an alternative that gives you more advanced features and compatibility with some extra devices. Instead of talking directly to your Zigbee devices, Home Assistant communicates with them through a small piece of software called an MQTT broker.
    What is MQTT? MQTT stands for "Message Queuing Telemetry Transport." It's just a simple way for smart devices to send messages back and forth. If you use Zigbee2MQTT, you'll need to set up this "broker" - think of it as a post office that passes information between your Zigbee devices and Home Assistant. ZHA does not require MQTT at all.

When is ZHA best? If you're new to Home Assistant or Zigbee, or just want to get your devices working quickly, ZHA is almost always the best choice.
When to consider Zigbee2MQTT? If you need advanced features like over-the-air updates (OTA), support for rare Zigbee devices, or you already use MQTT for other devices, Zigbee2MQTT might be worth considering.

What You'll Need

  • A Zigbee coordinator (USB stick), such as the Sonoff Zigbee 3.0 USB Dongle Plus, ConBee II, or Nortek HUSBZB-1.
  • A running Home Assistant installation.
  • Your Zigbee devices (bulbs, sensors, switches, etc.).

Setting Up ZHA

  1. Plug in your Zigbee USB stick to the computer or Raspberry Pi running Home Assistant.
  2. Open Home Assistant and go to Settings → Devices & Services. Click Add Integration (bottom right).
  3. Search for Zigbee Home Automation or ZHA and select it.
  4. Choose your Zigbee radio from the list. Home Assistant will often auto-detect it. If not, you may need to pick the correct serial port (it usually starts with /dev/ or tty).
  5. Click Submit and wait a few seconds for setup to complete.
  6. Once installed, you'll see ZHA as a new integration under Devices & Services.

Adding Zigbee Devices

  1. Click into the ZHA integration on your Devices & Services page.
  2. Click Configure, then Add Device.
  3. Put your Zigbee device into pairing mode (check its instructions - usually holding a button for several seconds).
  4. Home Assistant will automatically detect and add the device. You can give it a name, assign it to an area, and start using it right away.

Tip: Always pair new devices close to your Zigbee coordinator first, then move them to their final location if needed.

Using Zigbee Devices in Home Assistant

  • After pairing, your Zigbee devices show up as entities and devices in Home Assistant. You'll see them in the Devices & Services section, and you can add them to dashboards, automations, or scripts.
  • For example, you might add a motion sensor to a dashboard, or use it to trigger an automation that turns on a Zigbee smart bulb.
  • You can rename devices, assign them to areas, and control their settings from the device page in Home Assistant.

Tips & Troubleshooting

  • If a device doesn't pair, try resetting it and making sure it's close to the Zigbee coordinator.
  • For best coverage, keep your Zigbee coordinator away from Wi-Fi routers and USB 3.0 ports (they can cause interference).
  • Add a few Zigbee mains-powered devices (like smart plugs) to act as "repeaters" - this helps create a robust Zigbee mesh network.

Summary: Why Start with ZHA?

  • All-in-one integration - no separate broker or app needed.
  • Beginner-friendly: intuitive UI, easy setup, no YAML required.
  • Supports most popular Zigbee devices out of the box.
  • Can always switch to Zigbee2MQTT later if you need advanced features.