feat(esp32): add support for Native ESP32 Ethernet and WT32-ETH01 variant by balya · Pull Request #9586 · meshtastic/firmware

balya · 2026-02-09T18:09:45Z

Description

This PR introduces support for Native ESP32 Ethernet (using the internal MAC and PHY-interface, e.g., LAN8720) and adds the WT32-ETH01 board variant.

Previously, Ethernet support was tightly coupled with external SPI-based modules (W5500/RAK). This change abstracts the Ethernet client/server types, allowing Meshtastic to run on boards with native Ethernet hardware while maintaining full backward compatibility with existing SPI Ethernet and WiFi-only boards.

Key Changes:

Hardware Abstraction: Introduced MeshEthernetClient and MeshEthernetServer typedefs in ethServerAPI.h. On ESP32 with native ETH, these map to WiFiClient/WiFiServer, leveraging the robust lwIP stack.
MQTT Enhancements: Enabled TLS support for native Ethernet by allowing WiFiClientSecure to be used for MQTT connections.
Admin Module: Updated AdminModule to correctly report link status and local IP addresses for native Ethernet interfaces.
Build Fixes: Resolved multiple definition conflicts of initApiServer when both WiFi and Native Ethernet are enabled on the same target.
New Variant: Added wt32-eth01-e22 variant with correct pin mapping for LAN8720 and LoRa (SX1262).

Attestations

I have tested that my proposed changes behave as described.
I have tested that my proposed changes do not cause any obvious regressions on the following devices:
- Heltec (Lora32) V3
- LilyGo T-Deck
- LilyGo T-Beam
- RAK WisBlock 4631
- Seeed Studio T-1000E tracker card
- Other: WT32-ETH01 (Native Ethernet, WebServer, MQTT, and API verified).

Note: I do not have access to all Heltec/LilyGo hardware for regression testing. However, the changes are guarded by ETH_PHY_TYPE and HAS_WIFI macros to ensure zero impact on existing SPI-Ethernet and WiFi-only targets.

CLAassistant · 2026-02-09T18:09:53Z

All committers have signed the CLA.

CLAassistant · 2026-02-09T18:09:55Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

github-actions · 2026-02-09T18:09:56Z

@balya, Welcome to Meshtastic!

Thanks for opening your first pull request. We really appreciate it.

We discuss work as a team in discord, please join us in the #firmware channel.
There's a big backlog of patches at the moment. If you have time,
please help us with some code review and testing of other PRs!

Welcome to the team 😄

Copilot

Pull request overview

Adds native ESP32 Ethernet (internal MAC/PHY such as LAN8720) support and introduces a WT32-ETH01-E22 board variant, while refactoring networking code to abstract Ethernet client/server types and enable TLS for MQTT over native Ethernet.

Changes:

Added MeshEthernetClient / MeshEthernetServer typedef abstraction for Ethernet API server support (native ESP32 ETH + existing SPI Ethernet).
Updated MQTT client selection logic to allow TLS (via WiFiClientSecure) on native ESP32 Ethernet.
Added new wt32-eth01-e22 ESP32 variant (pins + PlatformIO environment), plus assorted build/config housekeeping (.trunk, .gitignore).

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
variants/esp32/wt32-eth01-e22/variant.h	New WT32-ETH01-E22 pin + feature definitions (LAN8720 + SX1262).
variants/esp32/wt32-eth01-e22/platformio.ini	New PlatformIO environment for the WT32-ETH01-E22 build.
src/mqtt/MQTT.h	Extends MQTT transport type selection to support native ETH + TLS via WiFiClientSecure.
src/modules/AdminModule.cpp	Reports Ethernet link/IP for native ESP32 ETH (and other ETH paths).
src/mesh/wifi/WiFiAPClient.h	Adds ETH include handling for native ESP32 ETH and broadens initEthernet declaration.
src/mesh/wifi/WiFiAPClient.cpp	Adds native ESP32 Ethernet init path and event handling.
src/mesh/eth/ethClient.cpp	Adjusts API server init call to match updated signature.
src/mesh/api/ethServerAPI.h	Introduces MeshEthernetClient/Server typedefs and adapts eth server API templates.
src/mesh/api/ethServerAPI.cpp	Updates implementation for the new eth server API typing and initApiServer handling.
src/mesh/InterfacesTemplates.cpp	Updates template instantiations to use MeshEthernet* abstractions.
src/main.cpp	Adjusts include logic for ethernet components (native ETH vs RAK/W5100S paths).
src/DebugConfiguration.h	Updates ETH include selection to support native ESP32 ETH alongside existing ETH modes.
.trunk/trunk.yaml	Updates/extends trunk toolchain versions and enabled runtimes/linters.
.gitignore	Adds `.history` and expands macOS ignore patterns.

Copilot · 2026-02-10T12:21:37Z

+#include "ethServerAPI.h"
 #include "configuration.h"


ethServerAPI.cpp now includes ethServerAPI.h before configuration.h. Because ethServerAPI.h is wrapped in #if HAS_ETHERNET, targets that define HAS_ETHERNET only via configuration/variant headers will see an empty header here, and then this .cpp later compiles the #if HAS_ETHERNET block (after including configuration.h) and references types that were never declared. Fix by including configuration.h before ethServerAPI.h (or make ethServerAPI.h independent of include order).

Suggested change

#include "ethServerAPI.h"

#include "configuration.h"

#include "configuration.h"

#include "ethServerAPI.h"

Copilot · 2026-02-10T12:21:38Z

+#if HAS_WIFI || (defined(ESP32) && defined(ETH_PHY_TYPE))
 #include <WiFiClient.h>
 #if __has_include(<WiFiClientSecure.h>)
 #include <WiFiClientSecure.h>
 #endif
 #endif
-#if HAS_ETHERNET && !defined(USE_WS5500)
+
+#if HAS_ETHERNET && !defined(ETH_PHY_TYPE) && !defined(USE_WS5500)
 #include <EthernetClient.h>
 #endif



MQTT.h’s client-type selection can break for USE_WS5500 builds when HAS_WIFI is 0 (e.g., MESHTASTIC_EXCLUDE_WIFI=1). In that configuration the code falls into the #elif HAS_ETHERNET branch and aliases MQTTClient to EthernetClient, but EthernetClient.h is not included when USE_WS5500 is defined (and W5500 uses the WiFiClient-based stack). Consider treating USE_WS5500 like native ESP32 ETH here (include/typedef WiFiClient + optional WiFiClientSecure) or otherwise ensure the selected client type is declared via includes for all macro combinations.

slomkowski · 2026-02-26T23:26:09Z

@balya I successfully ran your changes on W32-ETH01 ESP32 module and E22-900M30S LoRa. However, I needed to make some changes to make it work, I put them in pull request balya#1.

Please let me know if you're willing to go further with pushing ETH01 into mainline.

caveman99

Lemme wae through this... hold your beer.

MeisterQ · 2026-03-08T16:34:56Z

Uh.. Sorry for asking. When will the WT32-ETH or at least LAN8720 support be includet?

slomkowski · 2026-03-08T21:45:36Z

@MeisterQ Since @balya didn't respond, I think I'll work on his changes, apply the changes from the reviewers and make my pull reqest. If you need to run it now, under my fork: https://github.com/slomkowski/meshtastic-firmware/tree/develop WT32-ETH01 works OK. Feel free to test it and provide feedback. I'll answer your questions.

MeisterQ · 2026-03-09T17:16:08Z

@MeisterQ Since @balya didn't respond, I think I'll work on his changes, apply the changes from the reviewers and make my pull reqest. If you need to run it now, under my fork: https://github.com/slomkowski/meshtastic-firmware/tree/develop WT32-ETH01 works OK. Feel free to test it and provide feedback. I'll answer your questions.

Thank you. I will give it a try. Can you give me some hints where to define all this pins etc? Im not pretty familiar with it. I had the original source code in my platformio and could compile it.

Will it use an internal or external clock? My custom board uses the internal clock and no PHY PWR.

I just made myself an PoE powered Ethernet Board with LAN8720 and RA-01SH SX1267 based chip. Hopefully this all will work

slomkowski · 2026-03-09T22:55:20Z

@MeisterQ I think you'll find all pinout information in the file variants/esp32/wt32-eth01-e22/variant.h.

I'm not familiar with the intricacies of Ethernet configuration for ESP32, but in the code, the config is in src\mesh\wifi\WiFiAPClient.cpp:74. It is where ETH.begin() is called.

Pinout for SX1262 which is proven to work is also in variants/esp32/wt32-eth01-e22/variant.h.

You'll probably need to make your own PlatformIO variant and define your pinout in your own variant.h.

MeisterQ · 2026-03-10T11:10:58Z

@MeisterQ I think you'll find all pinout information in the file variants/esp32/wt32-eth01-e22/variant.h.

I'm not familiar with the intricacies of Ethernet configuration for ESP32, but in the code, the config is in src\mesh\wifi\WiFiAPClient.cpp:74. It is where ETH.begin() is called.

Pinout for SX1262 which is proven to work is also in variants/esp32/wt32-eth01-e22/variant.h.

You'll probably need to make your own PlatformIO variant and define your pinout in your own variant.h.

Im currently testing it. I could have upload your fork already, but i was choosing the wrong variant, because im not very familiar with PlatformIO. I hope i will get it running. Sometimes im occuring errors like "PlattformIO: Upload is not known" and so on.. Thats really weird.

I will keep you updated if i get it running.

MeisterQ · 2026-03-10T11:49:26Z

@MeisterQ I think you'll find all pinout information in the file variants/esp32/wt32-eth01-e22/variant.h.

I'm not familiar with the intricacies of Ethernet configuration for ESP32, but in the code, the config is in >src\mesh\wifi\WiFiAPClient.cpp:74. It is where ETH.begin() is called.

Pinout for SX1262 which is proven to work is also in variants/esp32/wt32-eth01-e22/variant.h.

You'll probably need to make your own PlatformIO variant and define your pinout in your own variant.h.

INFO  | ??:??:?? 7 Ethernet Obtained IP address: 192.168.1.84
INFO  | ??:??:?? 7 Start network services
INFO  | ??:??:?? 7 mDNS Host: Meshtastic.local
INFO  | ??:??:?? 7 Start NTP time client
DEBUG | ??:??:?? 7 Init Web Server
INFO  | ??:??:?? 7 Start Secure Web Server
Guru Meditation Error: Core  1 panic'ed (LoadProhibited). Exception was unhandled.

Core  1 register dump:
PC      : 0x400f69d3  PS      : 0x00060330  A0      : 0x800f7ef8  A1      : 0x3ffead80
A2      : 0x3fff8be8  A3      : 0x3fff8fdc  A4      : 0x3fff8ef4  A5      : 0x00000000
A6      : 0x3ffdd2b4  A7      : 0x00000000  A8      : 0x800f69c5  A9      : 0x3ffeac50
A10     : 0x00000000  A11     : 0x3f409131  A12     : 0x979de964  A13     : 0x00000000
A14     : 0x3ffd20d0  A15     : 0x00000001  SAR     : 0x0000001c  EXCCAUSE: 0x0000001c
EXCVADDR: 0x00000004  LBEG    : 0x40092bb0  LEND    : 0x40092bba  LCOUNT  : 0x00000000


Backtrace: 0x400f69d0:0x3ffead80 0x400f7ef5:0x3ffeada0 0x40126f29:0x3ffeadc0 0x40127561:0x3ffeaea0 0x400e6bbd:0x3ffeaf00




ELF file SHA256: 47e096054d296506

E (12959) esp_core_dump_flash: Core dump flash config is corrupted! CRC=0x7bd5c66f instead of 0x0
Rebooting...
ets Jul 29 2019 12:21:46

rst:0xc (SW_CPU_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0030,len:1184
load:0x40078000,len:13232
load:0x40080400,len:3028
entry 0x400805e4
E (809) esp_core_dump_flash: No core dump▒▒ѥѥ▒▒▒found!
E (809) esp_core_dump_flash: No core dump partition found!
[    11][D][esp32-hal-cpu.c:244] setCpuFrequencyMhz(): PLL: 480 / 2 = 240 Mhz, APB: 80000000 Hz
▒▒@INFO  | ??:??:?? 0

//\ E S H T /\ S T / C

It seems like its always crashing after trying to start the webserver.

slomkowski · 2026-03-10T11:55:57Z

On my WT32-ETH01 board, I initially didn't have this error. But after uploading custom OTA uploader to OTA partition, it started to happen. I haven't managed to trace the cause of it, I thought it was something on my side.

To mitigate it, I commented out secureServer->start(); in WebServer.cpp.

MeisterQ · 2026-03-10T12:54:05Z

On my WT32-ETH01 board, I initially didn't have this error. But after uploading custom OTA uploader to OTA partition, it started to happen. I haven't managed to trace the cause of it, I thought it was something on my side.

To mitigate it, I commented out secureServer->start(); in WebServer.cpp.

Thank you. This fixed my problem aswell. Its now running on my own designed PoE Board.

Thank you very much!

Will you think about pulling this into the main project after fixing the webserver issue?

slomkowski · 2026-03-10T13:01:44Z

Will you think about pulling this into the main project after fixing the webserver issue?

Yes, I'm applying the fixes from the reviews. If I fix the webserver issue, I may send a pull request.

MeisterQ · 2026-03-10T13:22:11Z

Will you think about pulling this into the main project after fixing the webserver issue?

Yes, I'm applying the fixes from the reviews. If I fix the webserver issue, I may send a pull request.

Thank you very much for your help!

MeisterQ · 2026-03-12T09:48:44Z

Will you think about pulling this into the main project after fixing the webserver issue?

Yes, I'm applying the fixes from the reviews. If I fix the webserver issue, I may send a pull request.

Did you have MQTT running on your Ethernet Board?
Im getting problems, that it does not connect to MQTT via ethernet.

slomkowski · 2026-03-12T09:59:25Z

@MeisterQ I made a draft pull request with some changes from the reviewers: #9891. Please check if perhaps my further changes helped. If not, continue the discussion there.

MeisterQ · 2026-03-12T10:15:01Z

@MeisterQ I made a draft pull request with some changes from the reviewers: #9891. Please check if perhaps my further changes helped. If not, continue the discussion there.

So download again from your fork, right?

slomkowski · 2026-03-12T10:19:51Z

Yes. If it sill breaks, put the logs under #9891. I didn't look closer at the MQTT, I was under the impression it worked.

balya · 2026-04-04T20:08:29Z

I finally managed to clean this up, and it seems to be working okay now. The main issue was with the event loop, so I moved the registration to the very beginning of the Ethernet initialization. I also updated the WiFiEvent signature for newer cores and added a heap check before generating the SSL certificate. Without PSRAM, it was just crashing as soon as the webserver tried to start, but now it stays stable.

I've tested it on my hardware — Ethernet is working, the API is up on port 4403, and the app connects without any issues.

Just a heads up: I wouldn't really recommend using this specific board for Meshtastic. The memory is extremely tight, and you basically have to disable almost all extra modules just to keep it from running out of heap.

balya · 2026-05-14T21:05:47Z

Hi @caveman99 @robekl @thebentern

Sorry to bother you directly.
I submitted this PR some time ago, and I wanted to politely ask if there is anything I can do to help move it forward.

I understand that everyone is busy and that maintaining the project takes a lot of time. I just want to make sure I did not miss anything on my side. Maybe the PR is missing some required changes, was submitted in the wrong way, or there are concerns with the implementation.

Could you please let me know what needs to be fixed or improved for this PR to be considered for merging?
I would be happy to make any required changes.

MeisterQ · 2026-06-02T08:05:38Z

Whats going on here now? Is is already merged into the original project?

github-actions Bot added first-contribution hardware-support Hardware related: new devices or modules, problems specific to hardware labels Feb 9, 2026

thebentern requested review from caveman99 and Copilot February 10, 2026 12:12

Copilot started reviewing on behalf of thebentern February 10, 2026 12:13 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

robekl reviewed Feb 27, 2026

View reviewed changes

Comment thread src/mesh/wifi/WiFiAPClient.cpp

slomkowski mentioned this pull request Mar 5, 2026

Meshtastic OTA (moar) #9327

Merged

caveman99 reviewed Mar 5, 2026

View reviewed changes

Comment thread .trunk/trunk.yaml

slomkowski mentioned this pull request Mar 12, 2026

Refinement on support for Native ESP32 Ethernet and WT32-ETH01 board (LAN8720) #9891

Closed

8 tasks

This comment was marked as duplicate.

Sign in to view

balya force-pushed the develop branch from b36b822 to 0b540be Compare May 14, 2026 20:43

feat(esp32): add native Ethernet support

1900a08

balya force-pushed the develop branch from 0b540be to 1900a08 Compare May 14, 2026 21:24

Merge branch 'develop' into develop

937d436

Uh oh!

Uh oh!

Conversation

balya commented Feb 9, 2026

Description

Key Changes:

Attestations

Uh oh!

CLAassistant commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Feb 9, 2026

Uh oh!

github-actions Bot commented Feb 9, 2026

@balya, Welcome to Meshtastic!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

slomkowski commented Feb 26, 2026

Uh oh!

Uh oh!

caveman99 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MeisterQ commented Mar 8, 2026

Uh oh!

slomkowski commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MeisterQ commented Mar 9, 2026

Uh oh!

slomkowski commented Mar 9, 2026

Uh oh!

MeisterQ commented Mar 10, 2026

Uh oh!

MeisterQ commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slomkowski commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MeisterQ commented Mar 10, 2026

Uh oh!

slomkowski commented Mar 10, 2026

Uh oh!

MeisterQ commented Mar 10, 2026

Uh oh!

MeisterQ commented Mar 12, 2026

Uh oh!

slomkowski commented Mar 12, 2026

Uh oh!

MeisterQ commented Mar 12, 2026

Uh oh!

slomkowski commented Mar 12, 2026

Uh oh!

balya commented Apr 4, 2026

Uh oh!

This comment was marked as duplicate.

Uh oh!

balya commented May 14, 2026

Uh oh!

MeisterQ commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

CLAassistant commented Feb 9, 2026 •

edited

Loading

slomkowski commented Mar 8, 2026 •

edited

Loading

MeisterQ commented Mar 10, 2026 •

edited

Loading

slomkowski commented Mar 10, 2026 •

edited

Loading