How to Fix MicroPython Driver Bugs with WIZnet W5500 on ESP32?

Summary

This maker project debugs the MicroPython wiznet5k.py driver used with WIZnet W5500 on an ESP32-based Ethernet node. The source identifies two practical driver issues: reset-pin handling when the W5500 reset line is wired to a GPIO instead of tied high, and incorrect remote TCP port reconstruction caused by using the high byte twice instead of combining high and low bytes. W5500 provides the wired Ethernet MAC/PHY, hardware TCP/IP stack, socket registers, and packet buffering; the ESP32 MicroPython driver must still handle reset timing, SPI access, register reads, socket metadata, and application-level connection reporting correctly.

What the Project Does

The project is a debugging note for a W5500 MicroPython hardware driver. The author first followed common tutorial guidance that ties the W5500 reset pin to the positive supply rail, which avoids software reset handling. When the reset pin was instead assigned to an MCU GPIO, identified in the article as P14, initialization problems appeared and were traced to the driver’s reset sequence.

The second issue appears in TCP client handling. The driver’s remote_port() function should read two bytes from the W5500 socket destination-port register area and combine them into a 16-bit TCP port. The buggy path used the high byte twice, so different clients could appear to have the same normalized port pattern. After correction, the network debugging tool showed separate client ports such as 53905, 53929, and 53932, proving that both high and low bytes were being handled.

The data flow is a typical ESP32 + W5500 MicroPython stack. ESP32 runs the Python application and wiznet5k.py; the driver controls W5500 over SPI, resets the chip, configures MAC/IP/DHCP state, opens W5500 sockets, reads socket status, and reports remote endpoint information to higher-level socket code. W5500 handles Ethernet transport in hardware, but driver bugs at the GPIO, register, or socket-metadata layer can still break the application.

Where WIZnet Fits

The exact WIZnet product is W5500. In this project, W5500 sits between the ESP32 and the wired Ethernet network. ESP32 drives W5500 through SPI and GPIO control pins, while W5500 provides the embedded 10/100 Ethernet MAC/PHY, hardwired TCP/IP engine, socket state machine, and internal Tx/Rx buffer memory. WIZnet documents W5500 as supporting SPI up to 80 MHz, TCP, UDP, ICMP, IPv4, ARP, IGMP, PPPoE, 8 independent sockets, and 32 KB internal memory.

The driver bug is important because W5500 is not a passive Ethernet PHY. The MCU must operate W5500 registers and socket blocks correctly. The source article lists common and socket register constants such as REG_MR, REG_GAR, REG_SUBR, REG_SHAR, REG_SIPR, REG_PHYCFGR, REG_SNMR, REG_SNCR, REG_SNSR, REG_SNDPORT, REG_SNTX_FSR, and REG_SNRX_RSR. Those constants define the boundary between MicroPython code and the W5500 hardware socket engine.

For a maker Ethernet node, this is the useful trade-off. W5500 removes the need to implement TCP/IP in MicroPython, but it does not remove the need for correct reset polarity, SPI configuration, register access, socket-state checking, and byte-order handling.

Implementation Notes

File: wiznet5k.py
What it configures: W5500 reset sequencing during driver initialization.
Why it matters: tying reset high can hide a reset-driver problem. Once reset is routed to a GPIO, the driver must actively pull the W5500 reset line low, wait, release it high, and allow enough time before initialization.

# reset wiznet module prior to initialization
if reset:
    reset.value(0)
    time.sleep(0.1)
    reset.value(1)
    time.sleep(1)

The source contrasts this with an earlier reset.on() / reset.off() style sequence and explains the ambiguity: in MicroPython, pin.on() and pin.off() describe logical activation, but a reset input is often active-low. Using explicit value(0) and value(1) makes the electrical behavior clear.

File: wiznet5k.py
What it configures: remote TCP port reconstruction from W5500 socket registers.
Why it matters: TCP server code needs the correct client endpoint. If the driver reports the wrong remote port, logging, session cleanup, diagnostics, and multi-client handling become unreliable.

def remote_port(self, socket_num):
    """Returns the port of the host who sent the current incoming packet."""
    if socket_num >= self.max_sockets:
        return self._pbuff
    for octet in range(0, 2):
        self._pbuff[octet] = self._read_socket(socket_num, REG_SNDPORT + octet)[0]
    return int((self._pbuff[0] << 8) | self._pbuff[1])

The corrected function reads the high byte and low byte from REG_SNDPORT and REG_SNDPORT + 1, then combines them as (high << 8) | low. The source shows the incorrect form as (_pbuff[0] << 8) | _pbuff[0], which used the high byte twice.

Practical Tips / Pitfalls

• Do not rely on reset being tied high during development; route the W5500 reset pin to a GPIO if the product needs recoverability.
• Use explicit reset levels in firmware. For active-low reset, write 0, wait, then write 1.
• Verify SPI at a conservative speed first. The source driver initializes SPI at 500000 baud during bring-up, with an 8000000 baud value shown as a commented alternative. 
• Treat remote IP and remote port as register data, not strings. Reconstruct 16-bit port values from high and low bytes.
• Add endpoint logging for TCP servers: socket number, remote IP, remote port, connection time, bytes received, and bytes sent.
• Test with multiple clients, not one. The remote-port bug only becomes obvious when several TCP clients connect with different ephemeral ports.

FAQ

Q: Why use WIZnet W5500 for an ESP32 MicroPython maker Ethernet node?
A: W5500 gives ESP32 a wired Ethernet interface with hardware TCP/IP processing, 8 sockets, and internal packet buffers. That keeps the MicroPython application closer to socket-level programming instead of forcing it to implement ARP, IP, TCP, and UDP behavior in software.

Q: How does W5500 connect to the ESP32 platform?
A: W5500 connects through SPI plus control pins. The driver receives an SPI object, chip-select pin, and optional reset pin. In the source, the driver initializes SPI with polarity 0 and phase 0, stores the chip-select object, and conditionally toggles the reset pin before W5500 initialization.

Q: What role does W5500 play in this project?
A: W5500 is the hardware Ethernet and socket engine. It owns the wired MAC/PHY path and TCP/IP socket behavior, while wiznet5k.py controls registers such as network configuration, socket mode, socket status, TX/RX buffer pointers, and remote endpoint fields.

Q: Can beginners follow this debugging project?
A: Yes, if they already understand ESP32 GPIO, SPI wiring, MicroPython classes, and basic TCP client/server behavior. The best path is to verify reset behavior first, confirm W5500 initialization, open one socket, then test remote endpoint reporting with several TCP clients.

Q: How does W5500 compare with ENC28J60 for this kind of project?
A: W5500 is higher-level because it includes a hardwired TCP/IP stack, 8 sockets, and 32 KB internal buffer memory. ENC28J60 is a 10BASE-T standalone Ethernet controller with onboard MAC/PHY, 8 KB buffer RAM, and an SPI interface, so the host side normally carries more network-stack responsibility. For a MicroPython maker project, W5500 is usually simpler when the goal is TCP/UDP socket communication rather than building or porting a full software stack.

Source

Original article: CSDN, “W5500芯片网卡硬件驱动wiznet5k.py的BUG,” first published on 2026-02-12 and modified on 2026-02-13. The page is marked CC 4.0 BY-SA.

WIZnet product reference: W5500 documentation and feature list.

Alternative comparison reference: Microchip ENC28J60 product information.

Tags

#W5500 #WIZnet #ESP32 #MicroPython #wiznet5k #Ethernet #SPI #Maker #Firmware #Registers #SocketDriver #HardwareWiring #Performance #ENC28J60

ESP32에서 WIZnet W5500으로 MicroPython 드라이버 버그를 수정하는 방법은?

요약

이 메이커 프로젝트는 ESP32 기반 Ethernet 노드에서 WIZnet W5500과 함께 사용하는 MicroPython wiznet5k.py 드라이버를 디버깅합니다. 원문은 두 가지 실용적인 드라이버 문제를 확인합니다. 첫 번째는 W5500 reset pin을 high로 고정하지 않고 GPIO에 연결했을 때 발생하는 reset pin 처리 문제입니다. 두 번째는 원격 TCP port를 복원할 때 high byte와 low byte를 조합해야 하는데, high byte를 두 번 사용해 잘못된 port 값이 만들어지는 문제입니다. W5500은 유선 Ethernet MAC/PHY, 하드웨어 TCP/IP 스택, 소켓 레지스터, 패킷 버퍼링을 제공하지만, ESP32 MicroPython 드라이버는 reset timing, SPI 접근, register read, socket metadata, application-level connection reporting을 정확히 처리해야 합니다.

프로젝트가 하는 일

이 프로젝트는 W5500 MicroPython 하드웨어 드라이버에 대한 디버깅 노트입니다. 작성자는 처음에 일반적인 튜토리얼처럼 W5500 reset pin을 전원 positive rail에 연결해 소프트웨어 reset 처리를 피했습니다. 이후 reset pin을 MCU GPIO에 연결했으며, 원문에서는 이를 P14로 식별합니다. 이 구성에서 초기화 문제가 나타났고, 원인은 드라이버의 reset sequence로 추적되었습니다.

두 번째 문제는 TCP client 처리에서 나타납니다. 드라이버의 remote_port() 함수는 W5500 socket destination-port register 영역에서 두 바이트를 읽고 이를 16-bit TCP port로 조합해야 합니다. 버그가 있는 경로에서는 high byte를 두 번 사용했기 때문에, 서로 다른 client가 같은 패턴의 port로 잘못 표시될 수 있었습니다. 수정 후 network debugging tool에서 53905, 53929, 53932처럼 서로 다른 client port가 표시되어 high byte와 low byte가 모두 올바르게 처리됨을 확인했습니다.

데이터 흐름은 일반적인 ESP32 + W5500 MicroPython stack입니다. ESP32는 Python 애플리케이션과 wiznet5k.py를 실행합니다. 드라이버는 SPI로 W5500을 제어하고, 칩을 reset하며, MAC/IP/DHCP 상태를 설정하고, W5500 socket을 열고, socket status를 읽고, 원격 endpoint 정보를 상위 socket code에 보고합니다. W5500은 Ethernet transport를 하드웨어로 처리하지만, GPIO, register, socket metadata 계층의 드라이버 버그는 여전히 애플리케이션을 망가뜨릴 수 있습니다.

WIZnet이 들어가는 위치

이 프로젝트에서 사용되는 정확한 WIZnet 제품은 W5500입니다. W5500은 ESP32와 유선 Ethernet 네트워크 사이에 위치합니다. ESP32는 SPI와 GPIO control pin을 통해 W5500을 구동하고, W5500은 embedded 10/100 Ethernet MAC/PHY, hardwired TCP/IP engine, socket state machine, internal Tx/Rx buffer memory를 제공합니다. WIZnet 문서 기준으로 W5500은 최대 80 MHz SPI, TCP, UDP, ICMP, IPv4, ARP, IGMP, PPPoE, 8개 독립 socket, 32 KB internal memory를 지원합니다.

이 드라이버 버그가 중요한 이유는 W5500이 수동 Ethernet PHY가 아니기 때문입니다. MCU는 W5500 register와 socket block을 정확히 조작해야 합니다. 원문은 REG_MR, REG_GAR, REG_SUBR, REG_SHAR, REG_SIPR, REG_PHYCFGR, REG_SNMR, REG_SNCR, REG_SNSR, REG_SNDPORT, REG_SNTX_FSR, REG_SNRX_RSR 같은 common 및 socket register constant를 제시합니다. 이 constant들은 MicroPython code와 W5500 hardware socket engine 사이의 경계를 정의합니다.

메이커 Ethernet 노드에서는 이 trade-off가 핵심입니다. W5500은 MicroPython에서 TCP/IP를 직접 구현할 필요를 줄여주지만, reset polarity, SPI 설정, register access, socket-state checking, byte-order handling까지 없애주지는 않습니다.

구현 참고 사항

파일: wiznet5k.py
설정 내용: 드라이버 초기화 중 W5500 reset sequence
중요한 이유: reset을 high에 묶으면 reset-driver 문제가 숨어 있을 수 있습니다. reset이 GPIO에 연결되면 드라이버는 W5500 reset line을 low로 당기고, 대기한 뒤 high로 해제하고, 초기화 전에 충분한 시간을 제공해야 합니다.

# reset wiznet module prior to initialization
if reset:
    reset.value(0)
    time.sleep(0.1)
    reset.value(1)
    time.sleep(1)

원문은 이 코드를 이전의 reset.on() / reset.off() 스타일 sequence와 비교합니다. MicroPython에서 pin.on()과 pin.off()는 논리적 활성화를 설명하지만, reset input은 보통 active-low입니다. value(0)과 value(1)을 명시적으로 사용하면 실제 전기적 동작이 더 분명해집니다.

파일: wiznet5k.py
설정 내용: W5500 socket register에서 원격 TCP port 복원
중요한 이유: TCP server code는 정확한 client endpoint를 알아야 합니다. 드라이버가 잘못된 remote port를 보고하면 logging, session cleanup, diagnostics, multi-client handling이 신뢰할 수 없게 됩니다.

def remote_port(self, socket_num):
    """Returns the port of the host who sent the current incoming packet."""
    if socket_num >= self.max_sockets:
        return self._pbuff
    for octet in range(0, 2):
        self._pbuff[octet] = self._read_socket(socket_num, REG_SNDPORT + octet)[0]
    return int((self._pbuff[0] << 8) | self._pbuff[1])

수정된 함수는 REG_SNDPORT와 REG_SNDPORT + 1에서 high byte와 low byte를 읽은 뒤 (high << 8) | low로 조합합니다. 원문은 잘못된 형태가 (_pbuff[0] << 8) | _pbuff[0]였다고 설명합니다. 이 코드는 high byte를 두 번 사용해 remote port를 잘못 계산합니다.

실무 팁 / 주의점

• 개발 중에는 reset을 high에 고정하는 것에만 의존하지 않는 것이 좋습니다. 제품에서 복구 가능성이 필요하다면 W5500 reset pin을 GPIO에 연결해야 합니다.
• 펌웨어에서는 reset level을 명시적으로 사용해야 합니다. Active-low reset이라면 0을 쓰고 대기한 뒤 1을 써야 합니다.
• SPI는 먼저 보수적인 속도로 검증해야 합니다. 원문 드라이버는 bring-up 중 SPI를 500000 baud로 초기화하고, 8000000 baud 값은 주석 처리된 대안으로 보여줍니다.
• Remote IP와 remote port는 문자열이 아니라 register data로 취급해야 합니다. 16-bit port 값은 high byte와 low byte에서 재구성해야 합니다.
• TCP server에는 endpoint logging을 추가하는 것이 좋습니다. Socket number, remote IP, remote port, connection time, bytes received, bytes sent를 기록해야 합니다.
• 하나의 client만으로 테스트하지 말고 여러 client로 테스트해야 합니다. Remote-port 버그는 여러 TCP client가 서로 다른 ephemeral port로 연결될 때 더 명확하게 드러납니다.

FAQ

Q: ESP32 MicroPython 메이커 Ethernet 노드에서 왜 WIZnet W5500을 사용하나요?
A: W5500은 ESP32에 하드웨어 TCP/IP 처리, 8개 socket, 내부 packet buffer를 갖춘 유선 Ethernet interface를 제공합니다. 따라서 MicroPython 애플리케이션은 ARP, IP, TCP, UDP 동작을 소프트웨어로 직접 구현하지 않고 socket-level programming에 더 가깝게 작업할 수 있습니다.

Q: W5500은 ESP32 플랫폼에 어떻게 연결되나요?
A: W5500은 SPI와 control pin을 통해 연결됩니다. 드라이버는 SPI object, chip-select pin, optional reset pin을 받습니다. 원문에서 드라이버는 polarity 0, phase 0으로 SPI를 초기화하고, chip-select object를 저장하며, W5500 초기화 전에 reset pin이 있으면 조건부로 toggle합니다.

Q: 이 프로젝트에서 W5500은 어떤 역할을 하나요?
A: W5500은 하드웨어 Ethernet 및 socket engine입니다. 유선 MAC/PHY 경로와 TCP/IP socket behavior를 담당합니다. wiznet5k.py는 network configuration, socket mode, socket status, TX/RX buffer pointer, remote endpoint field 같은 register를 제어합니다.

Q: 초보자도 이 디버깅 프로젝트를 따라갈 수 있나요?
A: ESP32 GPIO, SPI 배선, MicroPython class, 기본 TCP client/server 동작을 이미 이해하고 있다면 가능합니다. 가장 좋은 순서는 reset behavior를 먼저 검증하고, W5500 초기화를 확인한 뒤, 하나의 socket을 열고, 여러 TCP client로 remote endpoint reporting을 테스트하는 것입니다.

Q: 이런 프로젝트에서 W5500은 ENC28J60과 비교하면 어떤 차이가 있나요?
A: W5500은 hardwired TCP/IP stack, 8개 socket, 32 KB internal buffer memory를 포함하므로 더 높은 수준의 장치입니다. ENC28J60은 onboard MAC/PHY, 8 KB buffer RAM, SPI interface를 가진 10BASE-T standalone Ethernet controller이므로, 일반적으로 host 측이 더 많은 network-stack 책임을 집니다. MicroPython 메이커 프로젝트에서 목표가 full software stack 구축이나 이식이 아니라 TCP/UDP socket communication이라면, W5500이 보통 더 단순합니다.

출처

Original article: CSDN, “W5500芯片网卡硬件驱动wiznet5k.py的BUG,” 2026-02-12 게시, 2026-02-13 수정, CC 4.0 BY-SA로 표시됨.
https://blog.csdn.net/iot2022/article/details/158006234

WIZnet product reference: W5500 documentation and feature list.
https://docs.wiznet.io/Product/Chip/Ethernet/W5500

Alternative comparison reference: Microchip ENC28J60 product information.
https://www.microchip.com/en-us/product/ENC28J60

태그

#W5500 #WIZnet #ESP32 #MicroPython #wiznet5k #Ethernet #SPI #Maker #Firmware #Registers #SocketDriver #HardwareWiring #Performance #ENC28J60