Wiznet makers

PROJECT DESCRIPTION

ESP HA USB Gateway는 ESP32-S3의 USB Host 기능과 WIZnet W5500 Ethernet을 활용하여 Zigbee, EnOcean 등의 USB 통신 동글을 TCP 네트워크로 연결하는 오픈소스 스마트홈 게이트웨이입니다.

일반적으로 Zigbee USB 동글은 Home Assistant가 실행되는 Raspberry Pi, 미니 PC 또는 서버의 USB 포트에 직접 연결해야 합니다. 하지만 이 방식은 USB 케이블 길이에 제한이 있고, Home Assistant를 가상머신으로 운영하는 경우 USB Passthrough 설정과 서버 이전이 복잡해질 수 있습니다.

이 프로젝트는 USB 동글을 ESP32-S3에 연결하고, USB 시리얼 데이터를 Wi-Fi 또는 W5500 Ethernet을 통해 TCP Socket으로 전달합니다. 이를 통해 Zigbee 또는 EnOcean 동글을 Home Assistant 서버와 떨어진 위치에 설치하고 네트워크를 통해 사용할 수 있습니다.

1. System Overview

전체 시스템은 다음과 같이 구성됩니다.

Zigbee / EnOcean / USB Serial Dongle
                  │
             USB Connection
                  │
          ESP32-S3 USB Host
                  │
           USB-to-TCP Bridge
                  │
       Wi-Fi or W5500 Ethernet
                  │
              TCP Network
                  │
   Home Assistant / Zigbee2MQTT / ZHA

ESP32-S3는 USB Host로 동작하며 연결된 USB 장치를 자동으로 감지합니다.

USB 장치에서 수신한 시리얼 데이터는 지정된 TCP 포트로 전달되며, 반대로 네트워크에서 들어온 TCP 데이터는 USB 장치로 전송됩니다.

따라서 Home Assistant에서는 원격 USB 장치를 로컬 USB 장치처럼 직접 연결하지 않고도 TCP 주소를 통해 사용할 수 있습니다.

2. Why Is This Gateway Needed?

Home Assistant에서 Zigbee2MQTT나 ZHA를 사용할 때는 일반적으로 다음과 같이 Zigbee USB 동글을 서버에 직접 연결합니다.

Zigbee Sensor
      │
  Zigbee Wireless
      │
Zigbee USB Dongle
      │
    USB
      │
Home Assistant Server

이 구조에는 몇 가지 제약이 있습니다.

Zigbee 동글을 서버 근처에 설치해야 함

USB 연장 케이블 길이에 제한이 있음

서버나 가상머신을 옮기면 USB Passthrough를 다시 설정해야 함

Proxmox 또는 ESXi에서 VM을 다른 호스트로 이전하기 어려움

서버의 USB 3.0 포트나 금속 케이스로 인해 Zigbee 간섭이 발생할 수 있음

ESP HA USB Gateway를 사용하면 USB 동글과 Home Assistant 서버를 네트워크로 분리할 수 있습니다.

Zigbee USB Dongle
        │
 ESP HA USB Gateway
        │
W5500 Ethernet Network
        │
 Home Assistant Server

이를 통해 USB 동글을 Zigbee 수신에 적합한 장소에 설치할 수 있으며, Home Assistant 서버는 다른 방이나 데이터센터, 가상화 서버에 배치할 수 있습니다.

3. ESP32-S3 USB Host

이 프로젝트는 ESP32-S3의 USB OTG Host 기능을 사용합니다.

ESP32-S3는 USB Hub 또는 USB Serial 동글에 연결된 장치를 인식하고, 장치의 제조사, 제품명, 시리얼 번호 등의 정보를 읽습니다.

지원되는 대표적인 USB 장치는 다음과 같습니다.

Zigbee USB Dongle

EnOcean USB Dongle

FTDI USB-to-Serial Device

CP210X USB-to-Serial Device

CDC-ACM USB Serial Device

USB Hub를 연결하면 여러 USB 장치를 동시에 연결할 수도 있습니다.

다만 ESP32-S3 USB Host Controller의 자원 제한으로 인해, 현재 프로젝트에서는 USB Hub 사용 시 동시에 안정적으로 사용할 수 있는 시리얼 장치 수가 제한될 수 있습니다. 프로젝트 문서에는 USB 장치 슬롯을 최대 8개까지 설정할 수 있지만, USB Hub를 사용할 경우 동시에 동작 가능한 실제 장치는 최대 2개 수준이라고 안내되어 있습니다.

4. USB-to-TCP Bridge

프로젝트의 핵심 기능은 USB Serial과 TCP Socket 사이의 양방향 데이터 변환입니다.

예를 들어 Zigbee USB 동글에 TCP 포트 8880을 할당하면 Home Assistant 또는 Zigbee2MQTT는 다음과 같이 네트워크로 동글에 접속할 수 있습니다.

tcp://192.168.1.108:8880

데이터 흐름은 다음과 같습니다.

Zigbee Device
     │
Zigbee Wireless
     │
Zigbee USB Dongle
     │ USB Serial
ESP32-S3 USB Host
     │
USB-to-TCP Conversion
     │
W5500 Ethernet
     │ TCP/IP
Zigbee2MQTT

TCP에서 수신한 데이터는 USB 동글로 전달되고, USB 동글에서 수신한 데이터는 TCP Client로 전달됩니다.

각 USB 장치는 독립적인 TCP 포트를 사용할 수 있으므로 Zigbee와 EnOcean 동글을 하나의 게이트웨이에 연결하고 서로 다른 포트로 운영하는 것도 가능합니다.

현재는 각 USB 장치 포트에 하나의 TCP Client만 접속할 수 있습니다.

5. WIZnet W5500 Ethernet

ESP HA USB Gateway는 기본적으로 Wi-Fi를 사용할 수 있으며, Waveshare ESP32-S3 ETH 보드와 WIZnet W5500을 이용한 유선 Ethernet 구성도 지원합니다.

W5500은 ESP32-S3와 SPI로 연결되며, 프로젝트의 예제 설정에는 다음 핀 구성이 제공됩니다.

W5500 Ethernet을 사용하면 Wi-Fi 환경보다 안정적으로 USB 시리얼 데이터를 전달할 수 있습니다.

특히 Zigbee 또는 EnOcean 게이트웨이는 장시간 상시 연결 상태를 유지해야 하므로, 무선 간섭이나 Wi-Fi 신호 상태에 영향을 덜 받는 Ethernet이 유리합니다.

W5500은 다음과 같은 역할을 수행합니다.

ESP32-S3에 10/100 Mbps 유선 Ethernet 제공

USB 시리얼 데이터를 TCP 네트워크로 전달

Home Assistant 서버와 안정적인 상시 연결 유지

Wi-Fi 사용이 제한되는 환경에서 유선 네트워크 제공

스마트홈 USB 동글을 서버와 물리적으로 분리

이 프로젝트는 ESPHome의 ethernet 컴포넌트와 ESP-IDF 네트워크 구조를 이용해 W5500을 Ethernet 인터페이스로 사용합니다.

따라서 WIZnet ioLibrary의 socket(), send(), recv()와 같은 W5500 하드웨어 Socket API를 애플리케이션에서 직접 제어하는 구조는 확인되지 않습니다.

정확한 분류는 다음과 같습니다.

6. Home Assistant Integration

ESP HA USB Gateway는 Home Assistant와 ESPHome Native API를 통해 연결됩니다.

Home Assistant에서는 다음과 같은 상태를 확인할 수 있습니다.

연결된 USB 장치 수

Gateway Firmware 버전

Gateway IP 주소

설정 페이지 URL

시스템 Uptime

각 USB 장치 이름

장치별 TCP 포트

장치 연결 상태

시스템 재시작 버튼

예를 들어 Home Assistant에서 다음과 같은 정보를 확인할 수 있습니다.

Devices Connected: 1
Firmware: usb-bridge build 2026-04-11-a
IP Address: 192.168.1.108
Device 1 Name: SkyConnect v1.0
Device 1 Port: 8880
Device 1 Status: Connected

각 USB 동글의 연결 여부를 Home Assistant에서 바로 확인할 수 있기 때문에, 장치가 분리되거나 통신에 문제가 발생한 경우 빠르게 파악할 수 있습니다.

7. Zigbee2MQTT Integration

Zigbee2MQTT에서는 USB 장치 경로 대신 Gateway의 TCP 주소를 입력합니다.

예시는 다음과 같습니다.

serial:
  port: tcp://192.168.1.108:8880
  baudrate: 115200
  adapter: ember

이렇게 설정하면 Zigbee2MQTT가 ESP HA USB Gateway를 통해 원격 Zigbee USB 동글에 접속합니다.

Zigbee 센서 데이터는 다음 경로로 전달됩니다.

Zigbee Sensor
      │
Zigbee USB Dongle
      │
ESP32-S3 USB Host
      │
W5500 Ethernet
      │
Zigbee2MQTT
      │
MQTT Broker
      │
Home Assistant

프로젝트는 Zigbee2MQTT, ZHA 및 EnOcean MQTT UI와의 동작이 테스트되었습니다.

8. Web Configuration Interface

Gateway에는 별도의 웹 설정 페이지가 포함되어 있습니다.

사용자는 Gateway의 IP 주소에 접속하여 다음 작업을 수행할 수 있습니다.

연결된 USB 장치 자동 검색

USB 제조사 및 제품 정보 확인

장치별 TCP 포트 할당

장치별 연결 상태 확인

접속 허용 IP 주소 설정

관리자 비밀번호 설정

디버그 로그 확인

USB 장치 정보가 자동으로 감지되기 때문에 사용자가 USB VID, PID 또는 장치 경로를 YAML 파일에 직접 입력할 필요가 없습니다.

장치를 연결한 뒤 웹 UI에서 원하는 TCP 포트만 지정하면 사용할 수 있어, 기존의 USB-to-TCP Gateway보다 설정 과정이 간단합니다.

또한 각 장치에 IP Whitelist를 적용할 수 있어 허용된 Home Assistant 서버만 TCP 포트에 접속하도록 제한할 수 있습니다.

2026년 4월 17일 공개된 v1.0.1 릴리스에는 안정성과 보안 관련 수정 사항이 포함되었습니다.

9. Virtual Machine Migration

이 프로젝트가 해결하는 중요한 문제 중 하나는 가상머신 환경의 USB Passthrough입니다.

기존 구조에서는 Zigbee USB 동글이 특정 Proxmox 또는 ESXi 서버에 물리적으로 연결됩니다.

Zigbee Dongle
     │ USB
Proxmox Host A
     │
Home Assistant VM

이 경우 Home Assistant VM을 다른 서버로 옮기더라도 USB 동글은 기존 서버에 남아 있기 때문에 정상적으로 동작하지 않습니다.

ESP HA USB Gateway를 사용하면 Zigbee 동글이 네트워크 장치로 분리됩니다.

                 ┌─ Proxmox Host A
Zigbee Dongle    │
     │           │
ESP32-S3 Gateway ├─ Ethernet Network
     │           │
W5500 Ethernet   │
                 └─ Proxmox Host B

Home Assistant VM이 어느 서버에서 실행되더라도 동일한 Gateway IP와 TCP 포트로 접속할 수 있습니다.

따라서 다음 기능을 보다 쉽게 사용할 수 있습니다.

Proxmox VM Live Migration

ESXi 가상머신 이전

Home Assistant 서버 교체

서버 장애 시 Backup VM 전환

여러 서버 간 Zigbee Gateway 공유 구조 구축

이 프로젝트의 개발 목표도 USB Passthrough 의존성을 제거하여 Home Assistant VM의 이동성과 운영 편의성을 높이는 것입니다.

10. Difference from a Normal Ethernet Gateway

일반적인 W5500 IoT Gateway는 센서 데이터를 MCU에서 직접 읽어 MQTT 또는 HTTP로 전송합니다.

하지만 ESP HA USB Gateway는 USB 장치가 사용하는 원본 시리얼 프로토콜을 분석하거나 변환하지 않습니다.

일반 IoT Gateway

Sensor Data
    ↓
Protocol Processing
    ↓
MQTT / HTTP
    ↓
Cloud

ESP HA USB Gateway

USB Serial Data
    ↓
TCP Transparent Transmission
    ↓
Zigbee2MQTT / ZHA

USB 동글의 데이터를 그대로 TCP로 투명하게 전달하기 때문에 Zigbee, EnOcean 등 서로 다른 프로토콜의 USB 장치를 하나의 구조에서 지원할 수 있습니다.

즉, 특정 센서 프로토콜에 종속된 Gateway가 아니라 다양한 USB Serial 장치를 네트워크화하는 범용 USB-to-TCP Gateway입니다.

11. Application

ESP HA USB Gateway는 다음과 같은 환경에 활용할 수 있습니다.

Home Assistant Zigbee Gateway

Zigbee2MQTT 원격 Coordinator

ZHA 원격 Zigbee Adapter

EnOcean-to-Network Gateway

FTDI USB Serial Device 원격 연결

CP210X 기반 산업 장치 원격 연결

Proxmox Home Assistant VM

VMware ESXi Home Assistant Server

데이터센터와 스마트홈 장치 간 연결

USB 케이블 거리 제한을 해결하는 Serial Gateway

여러 무선 동글을 통합한 스마트홈 통신 Hub

특히 서버와 Zigbee 네트워크의 최적 설치 위치가 다른 경우 유용합니다.

서버는 네트워크 장비실에 설치하고 Zigbee 동글은 센서가 많은 공간 중앙에 배치한 뒤, 두 장치를 Ethernet으로 연결할 수 있습니다.

12. WIZnet Perspective

이 프로젝트에서 W5500은 단순히 ESP32-S3에 Ethernet 포트를 추가하는 역할을 넘어, USB 스마트홈 장치를 안정적인 TCP 네트워크 장치로 변환하는 핵심 통신 인터페이스입니다.

Zigbee와 EnOcean USB 동글은 일반적으로 서버의 USB 포트에 종속되지만, W5500 Ethernet을 사용하면 물리적인 USB 연결을 IP 네트워크 연결로 변경할 수 있습니다.

이를 통해 다음과 같은 장점을 얻을 수 있습니다.

USB 장치의 설치 위치 자유도 향상

USB 연장 케이블 제한 제거

Wi-Fi보다 안정적인 유선 연결

Home Assistant 서버와 USB 동글 분리

가상머신 Live Migration 지원

USB 동글 장애 및 연결 상태 원격 확인

여러 종류의 USB Serial 장치 네트워크화

즉, W5500은 Zigbee 데이터를 직접 처리하는 것이 아니라 ESP32-S3에서 변환된 USB Serial 데이터를 Home Assistant 서버까지 안정적으로 전달하는 유선 네트워크 경로를 제공합니다.

Conclusion

ESP HA USB Gateway는 ESP32-S3의 USB Host 기능과 WIZnet W5500 Ethernet을 결합하여 Zigbee, EnOcean, FTDI 및 CP210X USB 장치를 TCP 네트워크로 연결하는 오픈소스 Gateway입니다.

USB 동글을 Home Assistant 서버에 직접 연결하지 않고 원격 위치에 설치할 수 있으며, Zigbee2MQTT, ZHA, EnOcean MQTT UI 등에서 TCP 방식으로 사용할 수 있습니다.

웹 기반 USB 장치 자동 감지, TCP 포트 설정, IP 접근 제한, Home Assistant 상태 센서 등의 기능을 제공하여 단순한 USB Serial 변환 예제보다 완성도 높은 스마트홈 네트워크 플랫폼을 구성합니다.

특히 W5500 Ethernet을 통해 USB Passthrough 의존성을 제거함으로써 Proxmox나 ESXi에서 Home Assistant 가상머신을 자유롭게 이동할 수 있다는 점이 이 프로젝트의 가장 큰 특징입니다.

SHORT SUMMARY

ESP HA USB Gateway는 ESP32-S3와 WIZnet W5500을 기반으로 Zigbee, EnOcean, FTDI 및 CP210X USB 장치를 TCP 네트워크로 연결하는 스마트홈 Gateway입니다. USB 동글을 Home Assistant 서버에 직접 연결하지 않고 Ethernet을 통해 원격으로 사용할 수 있으며, Zigbee2MQTT, ZHA 및 EnOcean 시스템과 연동됩니다. 이를 통해 USB 케이블 거리와 USB Passthrough 제약을 해결하고 Proxmox 또는 ESXi 환경에서 Home Assistant 가상머신의 이동성과 운영 안정성을 높일 수 있습니다.