Zigbee coordinator over the network on the ESP Thread Border Router / Zigbee Gateway board

[tostmann]

There is a new flavour of this firmware, and it is not a stick: a network-attached Zigbee coordinator on Espressif's ESP Thread Border Router / Zigbee Gateway board — the ~10 USD board with an ESP32-S3 and an ESP32-H2 on it.

https://install.busware.de/cdc2net/zbgw/

What it is

The H2 runs the full ZBOSS NCP firmware from this repository — the same coordinator that runs on a C6 stick, no reduced version. The S3 bridges the NCP frame stream to a raw TCP port over Ethernet or WiFi. Zigbee2MQTT talks to it exactly as it would to a USB stick:

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

No USB host on your server, no ser2net or socat, no coordinator hanging off the back of the machine that runs your automation. The coordinator can sit wherever the radio coverage is best.

Note this is a different approach from the experimental WiFi-coex build for the C6: there, one chip does Zigbee and WiFi on a single radio, time-shared. Here the two jobs live on two chips — the H2 does nothing but 802.15.4, the S3 does nothing but network. Both are 2.4 GHz, so this is not magic, but the coordinator's radio is at least not sharing its own airtime with its own uplink.

Installing

One click writes both chips. The S3 image carries the H2's firmware in a dedicated flash partition and writes it over the inter-chip UART on first boot — MD5-verified, about 25 seconds. After that, every boot verifies the radio's application against the staged image (MD5) and rewrites only on a mismatch: updating the S3 leaves a matching radio untouched, while an erased or half-written H2 gets repaired automatically.

This matters because the board resists the obvious approach: Espressif's factory firmware makes the S3 reflash its bundled ot_rcp image back onto the H2 when it detects the radio failing to come up as a Spinel RCP — a documented recovery feature, confirmed on our bench. Flashing only the H2 with coordinator firmware therefore does not survive; the S3 has to be dealt with, which is what this image does.

You need a Chromium-based desktop browser (Web Serial); Firefox and Safari cannot flash.

After flashing

It works as it comes, with no add-on hardware. WiFi is provisioned over the same USB-C port you just flashed from, using 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 with a configuration page. The optional Ethernet sub-board is picked up by DHCP at boot and takes precedence when fitted. Either way there is a web UI on port 80, and firmware updates for both the gateway and the radio arrive over the air.

What is verified, and what is not

Verified on the board, over both a wired and a wireless uplink: network formation, a factory-new device joining on air in about three seconds, interview, pairing, on/off round-trips, and the network state surviving reboots (NVRAM resume).

Not verified, and worth knowing before you flash:

• This overwrites Espressif's factory firmware on both chips. We deliberately did not keep a factory backup. Going back to a Thread border router means returning to Espressif's esp-thread-br firmware — a path we have not tested.
• With the Ethernet sub-board there is a known corner case: booting with no cable and no WiFi credentials opens the configuration access point after about two minutes, and plugging the cable in after that point can leave the Ethernet link stuck. A restart brings it up normally; booting with the cable connected is unaffected.
• The zboss adapter is still marked experimental in stock Zigbee2MQTT, and coordinator backup/restore needs the matching container image — see the README before you put a production network on it.

The gateway side lives in tostmann/cdc2net, the coordinator side is this repository. Feedback, and especially reports from networks larger than a bench, are welcome here.

Credit where it is due: this exists because @xbln pointed at the board in Discussion #1.