Overview

This project provides firmware for building a transparent Layer 2 bridge between an Ethernet port and a WiFi access point on ESP32-based hardware. Its main purpose is not to create a routed WiFi network, but to make Ethernet-side and WiFi-side devices appear as part of the same LAN segment. The repository explicitly describes the design as “no NAT, no routing, no separate subnet,” with Ethernet and WiFi AP sharing one broadcast domain.

The firmware is derived from an ESP32 NAT router project, but its behavior is intentionally different: instead of translating or routing IP traffic, it forwards frames at the MAC layer. This changes the system role from “small router” to “transparent bridge,” which is a significant architectural distinction rather than a minor feature change.

Main Content

The system targets cases where WiFi clients need direct Layer 2 access to an existing wired LAN. The documented use cases include wireless extension for a wired network, lab bridging, transparent monitoring through packet capture, and connecting headless IoT devices to an existing LAN without changing their network model.

The project supports two compile-time hardware variants. The default target is WT32-ETH01, using ESP32 with an integrated LAN8720 Ethernet PHY. A second variant targets ESP32-C3 SuperMini with a WIZnet W5500 SPI Ethernet chip, where the W5500 provides the wired Ethernet interface over SPI. The repository lists the W5500 wiring and notes an Ethernet speed path through SPI at about 26.67 MHz.

For the W5500 variant, the WIZnet W5500 is not just a named component. It is the external Ethernet controller that lets an ESP32-C3 board participate in a wired Ethernet segment through SPI. WIZnet documents W5500 as a hardwired TCP/IP stack internet controller with SPI support up to 80 MHz and an embedded 10/100 Ethernet MAC and PHY, while this project uses it as the Ethernet-side interface feeding the bridge path.

The firmware also includes practical management features: a browser-based configuration interface, serial console, optional management IP, OTA firmware update, remote console, syslog forwarding, byte counters, and packet capture streaming to Wireshark over TCP. These features make the device more than a bare frame forwarder, but they remain secondary to the central bridge behavior.

System Context

A conventional low-cost WiFi router typically creates a separate subnet, assigns addresses through its own DHCP service, and routes or NATs traffic between interfaces. This project avoids that model. WiFi clients receive their IP addresses from the upstream network’s DHCP server, and devices on the wired side can directly reach them as peers on the same network.

That design makes the bridge useful when the goal is network transparency rather than traffic isolation. It can help in bench testing, embedded device access, protocol debugging, and temporary wireless access to a wired segment. It is less suited to cases where the WiFi side must be isolated, firewalled, bandwidth-managed, or placed behind NAT.

The most failure-sensitive part of the system is the Layer 2 forwarding boundary. If forwarding, MAC learning, DHCP relay behavior through the bridge, or broadcast handling is wrong, the visible symptom may not be a simple “device offline” state. It can become intermittent DHCP failure, duplicate reachability problems, broadcast flooding, or misleading packet capture results. In a transparent bridge, small forwarding mistakes are annoyingly good at pretending to be someone else’s network problem.

Architecture / Design Considerations

The architecture separates the physical ports from the management interface. The Ethernet port and WiFi AP port are bridge ports without their own ordinary IP role, while the bridge interface can obtain a management IP through DHCP or static configuration. The source code defines separate objects for the bridge virtual interface, Ethernet physical port, and WiFi AP physical port, which reflects this split.

The bridge is built around ESP-IDF networking components, including ESP netif bridge glue and lwIP bridge behavior. The code shows Ethernet and WiFi AP being added as two bridge ports, with the bridge interface acting as the network-facing management endpoint.

Packet monitoring is implemented by hooking into lwIP network interface input and output paths. The project’s hook file is described as intercepting packets on both Ethernet and AP bridge port interfaces for byte counting and PCAP capture. This is important because a transparent bridge often needs observability without changing client configuration.

Removing specific components would change the system’s character. Without the Ethernet interface, the firmware becomes merely a WiFi AP management shell. Without the WiFi AP, it no longer extends wired access to wireless clients. Without Layer 2 bridging, it becomes closer to a router or NAT gateway. Without management and capture features, it still remains a bridge, but becomes much harder to diagnose and operate.

Possible Implications

The key difference from the project’s NAT-router origin is the removal of IP-layer separation. That is useful when the network must remain flat and discoverable, especially for protocols that depend on broadcast, multicast, or same-subnet assumptions. It is also a tradeoff: the WiFi side inherits the wired LAN’s broadcast domain, and the wired LAN directly sees WiFi clients.

This design is best understood as an auxiliary network access tool, not a replacement for a managed access point or enterprise bridge. Its value is in portability, transparency, and inspectability on ESP32-class hardware. Its limits are also clear: WiFi radio quality, ESP32 processing capacity, SPI Ethernet performance in the W5500 variant, and bridge forwarding behavior all define the practical ceiling.

Conclusion

This repository is a focused ESP32 firmware project for transparent Ethernet-to-WiFi Layer 2 bridging. Its main technical value is the decision to keep both sides in a single broadcast domain, allowing WiFi clients to behave like direct participants in the wired LAN. The WIZnet W5500 variant extends that model to ESP32-C3 hardware by using W5500 as the SPI-based Ethernet interface, while preserving the same bridge-oriented firmware role.

KR – Internal / Presentation

전체 개요

이 프로젝트는 ESP32 계열 보드를 작은 유무선 공유기처럼 쓰는 것이 아니라, 유선 Ethernet과 WiFi AP를 같은 LAN 안에 묶어주는 계층2 브리지로 동작시키는 펌웨어입니다.

핵심은 단순합니다.

Ethernet 쪽 장비와 WiFi로 붙은 장비가 서로 다른 네트워크가 아니라, 같은 네트워크에 있는 것처럼 보이게 합니다.

저장소 설명에서도 이 프로젝트는 NAT, 라우팅, 별도 서브넷을 만들지 않는다고 명시되어 있습니다. 즉 WiFi 클라이언트는 ESP32가 새로 만든 내부망에서 IP를 받는 것이 아니라, 기존 유선망의 DHCP 서버에서 IP를 받습니다.

이 점이 가장 중요합니다. 보통 “ESP32로 WiFi 공유기 만들기”라고 하면 NAT 라우터를 떠올리기 쉽습니다. 그런데 이 프로젝트는 그 방향이 아닙니다. 라우터가 아니라 브리지입니다. 이름 하나 바뀐 것 같지만, 네트워크 구조상으로는 꽤 큰 차이입니다. 인간은 늘 이름을 대충 붙이고 나중에 장애 분석 때 고통받죠.

문제의식과 기술적 맥락 재구성

기존 유선 LAN에 어떤 장비가 있고, 여기에 WiFi 장비를 임시로 붙이고 싶다고 가정하겠습니다.

일반적인 방법은 다음과 같습니다.

1. 무선 공유기나 AP를 설치합니다.
2. NAT 또는 별도 서브넷이 생깁니다.
3. WiFi 장비와 유선 장비 사이의 직접 탐색, 브로드캐스트, 멀티캐스트, 일부 장비 자동 검색이 어긋날 수 있습니다.

이 프로젝트는 이 문제를 다르게 풉니다.

ESP32 기반 장치를 중간에 두고, 한쪽은 Ethernet, 다른 한쪽은 WiFi AP로 열어둔 뒤, 두 인터페이스 사이에서 MAC 프레임을 전달합니다. 그래서 WiFi 클라이언트는 “ESP32 뒤의 별도 네트워크”가 아니라 “기존 LAN에 직접 붙은 장비”처럼 보입니다. 저장소는 이 구조를 순수 Layer 2 bridge로 설명하고, Ethernet 포트와 WiFi AP가 하나의 broadcast domain을 공유한다고 밝히고 있습니다.

추론임: 이 프로젝트의 실용적 출발점은 “라우터 기능을 많이 넣은 장비”보다 “네트워크 구조를 바꾸지 않고 유선망을 무선으로 살짝 확장하는 도구”에 더 가깝습니다. 특히 실험실, 벤치 테스트, IoT 장비 접근, 패킷 관찰 같은 상황에서 의미가 큽니다.

기술 흐름 설명

동작 흐름은 다음처럼 이해하면 됩니다.

기존 유선 LAN
    │
    │ Ethernet
    ▼
[ ESP32 계열 보드 ]
    │
    ├─ Ethernet 포트
    │   - WT32-ETH01: LAN8720 PHY
    │   - ESP32-C3 변형: WIZnet W5500 SPI Ethernet
    │
    ├─ Layer 2 Bridge
    │   - MAC 프레임 전달
    │   - 같은 broadcast domain 유지
    │   - 브리지 관리 IP 선택 가능
    │
    └─ WiFi AP
        │
        ▼
    WiFi 클라이언트

WiFi 클라이언트가 접속하면, 클라이언트는 ESP32 내부 DHCP 서버에서 IP를 받는 구조가 아닙니다. 기존 유선망의 DHCP 서버에서 주소를 받습니다. 이 때문에 유선 장비 입장에서는 WiFi 클라이언트가 같은 네트워크 안에 있는 장비처럼 보입니다.

관리 관점에서는 브리지 자체가 별도의 관리 IP를 가질 수 있습니다. 이 IP는 정적 설정 또는 DHCP로 얻을 수 있으며, 웹 UI나 원격 관리에 사용됩니다. 중요한 점은 이 관리 IP가 브리지 장치 관리를 위한 것이지, WiFi 클라이언트를 위한 별도 라우팅 경계가 아니라는 점입니다.

왜 이런 구조가 나왔는지에 대한 해설

이 프로젝트는 esp32_nat_router에서 파생되었다고 설명되어 있습니다. 원래 NAT 라우터 프로젝트는 WiFi NAT 라우터 성격이 강하지만, 이 저장소는 그중 일부 기반을 가져와 라우팅 장비가 아니라 투명 브리지 장비로 성격을 바꾼 것입니다.

여기서 핵심 차이는 다음입니다.

추론임: 이 구조는 “관리된 네트워크 장비”보다는 “작고 빠르게 붙이는 투명 네트워크 보조 장치”에 가깝습니다. 그래서 기업용 AP나 스위치를 대체한다기보다, 특정 실험이나 연결 문제를 단순하게 풀기 위한 보조 수단으로 보는 것이 정확합니다.

설계 선택의 배경

1. Layer 2 브리지 선택

Layer 2 브리지는 IP 주소를 새로 나누거나 NAT를 하지 않고, MAC 주소 기반으로 프레임을 넘깁니다. 이 방식은 같은 서브넷에 있어야 잘 동작하는 장비 검색, DHCP, 일부 IoT 프로토콜, 브로드캐스트 기반 도구와 궁합이 좋습니다.

반대로 보안 격리나 트래픽 정책 제어가 필요하면 불리합니다. WiFi 클라이언트를 기존 유선망과 같은 broadcast domain에 넣는다는 것은 편리함과 위험을 동시에 가져옵니다. 세상 모든 편의 기능이 그렇듯, 공짜 점심은 없고 청구서는 장애 분석 때 날아옵니다.

2. ESP32 사용

ESP32는 WiFi 기능과 임베디드 처리 능력을 가진 MCU입니다. WT32-ETH01은 ESP32에 LAN8720 Ethernet PHY가 붙은 형태이고, 이 프로젝트의 기본 하드웨어 변형으로 제시됩니다.

3. WIZnet W5500 변형 지원

ESP32-C3 SuperMini + W5500 변형은 외부 SPI Ethernet 칩을 사용합니다. 저장소는 W5500의 MISO, MOSI, SCLK, CS, INT, RST 연결 GPIO와 SPI 기반 Ethernet 구성을 명시하고 있습니다.

WIZnet W5500은 SPI로 MCU와 연결되는 Ethernet 컨트롤러이며, WIZnet 문서상 10/100 Ethernet MAC/PHY를 내장하고 SPI 최대 80 MHz 인터페이스를 제공합니다. 이 프로젝트에서는 W5500이 “TCP/IP 오프로더”로 전면 활용된다기보다, ESP32-C3 보드에 유선 Ethernet 포트를 부여하는 하드웨어 인터페이스 역할로 이해하는 편이 안전합니다.

추론임: W5500 변형의 장점은 ESP32-C3처럼 내장 Ethernet MAC이 없는 구성에서도 Ethernet-WiFi 브리지를 만들 수 있게 해주는 것입니다. 다만 SPI Ethernet 경로는 SPI 클럭, 인터럽트 처리, 버퍼링, 드라이버 안정성에 영향을 받기 때문에, 고성능 브리지라기보다 소형 임베디드 브리지로 보는 것이 맞습니다.

제약 조건

이 시스템에서 실패 비용이 가장 큰 구간은 브리지 경계의 프레임 전달과 MAC 처리입니다.

특히 다음 지점이 민감합니다.

1. DHCP 프레임 전달
   • WiFi 클라이언트가 기존 DHCP 서버에서 IP를 받아야 하므로, DHCP Discover/Offer 흐름이 브리지에서 깨지면 접속은 되어도 IP를 못 받는 상황이 생깁니다.
2. 브로드캐스트/멀티캐스트 처리
   • 같은 LAN처럼 보이게 하는 장점은 브로드캐스트 전달에 의존합니다.
   • 하지만 잘못 처리하면 불필요한 트래픽 증가나 탐색 실패가 생길 수 있습니다.
3. MAC 주소 학습과 로컬 MAC 필터링
   • 브리지 자신에게 향한 프레임과 양쪽 포트로 전달해야 할 프레임을 구분해야 합니다.
   • 소스 코드에는 브리지 MAC, AP MAC, 로컬 유니캐스트 목적지를 구분하는 훅 로직이 보입니다. 
4. W5500 SPI 경로
   • W5500 변형에서는 Ethernet 프레임이 SPI를 통해 오갑니다.
   • 저장소는 W5500 빌드 전용으로 SPI 클럭 설정, W5500 상태 확인, SPI 에러 카운터 확인 명령을 제공합니다. 

추론임: 실제 현장에서 가장 귀찮은 장애는 “완전히 안 됨”이 아니라 “가끔 DHCP가 실패함”, “일부 장비만 검색이 안 됨”, “Wireshark에는 보이는데 통신은 이상함” 같은 형태일 가능성이 큽니다. 이런 문제는 브리지, DHCP, WiFi 품질, SPI Ethernet 경로가 서로 책임을 떠넘기는 아름다운 지옥을 만듭니다.

대안 가능성

이 프로젝트와 비교할 수 있는 대안은 다음과 같습니다.

따라서 이 프로젝트는 “전체 네트워크 인프라”보다는 “특정 구간을 간단히 유무선으로 이어주는 보조 장치”로 보는 것이 좋습니다.

생소한 개념에 대한 풀어쓴 설명

Layer 2 브리지

Layer 2는 Ethernet 프레임과 MAC 주소가 중심인 계층입니다. IP 주소를 보고 라우팅하는 것이 아니라, MAC 주소를 기준으로 어느 쪽 포트로 프레임을 넘길지 결정합니다.

쉽게 말하면, “네트워크 주소를 새로 나누는 관리자”가 아니라 “양쪽 케이블과 무선 사이에서 프레임을 전달하는 중계자”입니다.

NAT

NAT는 내부 네트워크의 여러 장비가 하나의 외부 IP처럼 보이도록 주소를 변환하는 방식입니다. 집 공유기가 흔히 쓰는 방식입니다.

이 프로젝트는 NAT를 하지 않습니다. 그래서 WiFi 클라이언트가 기존 LAN 안의 장비처럼 보입니다.

Broadcast Domain

브로드캐스트 도메인은 브로드캐스트 패킷이 퍼지는 네트워크 범위입니다. 같은 브로드캐스트 도메인에 있으면 DHCP, ARP, 일부 장비 탐색이 자연스럽게 동작합니다.

이 프로젝트는 Ethernet과 WiFi AP를 같은 브로드캐스트 도메인에 놓는 것을 핵심으로 합니다.

PCAP Streaming

PCAP은 Wireshark 같은 도구에서 패킷을 분석할 때 사용하는 캡처 형식입니다. 이 프로젝트는 브리지 트래픽을 TCP 포트 19000으로 스트리밍해서 Wireshark에서 볼 수 있게 합니다.

이 기능은 단순 장식이 아닙니다. 투명 브리지에서는 문제가 생겼을 때 “어느 쪽에서 패킷이 사라지는지”를 확인하는 것이 중요합니다.

시스템 구성 및 선택지 해석

기본 구성: WT32-ETH01

WT32-ETH01 구성은 ESP32와 LAN8720 Ethernet PHY를 사용하는 형태입니다. 저장소 기준 기본 변형이며, 내부 EMAC 기반 Ethernet 구성을 사용합니다.

이 구성은 Ethernet 기능이 통합된 보드 기반이라 배선 복잡도가 낮습니다. 단, 보드 자체의 제약과 ESP32 WiFi 성능 한계를 고려해야 합니다.

변형 구성: ESP32-C3 SuperMini + WIZnet W5500

이 구성은 ESP32-C3에 WIZnet W5500 SPI Ethernet 칩을 붙이는 방식입니다. W5500은 SPI로 Ethernet 기능을 제공하며, 프로젝트는 약 26.67 MHz SPI Ethernet 구성을 문서화하고 있습니다.

이 변형은 작은 ESP32-C3 보드에 유선 Ethernet 기능을 추가할 수 있다는 점에서 의미가 있습니다. 다만 SPI 클럭, 배선, 인터럽트, 드라이버 상태가 통신 안정성에 직접 영향을 줄 수 있습니다.

관리 기능

저장소는 웹 UI, 시리얼 콘솔, 원격 콘솔, syslog, OTA, byte counter, Wireshark용 PCAP 스트리밍을 제공합니다.

이 기능들은 브리지 자체의 본질은 아니지만, 현장에서 문제를 확인하고 설정을 바꾸는 데 중요합니다. 특히 packet capture와 byte counter는 브리지 장비에서 꽤 실용적인 진단 도구입니다.

내부 관점에서의 시사점

이 프로젝트는 WIZnet 관점에서도 꽤 쓸 만한 큐레이션 대상입니다.

첫째, W5500이 “인터넷 연결용 칩”이라는 일반 설명을 넘어, ESP32-C3 기반 L2 브리지의 Ethernet 포트 역할을 수행하는 사례로 볼 수 있습니다. 단순히 센서 데이터를 서버로 보내는 예제보다 네트워크 구조가 더 분명합니다.

둘째, 이 프로젝트는 W5500의 성능을 과장해서 보여주는 사례가 아니라, SPI Ethernet이 실제 시스템 안에서 어디에 들어가고 어떤 제약을 갖는지 보여줍니다. 이게 오히려 기술적으로 더 정직합니다. 홍보 문구는 달콤하지만 디버깅 로그는 늘 무례하니까요.

셋째, “W5500을 쓰면 모든 네트워크 문제가 해결된다”가 아닙니다. W5500은 Ethernet 쪽 인터페이스를 제공하고, 브리징·WiFi AP·관리 UI·패킷 캡처는 ESP32 펌웨어와 네트워크 스택의 몫입니다. 이 역할 분리를 설명해야 기술 설득력이 생깁니다.

넷째, 특정 구성요소를 제거하면 시스템 성격이 바뀝니다.

따라서 이 프로젝트의 본질은 “ESP32로 만든 WiFi AP”가 아니라 Ethernet과 WiFi AP 사이의 투명한 계층2 연결을 ESP32급 하드웨어로 구현한 펌웨어입니다.

FAQ

1. 기존 ESP32 NAT 라우터와 가장 큰 차이는 무엇입니까?

가장 큰 차이는 IP 계층에서 라우팅하거나 NAT를 하지 않는다는 점입니다. 이 프로젝트는 Ethernet과 WiFi AP를 같은 브로드캐스트 도메인에 놓고 MAC 계층에서 프레임을 전달합니다. 그래서 WiFi 클라이언트가 별도 내부망 장비가 아니라 기존 LAN의 장비처럼 보입니다.

2. 왜 Layer 2 브리지 구조를 선택한 것으로 볼 수 있습니까?

공개 설명 기준으로는 WiFi 클라이언트가 upstream DHCP 서버에서 IP를 받고, 유선 쪽에서 직접 접근 가능하도록 만드는 것이 목표입니다. 이 요구는 NAT 라우터보다 Layer 2 브리지에 더 잘 맞습니다. 추론임: 장비 자동 검색, DHCP, ARP, 브로드캐스트 기반 프로토콜을 그대로 통과시키려는 목적이 설계 배경으로 볼 수 있습니다.

3. WIZnet W5500은 이 시스템에서 어떤 역할입니까?

ESP32-C3 SuperMini 변형에서 W5500은 SPI로 연결되는 유선 Ethernet 인터페이스 역할을 합니다. WIZnet 문서상 W5500은 SPI 기반 Ethernet 컨트롤러이며 10/100 Ethernet MAC/PHY를 내장합니다. 이 프로젝트에서는 W5500이 브리지의 유선 포트 쪽 하드웨어 경로를 담당한다고 보는 것이 정확합니다.

4. 실패 비용이 가장 큰 판단 지점은 어디입니까?

가장 민감한 구간은 Ethernet과 WiFi AP 사이의 Layer 2 forwarding 경계입니다. DHCP, ARP, 브로드캐스트, MAC 학습, 로컬 MAC 필터링이 어긋나면 네트워크가 “대충 붙은 것처럼 보이지만 실제로는 불안정한” 상태가 될 수 있습니다. 특히 W5500 변형에서는 SPI 클럭과 에러 카운터도 함께 봐야 합니다.

5. 이 프로젝트는 상용 AP나 공유기를 대체할 수 있습니까?

그렇게 보는 것은 과합니다. 이 프로젝트는 투명한 LAN 확장, 실험실 브리지, 패킷 관찰, 임시 IoT 연결 같은 보조적 목적에 더 적합합니다. 보안 격리, 대규모 클라이언트 관리, 고성능 무선 품질이 필요하면 상용 AP나 관리형 네트워크 장비가 더 적절합니다.

6. PCAP 스트리밍 기능은 왜 중요합니까?

투명 브리지에서는 문제가 생겼을 때 어느 방향에서 패킷이 사라지는지 확인하기 어렵습니다. 이 프로젝트는 TCP 포트 19000을 통해 Wireshark로 트래픽을 스트리밍할 수 있다고 설명합니다. 이 기능은 단순 모니터링이 아니라, 브리지 장애 분석의 핵심 보조 수단입니다.

저자 정보

GitHub 사용자명은 martin-ger입니다. 공개 GitHub 프로필에는 위치가 Wiesbaden, Germany로 표시되어 있으며, 공개 저장소로 esp32_nat_router, esp32_ethernet_router, esp_wifi_repeater, uMQTTBroker, esp_slip_router 등이 확인됩니다.

공개 저장소 목록을 기준으로 보면, 네트워크 기능을 ESP32/ESP8266 계열 임베디드 환경에 구현하는 작업 경험이 상당히 축적된 개발자로 해석할 수 있습니다. 추론임: 특히 NAT router, WiFi repeater, Ethernet router, SLIP router 계열 저장소가 반복적으로 등장하므로, 관심 영역은 임베디드 네트워킹과 소형 라우팅/브리징 펌웨어 쪽으로 보는 것이 자연스럽습니다.

다만 실명, 소속 기관, 직업 이력, 학술적 배경은 GitHub 공개 프로필만으로는 충분히 확인되지 않습니다. 정보 제한: 따라서 저자의 공식 소속이나 경력 사항은 단정하지 않는 것이 맞습니다.