Overview

all_door_access_system is a full-stack IoT access-control platform built around an STM32F103C8T6 door controller. The embedded system supports password, AS608 fingerprint, MFRC522 RFID, and remote door-opening methods while controlling a physical relay for the lock.

The system connects the embedded controller to a Mosquitto MQTT broker and a FastAPI backend. MySQL stores users, devices, and access logs, Redis handles caching, authentication state, and device status, and WebSocket connections provide real-time updates to the management interface. Web, mobile, and WeChat Mini Program clients share the same backend.

The default documented network path uses an ESP32-S3 as a UART-to-Wi-Fi MQTT bridge. The repository also provides a W5500 Ethernet implementation that allows the STM32 to communicate directly with the MQTT broker through SPI and Ethernet.

W5500 Implementation

The W5500 implementation includes dedicated w5500.c/.h and mqtt_client.c/.h sources, and both source files are included in the Keil project configuration.

The wired architecture replaces the ESP32-S3 network bridge:

STM32 → SPI → W5500 → Ethernet → MQTT Broker → FastAPI

The W5500 driver directly controls hardware TCP sockets. The MQTT client opens a W5500 socket in TCP mode, establishes a connection to the broker, and builds MQTT CONNECT, SUBSCRIBE, PUBLISH, and keep-alive packets on the STM32.

This makes the project a practical example of using the W5500 Hardwired TCP/IP stack for TCP/IP offload instead of running a complete software TCP/IP stack on the STM32.

System Flow

Local password, fingerprint, or RFID authentication is processed by the STM32. Successful authentication activates the door relay and generates an access status event. The event is sent through the selected network interface to the MQTT broker and then processed by the backend for logging and real-time notification.

Remote door commands travel in the opposite direction from the Web or mobile client through FastAPI and MQTT to the embedded controller. The STM32 validates its lock state before activating the relay and returns an acknowledgment after the operation.

Strengths

The project covers the complete IoT path from physical authentication hardware and an embedded controller to Ethernet/Wi-Fi networking, MQTT messaging, backend services, databases, and user interfaces.

For WIZnet, its strongest point is that W5500 is applied to an actual MQTT-based access-control application rather than a basic TCP demonstration. The Ethernet implementation directly uses W5500 hardware sockets and provides its own embedded MQTT client.

Limitations

The Wi-Fi and W5500 paths are selectable alternatives rather than a simultaneous hybrid wired/wireless network. No automatic Ethernet/Wi-Fi failover is documented.

The repository also shows some inconsistency between the W5500 migration documentation and the currently rendered main.c. The W5500 driver and MQTT client are present and included in the Keil project, but the current main application source does not clearly expose the W5500 mode described by the migration document.

The README describes QoS 1 hardware messaging, while the inspected W5500 MQTT client builds QoS 0 SUBSCRIBE and PUBLISH packets. QoS behavior therefore depends on the network implementation and should not be generalized across both paths.

WIZnet Relevance

Product: W5500
Usage: STM32-connected Ethernet interface
Interface: SPI
Network role: Hardware TCP/IP and Socket offload
Application protocol: MQTT
Hybrid Network: No
TOE relevance: Yes
Main value: Direct MQTT communication from an STM32 through W5500 hardware TCP sockets

프로젝트 개요

all_door_access_system은 STM32F103C8T6 기반 전자 도어락과 서버, Web 관리 화면, 모바일 앱, WeChat Mini Program까지 포함하는 풀스택 IoT 출입통제 플랫폼이다. STM32는 비밀번호, AS608 지문 센서, MFRC522 RFID 카드 및 원격 명령을 이용한 네 가지 개방 방식을 처리하고 실제 도어 릴레이를 제어한다.

네트워크 상위 계층은 Mosquitto MQTT Broker와 FastAPI 백엔드로 구성된다. 백엔드는 MySQL에 사용자·장치·출입 기록을 저장하고 Redis를 인증 Token, 캐시 및 장치 상태 관리에 사용한다. WebSocket을 통해 관리 화면에 출입 및 장치 상태를 실시간으로 전달하며, RBAC 기반 사용자 권한 관리와 장치 잠금 및 해제 기능도 구현한다.

이 프로젝트의 특징은 기본 Wi-Fi 통신뿐 아니라 STM32가 W5500을 직접 제어해 MQTT Broker와 통신할 수 있는 별도의 Ethernet 경로를 코드 수준에서 제공한다는 점이다.

하드웨어 구성

중앙 제어기는 STM32F103C8T6, ARM Cortex-M3 72 MHz​이며 다음 주변장치를 연결한다.

로컬 인증 정보 일부는 AT24C02 EEPROM에 저장된다. 문서에는 관리자·개방 비밀번호와 최대 3장의 RFID UID 저장 구조까지 주소 단위로 정의되어 있다. MFRC522는 소프트웨어 SPI, EEPROM은 소프트웨어 I²C로 연결된다.

시스템 구조

기본 구성은 다음과 같다.

Password / Fingerprint / RFID
             │
             ▼
       STM32F103C8T6
        │          │
        │          └── Relay ── Door Lock
        │
        │ UART
        ▼
       ESP32-S3
        │ Wi-Fi
        ▼
    Mosquitto MQTT
        │
        ▼
      FastAPI
      │   │   │
      │   │   └── Redis
      │   └────── MySQL
      │
      ├── WebSocket
      └── REST API
             │
       ┌─────┼─────┐
       ▼     ▼     ▼
      Web   App   Mini Program

STM32에서 비밀번호·지문·카드 인증에 성공하면 PWD_OK, FP_OK, CARD_OK 등의 상태가 ESP32-S3에 UART로 전달되고, ESP32-S3가 이를 MQTT door/{device_id}/status Topic으로 Broker에 게시한다. 반대 방향으로 서버가 OPEN_DOOR 명령을 전송하면 ESP32-S3가 UART를 통해 STM32에 전달하고 STM32가 릴레이를 동작시킨다.

현재 공개된 main.c에서는 OPEN_DOOR\n을 수신하면 장치가 잠금 상태가 아닌 경우 릴레이를 약 1.5초 동작시키고 OK 상태를 회신하는 흐름을 확인할 수 있다. 반복 인증 실패 시 사용하는 5분 장치 잠금 상태도 펌웨어에 구현되어 있다.

W5500 Ethernet 경로

Wi-Fi에서 W5500으로 구조 변경

프로젝트에는 W5500용 w5500.c/.h와 mqtt_client.c/.h가 별도로 포함되어 있으며 Keil 프로젝트 파일에도 두 소스가 빌드 대상으로 등록되어 있다. 따라서 단순한 향후 계획 수준의 디렉터리는 아니다.

문서가 제시하는 네트워크 구조 변경은 명확하다.

Wi-Fi mode

STM32
  │ UART
  ▼
ESP32-S3
  │ Wi-Fi
  ▼
MQTT Broker


W5500 Ethernet mode

STM32
  │ SPI
  ▼
W5500
  │ Ethernet
  ▼
MQTT Broker

즉 W5500 사용 시 ESP32-S3를 네트워크 브리지로 사용하지 않고 STM32 → SPI → W5500 → Ethernet → MQTT Broker로 연결한다.

W5500 설정 문서에는 STM32 측 SPI 연결, MAC·IP·Gateway·Subnet과 MQTT Broker IP를 지정하고 Ethernet 모드로 펌웨어 설정을 변경하는 절차까지 제시되어 있다. 현재 문서상 설정 방식은 고정 IP 중심이다.

W5500에서 TCP/IP가 실제로 어떻게 사용되는가

W5500 코드는 MCU에서 소프트웨어 TCP stack을 실행하는 방식이 아니라 W5500의 Hardware Socket을 직접 제어한다.

MQTT 연결 과정에서 코드가 W5500 Socket을 TCP 모드로 열고,

W5500_Socket_Open(sock, Sn_MR_TCP);

목적지 Broker IP와 Port를 지정한 뒤 W5500의 CONNECT 명령을 사용한다. Socket 상태가 SOCK_ESTABLISHED가 될 때까지 상태 레지스터를 검사하는 로직도 구현되어 있다.

따라서 Pentacode 관점에서는 W5500의 Hardwired TCP/IP stack을 실제로 활용하는 TOE/Hardware Offload 사례로 분류하는 것이 적절하다.

MCU 내부 MQTT 구현

흥미로운 부분은 Ethernet 경로에서 별도의 대형 MQTT 라이브러리를 사용하는 대신 STM32 코드가 MQTT packet을 직접 구성한다는 점이다.

mqtt_client.c에는 CONNECT, SUBSCRIBE, PUBLISH, PINGREQ 등의 MQTT packet 생성 및 수신 parsing 코드가 구현되어 있으며, W5500 TCP Socket 위에서 동작한다.

예를 들어 PUBLISH 구현은 MQTT Topic과 Payload를 직접 packet buffer에 구성한 뒤 W5500 Socket으로 송신한다. 이는 다음 계층 구조로 이해할 수 있다.

Door Application
      │
      ▼
MQTT Client implemented in STM32
      │
      ▼
W5500 TCP Hardware Socket
      │
      ▼
Ethernet
      │
      ▼
Mosquitto Broker

이 구조는 MCU가 TCP retransmission, window 관리 등 전체 TCP/IP stack을 소프트웨어로 수행하지 않도록 하고 W5500에 TCP/IP 처리를 맡길 수 있다는 장점이 있다.

MQTT와 장치 상태 흐름

전체 제어 흐름은 다음과 같이 구성된다.

[Local authentication]

User
 │
 ├─ Password
 ├─ Fingerprint
 └─ RFID
 │
 ▼
STM32 authentication
 │
 ├─ Failure → error count / device lock
 │
 └─ Success
       │
       ├─ Relay ON → Door open
       │
       └─ MQTT status
              │
              ▼
          MQTT Broker
              │
              ▼
            Backend
              │
        ┌─────┴──────┐
        ▼            ▼
      MySQL       WebSocket
                       │
                       ▼
                  Admin UI


[Remote authentication]

Web / App
    │
    ▼
 FastAPI
    │
    ▼
 MQTT Broker
    │
    ▼
ESP32-S3 or W5500
    │
    ▼
 STM32
    │
    ▼
 Relay

백엔드는 MQTT Heartbeat와 상태 메시지를 통해 장치의 Online/Offline 상태를 판단하고 출입 결과와 오류를 저장하며 WebSocket을 이용해 관리자 화면으로 실시간 이벤트를 전달한다.

보안 및 운영 기능

시스템은 단순히 MQTT로 릴레이를 켜는 데서 끝나지 않는다. 다음과 같은 관리 계층도 구현되어 있다.

• Role Based Access Control을 이용한 사용자·장치·개방·경보 권한 분리
• JWT와 Redis 기반 로그인 및 Token 관리
• 비밀번호·지문·카드 인증 연속 실패 시 장치 잠금
• 관리자에 의한 원격 잠금 해제
• 장치 Heartbeat 기반 Online/Offline 감시
• WebSocket 기반 실시간 출입 이벤트 전달
• MySQL 기반 출입 기록 저장 및 검색
• Web, mobile app, WeChat Mini Program 지원
• DeepSeek 기반 자연어 도어 제어 및 데이터 조회 기능

장점

가장 큰 장점은 임베디드 장치 하나의 예제가 아니라 센서 → MCU → Network → Broker → Backend → Database → 사용자 인터페이스까지 전체 IoT 서비스 흐름이 공개되어 있다는 점이다.

특히 W5500 측에서는 단순 Ping이나 TCP Echo 예제가 아니라 MQTT client를 W5500 TCP Socket 위에 직접 구성하여 실제 출입 이벤트 및 원격 제어 시스템과 연결한 것이 기술적으로 의미가 있다. Keil 프로젝트에도 W5500 드라이버와 MQTT client가 포함되어 있다.

또한 같은 STM32 application을 유지하면서 ESP32-S3 Wi-Fi 경로를 W5500 Ethernet 경로로 변경하는 설계는 유선망이 필요한 빌딩·산업 환경으로 확장하기 쉬운 구조다.

한계 및 확인이 필요한 부분

첫째, Hybrid Network는 아니다. 문서는 Wi-Fi 모드와 W5500 Ethernet 모드를 별도의 구성으로 설명하며 W5500 사용 시 ESP32-S3를 제거하도록 안내한다. 유·무선 동시 연결이나 자동 Failover 로직은 공개 자료에서 확인되지 않는다.

둘째, 기본 실행 경로와 W5500 문서 사이에 버전 차이 흔적이 있다. W5500 전환 문서는 COMM_MODE_W5500 설정을 설명하지만 현재 공개된 main.c에서는 W5500 관련 include나 초기화를 확인하기 어렵다. 반면 Keil 프로젝트에는 w5500.c와 mqtt_client.c가 명시적으로 포함되어 있다. 따라서 W5500은 구현 코드가 존재하는 선택형 Ethernet 경로로 표현하되, 현재 기본 펌웨어가 W5500 모드라는 식으로 단정해서는 안 된다.

셋째, MQTT QoS 설명에 차이가 있다. README는 장치 통신에서 QoS 1을 설명하지만 W5500의 자체 MQTT client 코드에서 확인되는 SUBSCRIBE/PUBLISH 구현은 QoS 0으로 구성되어 있다. 따라서 W5500 경로까지 QoS 1이라고 일반화하면 안 된다.

넷째, 공개 저장소의 실제 장기 운용 안정성, 보안 침투시험, 다수 장치 동시 접속 규모 등은 확인되지 않는다.

WIZnet 관점의 핵심 가치

이 프로젝트에서 W5500의 역할은 단순한 “Ethernet 연결 부품”보다 명확하다.

STM32 application
       │
       ▼
Embedded MQTT implementation
       │
       ▼
W5500 Hardware TCP Socket
       │
       ▼
Ethernet
       │
       ▼
Mosquitto / FastAPI

즉 Wi-Fi용 ESP32-S3가 담당하던 네트워크 계층을 STM32 + W5500 조합으로 대체하면서 MQTT 기반 상위 시스템은 그대로 유지하는 구조다.

W5500의 Hardwired TCP/IP Socket을 활용해 제한된 MCU에서 TCP/IP 부담을 줄이면서 실제 IoT application protocol인 MQTT까지 연결한 점이 이 프로젝트의 WIZnet 관점 핵심 포인트다.

분류

최신성

저장소에는 168개의 Commit이 확인되며, 확인 시점의 최신 Commit은 2026년 8월 17일이다. 최근 Commit에는 MQTT 응답 처리와 Mosquitto 운영 설정 변경도 포함되어 있어 단순히 오래된 졸업작품을 올려둔 저장소라기보다는 2026년까지 실제 수정이 이어진 프로젝트로 볼 수 있다.