> For the complete documentation index, see [llms.txt](https://tk233.gitbook.io/notes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tk233.gitbook.io/notes/workflow-automation/zigbee-based-home-automation/setting-up-home-assistant-on-raspberry-pi-to-control-zigbee-iot-devices.md).

# Setting up Home Assistant on Raspberry Pi to Control Zigbee IoT Devices

In this article, we will introduce how to set up Home Assistant OS on a Raspberry Pi 3 B+ and configure Zigbee2MQTT to connect and control the Zigbee based IoT devices. The entire process takes around 1 hour to finish.

***

This is fairly simple and straight forward, thanks to the nice support provided by the Raspberry Pi Imager.

## Hardware Platform

An pretty old Raspberry Pi 3 B+ is used. 

Some people reported that the Zigbee dongle does not work well with USB3.0 ports due to interference, so maybe using 3 B+ with all USB 2.0 ports is a good option?

## Setting up Pi

Follow this tutorial on flashing the firmware

{% embed url="<https://www.home-assistant.io/installation/raspberrypi>" %}

After opening [homeassistant.local:8123](http://homeassistant.local:8123/), it takes some time to set everything up

<figure><img src="/files/DqWVZpmHqtfh9zhGa7SM" alt=""><figcaption></figcaption></figure>

## Setting up Home Assistant

Follow the prompt on the webpage to set up admin account, home location, and data sharing settings.

## Setting up MQTT Integration

In Settings -> integrations, add MQTT integration

<figure><img src="/files/tup8pPxfCUNgJm6LIex8" alt=""><figcaption></figcaption></figure>

Select MQTT

<figure><img src="/files/EFMWf5nLfHMl6W1bcVSy" alt=""><figcaption></figcaption></figure>

We will use the provided mosquitto broker to connect the MQTT to Home Assistant service.

<figure><img src="/files/1rvj4WCGeMCpQ8Mj7nsR" alt=""><figcaption></figcaption></figure>

It takes a while to install the integration service. After installation, it will automatically start the service.

<figure><img src="/files/QpVhrNUOReaUxTARFH4Y" alt=""><figcaption></figcaption></figure>

## Setting up Zigbee2MQTT

Install the addon following this tutorial

{% embed url="<https://github.com/zigbee2mqtt/hassio-zigbee2mqtt#installation>" %}

Click Add

<figure><img src="/files/baXvkKce0I0F1ZolhD47" alt=""><figcaption></figcaption></figure>

After adding, refresh the page, and it should appear in the Add-on Store list under section "Home Assistant Add-on: Zigbee2MQTT"

Click into the panel, and click Install.

After installation, start the service.

In this case, it fails to find the Zigbee dongle.

<figure><img src="/files/i4cTjZQ04qKMrj2CoLDO" alt=""><figcaption></figcaption></figure>

Then we need to manually tell it.

The dongle path can be seen at Settings -> System -> Hardware -> All Hardware

<figure><img src="/files/zvWxPBZ3M5ZypJRIoHI1" alt=""><figcaption></figcaption></figure>

Put this information in the configuration, save and restart the addon.

```yaml
port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_aec3a1c88f19ec1197ff37cc47486eb0-if00-port0
adapter: zstack
```

<figure><img src="/files/gtZhvaCuuhPcQkesNHl5" alt=""><figcaption></figcaption></figure>

Now it should be started correctly

<figure><img src="/files/v9bYwGDdhxZZHI869q4Q" alt=""><figcaption></figcaption></figure>

## Adding Zigbee Devices

In the Addon panel, click the "Open WebUI" button.

Click the "Permit Join (All)" to allow pairing with devices.

<figure><img src="/files/mlacAvpyh8baAnshNGb9" alt=""><figcaption></figcaption></figure>

Now enable pairing mode on the IoT devices, it should then be paired to the service fairly quickly.

I observed that the pairing time is much faster than when using ZHA.

## Configuring Apple HomeKit

{% embed url="<https://www.home-assistant.io/integrations/homekit/>" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://tk233.gitbook.io/notes/workflow-automation/zigbee-based-home-automation/setting-up-home-assistant-on-raspberry-pi-to-control-zigbee-iot-devices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.