How to build a Zigbee to Wifi Gateway for Home Assistant

Introduction<br>In the home automation world, Home Assistant plays a really important role. It&rsquo;s an open-source solution that&rsquo;s extremely flexible, backed by a large community online.<br>I recently bought a digital thermometer, the Shelly BLU H&T ZB, which measures ambient temperature and humidity and transmits the readings over Bluetooth or Zigbee.<br>To connect this sensor to my Home Assistant setup, I need a Zigbee coordinator to create the network and let the thermometer join it. This coordinator then has to talk to Home Assistant over WiFi.<br>This post is a guide on how to configure the board Espressif &ldquo;ESP Thread Border Router / Zigbee Gateway v1.2&rdquo; (ESP32-S3 + ESP32-H2) as Zigbee coordinator for Home Assistant, through Zigbee2MQTT and other open source projects.<br>Prerequisites<br>Board ESP Thread BR/Zigbee Gateway v1.2<br>USB-C data cable<br>Docker installed on the host<br>Home Assistant with MQTT reachable on the same network<br>The ESP Thread Border Router/Zigbee Gateway Board

This board (v1.2) is made up of two main sections:<br>ESP-H2 , which implements the IEEE 802.15.4 standard, common to both Zigbee and Thread<br>ESP-S3 , which supports Bluetooth and WiFi<br>By combining these two components, we can build a gateway (more accurately, a bridge) that carries Zigbee packets to a WiFi host and back.<br>Specifically:<br>ESP-H2 runs a complete, self-contained Zigbee NCP coordinator (esp-coordinator) that handles the radio communication with Zigbee devices (in my case, the Shelly thermometer).<br>ESP-S3 acts as a transparent TCP ↔ UART bridge (cdc2net) to the Wi-Fi network and is responsible for carrying Zigbee traffic to and from Home Assistant over WiFi.<br>Zigbee2MQTT connects via TCP to the bridge<br>Build environment<br>Let&rsquo;s set up the build environment for producing the two binaries we&rsquo;ll flash onto the board&rsquo;s chips.<br>As I usually do, I&rsquo;ll work inside Docker to keep my system clean instead of cluttering it with libraries and tools that only matter for a single project.<br>Start by creating a main working directory for the rest of this post.<br>cd ~<br>mkdir -p zb2wifi-gateway/espressif-data

Building the Docker container<br>Now let&rsquo;s build a Docker image with the libraries and tools we need for the rest of the work.<br>Here&rsquo;s the Dockerfile and the docker-compose.yml to launch the container — create both inside the zb2wifi-gateway directory.<br>Dockerfile<br>FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \<br>git wget flex bison gperf python3 python3-pip python3-venv python3-dev \<br>cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 \<br>gcc g++ pkg-config curl libdbus-1-dev \<br>libglib2.0-dev libavahi-client-dev unzip \<br>libgirepository1.0-dev libcairo2-dev libreadline-dev \<br>libevent-dev default-jre \<br>ca-certificates \<br>&& rm -rf /var/lib/apt/lists/*

USER ubuntu<br>WORKDIR /home/ubuntu

docker-compose.yml<br>services:<br>z2w-builder:<br>image: zb2wifi-builder:latest<br>container_name: zb2wifi-builder<br>user: "1000:1000"<br>group_add:<br>- "11"<br>volumes:<br>- ./esp-idf:/home/ubuntu/esp-idf<br>- ./esp-coordinator:/home/ubuntu/esp-coordinator<br>- ./cdc2net:/home/ubuntu/cdc2net<br>- ./espressif-data:/home/ubuntu/.espressif<br>working_dir: /home/ubuntu<br>stdin_open: true<br>tty: true<br>devices:<br>- /dev/ttyACM0:/dev/ttyACM0<br>command: bash

Heads up: this docker-compose assumes your user&rsquo;s uid and gid are 1000 and 1000, and that the serial device shows up as ttyACM0 when you plug in the board.<br>If your numbers differ, update the docker-compose file accordingly.<br>Now build the container image:<br>docker build --no-cache -t zb2wifi-builder .

[+] Building 1.7s (7/7) FINISHED docker:default<br>=> [internal] load build definition from Dockerfile 0.0s<br>....<br>....<br>=> exporting to image 0.1s<br>=> => exporting layers 0.0s<br>=> => naming to docker.io/library/zb2wifi-builder:latest 0.0s<br>=> => unpacking to docker.io/library/zb2wifi-builder:latest

Starting the builder container<br>We&rsquo;re ready to launch the container and build the project.<br>Plug your ESP board into the USB port, then run:<br>cd zb2wifi-gateway

docker compose run --rm z2w-builder

Cloning and preparing the firmware sources<br>Now let&rsquo;s clone the firmware sources for our board. Run these commands:<br>git clone -b v5.5.5 --recursive https://github.com/espressif/esp-idf.git

cd esp-idf

./install.sh esp32h2,esp32s3

. ./export.sh

For this project I&rsquo;m using Espressif SDK release v5.5.<br>./install.sh downloads the build toolchain (compilers for esp32h2 and esp32s3, plus the required Python packages) and installs it inside ~/.espressif — which, thanks to the volume mounted in docker-compose.yml, physically lives in espressif-data/ on the host. That keeps every package and tool for this project confined to zb2wifi-gateway, without touching our host system.<br>. ./export.sh needs to run every time we enter the container — it sets up the build environment correctly.<br>Now let&rsquo;s...