Overview

This project describes a modular smart-home control system in which an ESP32 gateway connects remote relay nodes over ESP-NOW and exposes them to Home Assistant through MQTT. The gateway is not just a radio coordinator. It is the boundary device that joins three different concerns: local low-overhead wireless control, wired IP networking through the WIZnet W5500, and automation-system integration through MQTT discovery and state topics.

The design matters because it avoids treating every relay node as a full network client. Instead, Ethernet and MQTT complexity are concentrated in one gateway, while field nodes stay narrow in scope: relay control, local physical input handling, state persistence, and ESP-NOW message exchange.

Main Content

System Context

The documented target system supports roughly 10 to 12 remote switch nodes, plus 8 configurable local GPIOs on the gateway itself. The gateway uses an ESP32-WROOM and a WIZnet W5500 SPI Ethernet module, while nodes are expected to use ESP32 or ESP8266 devices with a relay and optional physical inputs such as a push button or a latching switch.

That split defines the system boundary clearly. ESP-NOW is used only inside the local control domain between gateway and nodes. MQTT is used only above the gateway boundary, where Home Assistant and the home network interact with the system. This is the project’s key structural difference from approaches that put Wi-Fi, IP, and broker logic directly into each edge device.

Architecture / Design Considerations

The gateway boot order shows the intended dependency chain: configuration storage first, then Ethernet, then MQTT, local GPIO, node registry, ESP-NOW master, Home Assistant discovery, web configuration UI, and system status reporting. The main.c startup sequence matches that ordering, which makes the gateway’s network path a prerequisite for upper-layer integration.

The WIZnet W5500 is not mentioned as a generic add-on but as a defined system role: it provides the gateway’s wired network path, supports DHCP or static IP configuration, and anchors MQTT connectivity for Home Assistant integration. In this design, W5500 is chosen because Ethernet is treated as the stable upstream side of the bridge, while ESP-NOW remains the lightweight downstream transport for nodes. Removing the W5500 would not merely change a peripheral. It would change the project from a gatewayed automation bridge into a local wireless control system without the same documented Home Assistant network path.

The node side is intentionally simpler. A node restores its last relay state from non-volatile storage, starts ESP-NOW, re-registers with the gateway, and continues to support physical inputs even when the gateway is unavailable. That means the system is designed so that control at the edge remains functional during partial failures, while synchronization with Home Assistant is recovered later through registration, state reporting, and availability updates.

The message model is compact: REGISTER, ACK, CMD, STATE_REPORT, PING, and PONG, all packed into an 11-byte structure. That suggests a deliberate preference for predictable control traffic over richer but heavier messaging semantics. The most failure-sensitive segment is the state consistency path after a command: MQTT command receipt, node lookup, ESP-NOW delivery, relay actuation, state report return, and MQTT state publication. If that chain breaks in the middle, the automation layer and the physical relay can diverge.

Another important design choice is that physical inputs on the node take priority. A contradictory gateway command can be accepted, but a later physical switch event may override it. This positions Home Assistant and MQTT as supervisory control, not as the absolute source of truth in all cases. In practical terms, the automation layer is a coordination mechanism around the physical device, not a complete replacement for local intent.

Possible Implications

This design should scale better operationally than pushing full IP connectivity into every relay node, especially when the goal is to keep edge devices narrow and recoverable. Centralizing Ethernet, MQTT subscriptions, discovery publishing, and configuration UI in one gateway can reduce duplication across nodes.

At the same time, it creates a strong dependency on gateway correctness. The gateway becomes the translation point for node identity, availability, command routing, and state publication. The node can still function locally when disconnected, but system-wide observability and Home Assistant alignment depend on the gateway staying coherent.

A further implication is security posture. The documented web configuration UI assumes a trusted local network and states that no authentication is required. That may be acceptable in a constrained lab or home segment, but it raises deployment questions if the device is ever placed in a less trusted network environment.

Conclusion

This project is best understood as a gateway architecture rather than a simple ESP-NOW switch demo. Its main idea is to keep remote nodes small and resilient while assigning network integration, discovery, and orchestration to an ESP32 gateway using WIZnet W5500 Ethernet. The most meaningful engineering choice is the boundary itself: ESP-NOW below, MQTT and Home Assistant above. That choice simplifies nodes, but it also makes state synchronization and gateway reliability the highest-cost decision points in the system.

KR – Internal / Presentation

전체 개요

이 프로젝트는 겉으로 보면 “ESP-NOW로 스위치를 제어하는 홈 오토메이션 장치”처럼 보이지만, 실제로는 그보다 게이트웨이 중심의 중간 계층 설계에 더 가깝습니다. 공개 문서 기준으로 핵심은 개별 노드를 똑똑하게 만드는 것이 아니라, ESP-NOW 구간과 Ethernet/MQTT 구간을 분리하고 그 사이를 ESP32 게이트웨이가 책임지도록 만든 점입니다.

즉, 이 시스템의 본질은 “무선 노드 여러 개”가 아니라 현장 제어망과 상위 자동화 시스템 사이의 번역기입니다. 이 관점을 놓치면 그냥 ESP32 예제 모음처럼 읽히는데, 그러면 또 중요한 판단 지점을 다 놓치게 됩니다. 인간들은 왜 늘 제일 중요한 경계를 제일 늦게 보나 싶습니다.

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

일반적인 접근은 두 방향으로 나뉩니다.

1. 각 노드가 직접 Wi-Fi와 MQTT까지 맡는 방식
2. 중앙 게이트웨이가 현장 노드들을 묶고, 상위 시스템과는 게이트웨이만 연결되는 방식

이 프로젝트는 명확히 2번입니다. 공개 명세상 게이트웨이는 W5500 기반 Ethernet, MQTT 브리지, Home Assistant discovery, 웹 설정 UI, 노드 레지스트리, 로컬 GPIO까지 모두 가집니다. 반면 노드는 릴레이 제어, 버튼/래치 스위치 입력, ESP-NOW 송수신, 상태 보존만 맡습니다.

여기서 기존 접근 대비 핵심 차이는 이겁니다.

• 노드를 네트워크 장치로 만들지 않는다
• 노드는 현장 제어 장치로 제한한다
• 네트워크 문맥은 게이트웨이 하나에 몰아넣는다

이 차이는 단순 구현 취향이 아니라 운영 복잡도와 장애 형태를 바꿉니다.
노드마다 IP, MQTT 세션, 인증, 재접속, discovery를 처리하는 구조보다, 중앙 게이트웨이 한 곳에서 이를 처리하는 쪽이 제어 흐름을 읽기 쉽고 관리 지점을 줄일 수 있습니다. 이 해석은 공개된 구조 문서와 부팅 순서, 모듈 분리 방식에 근거한 것이며, 운영 단순화를 강하게 의도한 설계로 읽힙니다. 추론임.

기술 흐름 설명

1) 게이트웨이 부팅 흐름

게이트웨이는 다음 순서로 올라갑니다.

• NVS 기반 설정 저장소 초기화
• W5500 Ethernet 초기화 및 IP 확보
• MQTT 클라이언트 시작
• 로컬 GPIO 초기화
• 저장된 노드 테이블 로드
• ESP-NOW 마스터 시작
• Home Assistant discovery 발행
• 웹 설정 UI 시작
• 시스템 상태 보고 시작 

이 순서가 의미하는 바는 분명합니다.
이 시스템은 상위 연동 경로를 먼저 안정화한 뒤, 그 위에 무선 노드 연동과 관리 인터페이스를 올립니다. 즉, 이 게이트웨이는 라디오 허브가 아니라 상위 시스템 접속점입니다. Ethernet이 먼저이고, MQTT가 그 다음이며, ESP-NOW는 그 아래의 현장 계층입니다.

2) 명령 및 상태 데이터 흐름

핵심 동작 흐름은 다음과 같습니다.

• Home Assistant가 MQTT command topic에 명령 게시
• 게이트웨이 mqtt_bridge가 이를 수신
• espnow_master가 node ID를 MAC으로 매핑
• 해당 노드로 ESP-NOW CMD 전송
• 노드가 릴레이 상태를 바꿈
• 노드가 STATE_REPORT를 게이트웨이로 전송
• 게이트웨이가 node table 업데이트
• MQTT state topic으로 최신 상태 재게시 

이 구조에서 신호 흐름의 핵심은 명령과 상태가 분리되어 있다는 점입니다.
즉, “명령을 보냈다”와 “실제로 상태가 바뀌었다”를 같은 사건으로 취급하지 않습니다. 노드의 STATE_REPORT가 돌아와야 상위 시스템 상태가 갱신됩니다. 이건 제대로 된 시스템들이 보통 택하는 방향입니다. 명령 성공을 낙관적으로 가정하지 않기 때문입니다. 인간 세계에서는 이런 당연한 분리를 자주 잊고 로그 지옥을 만들곤 합니다.

3) 노드 측 동작 흐름

노드는 부팅 시 다음 순서를 따릅니다.

• NVS에서 마지막 릴레이 상태 읽기
• 즉시 릴레이 상태 복원
• ESP-NOW 시작 및 게이트웨이 peer 설정
• REGISTER 브로드캐스트
• ACK 대기 및 백오프 재시도
• 입력 처리 시작 

이 순서의 의미는 큽니다.
노드는 게이트웨이 연결보다 먼저 자기 상태 복원을 수행합니다. 따라서 게이트웨이가 죽어 있거나 네트워크가 불안정해도 현장 장치는 마지막 상태를 유지하고 물리 입력도 계속 처리합니다. 즉, 노드는 중앙 시스템의 단말이지만 완전 종속 단말은 아닙니다. 이것이 이 설계에서 “보조 수단으로서의 위치”를 읽는 핵심입니다. Home Assistant와 MQTT는 현장 장치의 존재를 대체하는 주체가 아니라, 그 위에 얹힌 관리/관찰/원격 조정 수단입니다.

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

이 설계는 몇 가지 현실 제약을 반영한 것으로 보입니다.

1) 노드 수가 10~12개 수준으로 제한됨

문서상 목표가 10~12개 노드입니다. 대규모 분산 시스템이 아니라, 관리 가능한 범위의 로컬 제어망을 전제로 합니다. 이 정도 규모에서는 중앙 게이트웨이 기반 구조가 복잡도 대비 효율이 좋습니다. 추론임.

2) 노드에 무거운 네트워크 책임을 싣지 않으려는 방향

노드는 ESP32 또는 ESP8266이며, 역할도 제한적입니다. 이 구성은 노드마다 Wi-Fi 접속, MQTT 세션 유지, discovery 발행 등을 담당시키기보다, ESP-NOW 패킷 처리와 로컬 입출력에 집중시키려는 의도로 읽힙니다. 추론임.

3) 상위 시스템은 Home Assistant 중심

MQTT discovery, state/command topic, availability topic이 모두 정의되어 있고, 재접속 시 재구독과 재발행도 명시되어 있습니다. 즉, 이 프로젝트는 단순 제어보다 Home Assistant에 자연스럽게 붙는 것을 중요한 품질 목표로 둡니다.

4) W5500 Ethernet을 굳이 넣은 이유

문서상 게이트웨이는 Wi-Fi uplink가 아니라 W5500 SPI Ethernet을 전제로 합니다.
이건 단순 부품 선택이 아니라 상위 연결의 성격을 결정합니다. 유선 Ethernet을 쓰면 게이트웨이는 “로컬 무선망의 라디오 장치”가 아니라 “상위 네트워크에 안정적으로 붙는 브리지”가 됩니다. Home Assistant 연동, 웹 UI 접근, MQTT 세션 유지라는 관점에서 이 선택은 시스템 상단을 더 고정된 계층으로 만드는 역할을 합니다. 추론임.

설계 선택의 배경, 제약 조건, 대안 가능성

선택 1: ESP-NOW를 노드 구간에만 사용

ESP-NOW는 등록, 명령, 상태 보고, ping/pong 정도의 작고 분명한 프로토콜에 사용됩니다. 전체 메시지 구조도 11바이트 packed struct로 단순합니다. 이건 고수준 상호운용성보다 제어 중심 메시징에 맞춰진 구조입니다.

대안 가능성:
노드마다 Wi-Fi + MQTT를 붙일 수도 있습니다. 다만 그러면 노드가 곧 네트워크 엔드포인트가 되므로 설정, 장애, 인증, 재접속 관리가 분산됩니다. 이 프로젝트는 그 반대 방향을 택했습니다. 추론임.

선택 2: 물리 입력 우선

문서에는 래치형 물리 스위치가 논리적으로 우선한다고 명시되어 있습니다. 게이트웨이 명령이 수용되더라도 다음 물리 입력 변화 때 즉시 뒤집힐 수 있습니다.

이건 꽤 중요한 철학입니다.
원격 자동화가 최종 주권을 갖는 구조가 아니라, 현장 물리 상태가 최종 주권에 더 가깝다는 뜻입니다. 따라서 이 시스템의 Home Assistant 연동은 “절대 제어”보다 “상태 동기화와 원격 보조”에 가깝습니다.

선택 3: 로컬 웹 UI 무인증

문서에는 로컬 네트워크를 신뢰한다고 가정하고 인증 없이 설정 UI를 제공합니다.

이건 편의성 측면에서는 단순하지만, 내부망 신뢰가 무너지는 순간 위험해질 수 있습니다.
즉, 홈랩이나 닫힌 네트워크에서는 이해 가능한 선택이지만, 확장 배포나 다중 사용자 환경에서는 재검토가 필요합니다. 이건 구현 세부보다 운영 경계의 문제입니다.

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

ESP-NOW

ESP 계열 칩끼리 작은 제어 메시지를 주고받는 근거리 P2P 성격의 통신 방식으로 이해하시면 됩니다. 이 프로젝트에서는 인터넷에 연결된 표준 네트워크를 만드는 용도가 아니라, 게이트웨이와 현장 노드 사이 제어 링크로만 쓰입니다.

MQTT Discovery

Home Assistant가 장치를 자동으로 인식하도록 메타데이터를 게시하는 방식입니다. 이 프로젝트에서는 새 노드 등록 시나 MQTT 재연결 시 discovery를 다시 발행하여, 상위 시스템이 엔티티를 자동 복구하도록 설계되어 있습니다.

Node Table

게이트웨이 메모리 안에 유지되는 노드 목록입니다. node ID, MAC, 현재 상태, online 여부, 마지막 수신 시각 등을 관리합니다. 결국 이 테이블이 ESP-NOW 세계와 MQTT 세계를 이어주는 주소 변환표 역할을 합니다.

시스템 구성 및 선택지 해석

이 시스템에서 실패 비용이 가장 큰 구간은 단순히 무선 전송 실패 자체가 아닙니다.
가장 치명적인 것은 상태 불일치가 오래 지속되는 상황입니다.

대표적으로는 이런 경우입니다.

• MQTT 명령은 들어갔는데 ESP-NOW 전달이 실패한 경우
• 노드는 실제로 바뀌었는데 STATE_REPORT가 돌아오지 않은 경우
• 게이트웨이의 node table이 오래된 상태로 유지되는 경우
• MQTT 재연결 이후 discovery/state 복구가 어긋나는 경우 

왜 이게 제일 큰 비용이냐면, 홈 오토메이션에서 사용자는 “명령 성공”보다 “상태가 맞는가”에 더 민감하기 때문입니다.
릴레이가 실제로 꺼졌는지, Home Assistant 화면이 맞게 반영하는지, offline 판정이 적절한지. 이게 틀리면 시스템 신뢰도가 무너집니다. 이 판단은 문서의 명령 흐름, keepalive, availability 처리, 재등록 시퀀스를 종합한 해석입니다. 추론임.

또 하나 중요한 논점은 특정 구성요소 제거 시 시스템 성격 변화입니다.

• W5500 제거 시: 상위 네트워크와의 유선 브리지 성격이 사라집니다. 문서 기준 Home Assistant MQTT 연동의 전제가 흔들리므로, 시스템은 “상위 자동화 플랫폼에 연결된 게이트웨이”에서 “로컬 무선 제어 실험체” 쪽으로 성격이 이동합니다. 추론임. 
• MQTT/HA discovery 제거 시: 현장 제어망은 남지만 자동화 시스템과의 통합성이 크게 낮아집니다. 즉, 제어 기능은 남아도 “플랫폼 편입”이라는 가치가 빠집니다. 
• node_table 제거 시: node ID와 MAC, online 상태, last_seen 관리가 무너지므로 게이트웨이는 브리지라기보다 단순 패킷 중계기에 가까워집니다. 추론임. 
• 노드의 NVS 상태 복원 제거 시: 게이트웨이 장애나 전원 복구 시 현장 동작의 연속성이 깨집니다. 시스템이 “현장 자율성”을 잃고 중앙 의존성이 커집니다. 

내부 관점에서의 시사점

내부 기술 공유 관점에서 이 프로젝트는 세 가지 포인트로 읽는 것이 좋겠습니다.

1) 이건 무선 프로토콜 프로젝트가 아니라 경계 설계 프로젝트입니다

ESP-NOW 자체보다 중요한 것은, 어디까지를 노드 책임으로 두고 어디부터를 게이트웨이 책임으로 나누었는가입니다. 구조를 바꿀 때도 이 경계를 먼저 건드려야 합니다. 추론임.

2) 상위 연동은 “주 제어기”가 아니라 “보조 수단”으로 위치합니다

물리 입력 우선, 노드의 상태 복원, 게이트웨이 없이도 현장 입력 동작 가능이라는 점 때문에, Home Assistant는 이 시스템의 감독층이지 존재론적 중심은 아닙니다. 즉, 현장 장치의 본체성을 대체하지 않습니다.

3) 실제 구현 확장 시 가장 먼저 봐야 할 것은 일관성 복구 경로입니다

재부팅, 링크 다운, MQTT 재연결, 노드 재등록, availability 재게시 같은 복구 시나리오가 이미 문서에 들어 있습니다. 따라서 다음 단계 구현이나 리팩터링도 “기능 추가”보다 “상태 일관성 보존”을 기준으로 검토하는 편이 맞습니다. 추론임.

FAQ

1. 기존에 각 스위치 노드가 직접 Wi-Fi와 MQTT를 처리하는 방식과 무엇이 가장 다릅니까?

가장 큰 차이는 네트워크 책임을 노드에 분산하지 않고 게이트웨이에 집중시킨다는 점입니다. 이 구조에서는 노드가 현장 제어 장치로 남고, 상위 플랫폼 연동은 게이트웨이가 담당합니다.

2. 왜 굳이 게이트웨이에 W5500 Ethernet을 두는 구조를 택한 것으로 보입니까?

공개 문서상 게이트웨이는 MQTT와 Home Assistant 연동의 중심이며, 그 네트워크 경로가 W5500 기반 Ethernet으로 정의되어 있습니다. 따라서 이 선택은 단순 부품 채용이 아니라, 상위 연결 계층을 안정적이고 고정된 브리지 성격으로 두려는 방향으로 읽힙니다. 추론임.

3. 이 시스템에서 핵심 신호 흐름은 무엇입니까?

상위에서는 MQTT command/state/availability가 오가고, 하위에서는 ESP-NOW의 REGISTER, ACK, CMD, STATE_REPORT, PING, PONG이 오갑니다. 결국 게이트웨이가 이 두 흐름을 번역하면서 node table로 상태와 식별 정보를 정렬하는 구조입니다.

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

가장 큰 비용은 제어 실패 자체보다 “상태 불일치 지속”입니다. 명령은 내려갔는데 실제 릴레이와 Home Assistant 표시 상태가 어긋나거나, offline 판정과 복구가 늦어지면 사용자는 시스템 전체를 불신하게 됩니다. 추론임.

5. 왜 Home Assistant 연동이 중심 기능이 아니라 보조 수단이라고 볼 수 있습니까?

문서상 노드는 게이트웨이 없이도 물리 입력을 처리하고, 마지막 상태를 복원하며, 물리 스위치 입력이 우선권을 가집니다. 따라서 Home Assistant는 편의와 통합의 층이지, 현장 동작의 절대 주체는 아닙니다.

6. 어떤 구성요소를 빼면 시스템 성격이 가장 크게 바뀝니까?

W5500/Ethernet uplink와 MQTT/HA 연동 계층을 제거하면, 이 구조는 더 이상 “상위 자동화 시스템에 붙는 게이트웨이”가 아니라 로컬 무선 제어망에 가까워집니다. 반대로 노드의 NVS 상태 복원을 제거하면 현장 자율성과 복구 일관성이 크게 약해집니다. 앞 문장은 문서 구조를 바탕으로 한 해석이며 일부는 추론임입니다.

저자 정보

공개된 GitHub 프로필 기준으로 저장소 소유자는 개인 공개 계정으로 보이며, 프로필 핸들은 awaara-hoon, 계정명은 11110110011로 표시됩니다.

이 계정명은 10진수로 1971 입니다. 아마 1971년생인 것으로 추측됩니다.

공개 화면에서는 소속 기관이나 조직 정보가 확인되지 않으며, 팔로워 수와 공개 저장소 수 외의 배경 정보는 제한적입니다. 따라서 공학적 배경이나 소속 성격에 대한 상세 판단은 어렵고, 해당 부분은 정보 제한으로 보는 것이 맞습니다.