> 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="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2FadjpgM40rXKujxnMF8ad%2Fimage.png?alt=media&amp;token=754ca928-ec23-499b-83b8-69fd95dc7bbc" 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="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2Fcy8SmWsG1zam1kDYa0LX%2Fimage.png?alt=media&amp;token=22a3c313-43f8-4ff6-b97a-c0b17da40bcd" alt=""><figcaption></figcaption></figure>

Select MQTT

<figure><img src="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2F11yrk7CxSKbkBllWWrfy%2Fimage.png?alt=media&amp;token=fd89affe-8082-44d0-9462-89553a14457b" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2FiooqgqnR5AD6S95YUHRE%2Fimage.png?alt=media&amp;token=b0966e81-16e7-4858-a67b-f6b52b57b184" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2FmMHwHHoMxG2ujBwSmpjw%2Fimage.png?alt=media&amp;token=f4473c63-07d5-437e-abb9-4d09c704438f" 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="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2F42WUcGGjWYk8x6QV1BgZ%2Fimage.png?alt=media&amp;token=772fbebd-fd84-4317-9980-c04a4ba7ad48" 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="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2Fs9KMafhZWSp8lqnzEATP%2Fimage.png?alt=media&amp;token=d8430ce2-f5a0-4221-a6b5-6d6f43a53854" 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="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2F8lixZ71LTdikxzKK7bVz%2Fimage.png?alt=media&amp;token=cf83cb82-34cb-4d9e-a6d3-1cb187a740fd" 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="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2F5kIopu7VaXgw6kDqfXwH%2Fimage.png?alt=media&amp;token=e5d795fb-0638-450e-b86e-68f6cb0d0f8c" alt=""><figcaption></figcaption></figure>

Now it should be started correctly

<figure><img src="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2F1Gprn64sGPu6KWxwvRWB%2Fimage.png?alt=media&amp;token=cf9e8122-dcc2-4a82-b771-682687876d54" 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="https://1287130752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvVJ0h2a4qMIhB1I8GdV8%2Fuploads%2F1flKZ4jJFw7phXMYnmiZ%2Fimage.png?alt=media&amp;token=b65e772c-a697-440c-bf16-32b6fd596f4b" 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/>" %}