ESP32-S3 Thread Border Router

Turn an ESP32-S3 + W5500 Ethernet module into a Thread Border Router for Home Assistant

Thread mesh networking · Ethernet backhaul · Matter-ready · ESPHome powered

---

🌐 What Is This?

A Thread Border Router (TBR) bridges your Thread mesh network to your local IP network, allowing Thread-based smart home devices (Matter over Thread) to communicate with Home Assistant.

This project uses:

• ESP32-S3 — has built-in IEEE 802.15.4 radio for Thread
• W5500 Ethernet module — wired backhaul for reliable border router connectivity
• ESPHome — simple YAML-based firmware with Home Assistant integration

Why Ethernet? A Thread Border Router should have a rock-solid connection to your network. Wi-Fi adds latency and unreliability. Ethernet is the way.

---

🧾 Bill of Materials

Part	Price (approx.)	Notes
ESP32-S3-DevKitC-1	~$8–12	Must be S3 variant (has 802.15.4 radio)
W5500 Ethernet module	~$3–5	SPI-based Ethernet controller
Ethernet cable	~$2	Cat5e or better
USB-C cable + power	~$3	For flashing and power
Jumper wires	~$2	For SPI connections

Total: ~$15–25

---

🔌 Wiring — ESP32-S3 to W5500

W5500 Pin	ESP32-S3 GPIO	Function
SCK / SCLK	GPIO21	SPI Clock
MOSI / SI	GPIO45	SPI Data Out
MISO / SO	GPIO38	SPI Data In
CS / SCS	GPIO41	Chip Select
INT	GPIO39	Interrupt
RST	GPIO40	Reset
VCC	3.3V	Power
GND	GND	Ground

┌────────────────────┐         ┌────────────────┐
│   ESP32-S3-DevKit  │         │  W5500 Module  │
│                    │         │                │
│  GPIO21 (SCK)  ────┼────────►│  SCLK          │
│  GPIO45 (MOSI) ────┼────────►│  MOSI / SI     │
│  GPIO38 (MISO) ◄───┼─────────│  MISO / SO     │
│  GPIO41 (CS)   ────┼────────►│  CS / SCS      │
│  GPIO39 (INT)  ◄───┼─────────│  INT           │
│  GPIO40 (RST)  ────┼────────►│  RST           │
│  3.3V          ────┼────────►│  VCC           │
│  GND           ────┼────────►│  GND           │
│                    │         │                │
│  USB-C (power)     │         │  RJ45 ◄── LAN  │
└────────────────────┘         └────────────────┘

---

⚡ Quick Start

1. Install ESPHome

pip install esphome

Or use the ESPHome Dashboard add-on in Home Assistant.

2. Clone This Repo

git clone https://github.com/el-bakkali/esp-thread-border-router.git
cd esp-thread-border-router

3. Create Your Secrets File

cp secrets.yaml.example secrets.yaml

Edit secrets.yaml:

api_encryption_key: "your-generated-key"

Generate an encryption key at: https://esphome.io/components/api.html

4. Flash the ESP32-S3

First time (USB):

esphome run esp-thread-border-router.yaml

Subsequent updates (OTA):

esphome run esp-thread-border-router.yaml --device esp-thread-border-router.local

5. Plug in Ethernet

Connect a Cat5e cable from the W5500 module's RJ45 port to your router/switch. The ESP32-S3 will get an IP via DHCP.

---

🏠 Home Assistant Integration

Once flashed and connected:

1. The device auto-discovers in Settings → Devices & Services
2. Home Assistant detects the Thread Border Router
3. Go to Settings → Thread to see your Thread network
4. Thread/Matter devices can now join through this border router

---

🧵 What Can You Do With Thread?

Thread is the transport layer for Matter smart home devices:

Device Type	Examples
Lights	Nanoleaf, Eve, IKEA (future)
Sensors	Eve Motion, Eve Door & Window
Switches	Eve Energy, Third Reality
Locks	Yale, Schlage (Matter-enabled)
Thermostats	Eve Thermo

All Matter-over-Thread devices need a Thread Border Router to communicate with your network. This is that router.

---

🔧 Configuration Details

Parameter	Value
Board	ESP32-S3-DevKitC-1
Framework	ESP-IDF
Ethernet Chip	W5500 (SPI)
Radio	IEEE 802.15.4 (built into ESP32-S3)
Protocol	Thread
Backhaul	Wired Ethernet

---

📁 Project Structure

esp-thread-border-router/
├── esp-thread-border-router.yaml   # Main ESPHome configuration
├── secrets.yaml.example            # Template for secrets
├── .gitignore                      # Ignores secrets and build artifacts
├── LICENSE                         # MIT License
└── README.md                       # You're reading it

---

🆚 Why DIY vs. Commercial Thread Border Routers?

Feature	Apple TV / HomePod	Google Nest Hub	DIY (This Build)
Price	$129+	$99+	~$15–25
Wired Backhaul	❌ (Wi-Fi only*)	❌ (Wi-Fi only)	✅ Ethernet
Home Assistant Native	❌	❌	✅
Open Source	❌	❌	✅
Ecosystem Lock-in	Apple	Google	None
OTA Updates	Vendor-controlled	Vendor-controlled	You control

*Apple TV 4K has Ethernet but Thread backhaul behavior varies.

---

⚠️ Troubleshooting

Issue	Fix
No Ethernet IP	Check W5500 wiring, especially MISO/MOSI orientation
Device not in HA	Ensure ESP32-S3 and HA are on the same LAN/VLAN
Thread network not visible	Verify ESP32-S3 variant (not ESP32 or ESP32-C3)
OTA fails	Fall back to USB flash; check that Ethernet has internet
W5500 not responding	Verify 3.3V power (not 5V) and check SPI connections

---

📜 License

MIT License — do whatever you want with it.

---

Built with ☕ and ESPHome

A $15 Thread Border Router with Ethernet backhaul — because mesh networking shouldn't cost $130.