Skip to content

Build and Hardware

Jump to bottom
PurpleSentinel edited this page Oct 20, 2026 · 1 revision

Build and hardware

Required components

The current reference build uses:

  • Espressif ESP Thread Border Router / Zigbee Gateway board, family ESP32-S3-Thread-BR, with both ESP32-S3 and ESP32-H2 processors. An H2 development board alone is not a substitute for the complete board.
  • A Linux host: Raspberry Pi 4 with 2 GB or more is sufficient for the documented service; Pi 5 or another Linux server can also be used.
  • USB-C data cable(s), suitable power supplies and storage. An SSD is preferred over microSD for a continuously written history database.
  • Zigbee sensors and mains-powered routers/plugs that match the desired supported features.
  • Ethernet for the SBC is useful where available. The gateway uses Wi-Fi.

See the repository's hardware bill of materials for selection details and board references.

Firmware components

The S3 runs the project's ESP-IDF coordinator application and local REST API. The H2 runs a UART radio-co-processor image built from Espressif's supplied ot_rcp source. The repository documents ESP-IDF 5.5.4 and ESP-Zigbee 2.0.4 as the validated baseline; consult the current firmware guide before changing versions.

The H2's RCP origin does not mean this product currently provides Thread networking. The application configures a Zigbee coordinator.

Build and flash overview

  1. Install ESP-IDF and its ESP32-S3/ESP32-H2 toolchains as described in the firmware setup guide.
  2. Identify the connected processor before flashing. On the reference board, USB1 is H2 and USB2 is S3; verify the board marking and chip identity rather than relying on changing Linux device names.
  3. Build and flash the H2 radio co-processor image.
  4. Configure the S3 Wi-Fi credentials and a unique gateway API token, then build and flash the S3 application.
  5. Keep the Zigbee network's nonvolatile state. Do not erase it as part of routine firmware updates.
  6. Verify Wi-Fi association, gateway health API and coordinator readiness before pairing devices.

The project README and firmware guide contain the full commands and configuration details. The checked-in build instructions take precedence if this summary becomes stale.

Hardware placement

The gateway's Wi-Fi and Zigbee radios share the 2.4 GHz environment. Keep the board away from metal enclosures, access points and sources of radio interference. Zigbee channel 20 is the documented starting setting, not a universal best channel. Mains-powered Zigbee devices can route traffic, but the route a particular sensor uses depends on its link quality and network behavior; a plug's presence alone does not prove that it is routing another device.

Clone this wiki locally