ESP Zigbee-Gateway — Zigbee Coordinator over the network

Turns the ESP Thread Border Router / Zigbee Gateway board (ESP32-S3 + ESP32-H2) into a network-attached Zigbee coordinator. The H2 runs the full ZBOSS NCP firmware (esp-coordinator); the S3 bridges its frame stream to a TCP port over Ethernet or WiFi. Zigbee2MQTT talks to it exactly as it would to a USB stick — just over tcp:// instead of a serial port.

Use the socket marked USB2 — that is the ESP32-S3. The board's other USB-C, USB1, goes to the ESP32-H2 and cannot flash this image. If the browser reports an ESP32-H2 after you pick the port, you are on the wrong socket.

Connect the board's USB2 socket (ESP32-S3), then:

Chromium-based desktop browser required (Web Serial). Firefox and Safari cannot flash.

What gets written

One click installs both chips. The S3 image carries the H2's firmware in a dedicated flash partition and writes it to the H2 on first boot, over the inter-chip UART:

Part	Offset	Goes to
S3 gateway firmware	`0x0`	ESP32-S3 — bridge, web UI, OTA
Zigbee radio firmware	`0x620000`	staged, then flashed into the ESP32-H2

The very first boot takes about half a minute longer than later ones: the S3 finds a factory board still running Espressif's ot_rcp, and replaces it with the ZBOSS NCP firmware (~720 KB, verified by MD5). Subsequent boots verify the radio's application against the staged image (MD5) and rewrite only on a mismatch. A firmware update of the S3 alone therefore leaves a matching radio untouched.

After flashing

The board works as it comes — no add-on required. Onboard WiFi is provisioned over the very same USB port you just flashed from, via Improv. If you would rather not use a cable at all: leave the gateway unconfigured for about two minutes and it opens its own access point (CDC2NET XXXX, no password), where a configuration page at 192.168.4.1 takes your network details.

With the optional Ethernet sub-board fitted, a wired connection is picked up by DHCP at boot and takes precedence — the access point then stays off, since the web UI is reachable over the network anyway. Either way the web UI lives on port 80 and the device announces itself over mDNS.

Point Zigbee2MQTT at the raw-TCP port:

serial:
  adapter: zboss
  port: tcp://<gateway-ip>:2329

The zboss adapter is marked experimental in stock Zigbee2MQTT, and coordinator backup/restore needs the matching container image. See the project README before putting a production network on it.

Notes on this hardware

Espressif's factory firmware makes the S3 reflash the H2 back to ot_rcp when it detects the radio failing to come up as a Spinel RCP (a documented recovery feature). Flashing only the H2 with coordinator firmware therefore does not stick — install this image on the S3 instead, which is what the button above does.
The two chips talk over an internal UART (H2 GPIO24/23 ↔ S3 GPIO17/18) plus the H2's reset and boot straps on S3 GPIO7/8 — the same wiring Espressif's own RCP updater uses.
This build is specific to the gateway board's wiring. The generic ESP32-H2 image from the stick flasher uses different UART pins and will not talk to the S3.
Known limitation with the Ethernet sub-board: if the gateway boots with no cable and no WiFi credentials, it opens its configuration access point after about two minutes. Plugging the network cable in after that point may leave the Ethernet link stuck — a restart brings it up normally. Booting with the cable already connected, or plugging it in before the access point appears, is unaffected.