Skip to content

Add WPA2 Enterprise Authentication Support for ESP32 #17789

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

UniverCom
Copy link

@UniverCom UniverCom commented Jul 30, 2025

Summary

This PR adds comprehensive WPA2 Enterprise authentication support to MicroPython's ESP32 WLAN implementation, enabling connection to enterprise-grade WiFi networks that require EAP authentication.

Features Added

  • WPA2 Enterprise enable/disable functionality
  • Identity, username, and password configuration
  • Support for EAP-TLS, PEAP, and EAP-TTLS methods
  • Proper error handling with OSError exceptions
  • Integration with ESP-IDF WPA2 enterprise APIs
  • Memory optimization through BTREE module removal

New API Methods

  • wlan.wpa2_ent_enable() - Enable WPA2 enterprise mode
  • wlan.wpa2_ent_disable() - Disable WPA2 enterprise mode
  • wlan.wpa2_ent_set_identity(identity) - Set EAP identity
  • wlan.wpa2_ent_set_username(username) - Set authentication username
  • wlan.wpa2_ent_set_password(password) - Set authentication password

Usage Example

import network

# Initialize WiFi interface
wlan = network.WLAN(network.STA_IF)
wlan.active(True)

# Configure WPA2 Enterprise credentials
wlan.wpa2_ent_enable()
wlan.wpa2_ent_set_identity("[email protected]")
wlan.wpa2_ent_set_username("testuser")
wlan.wpa2_ent_set_password("testpass")

# Connect to enterprise network
wlan.connect("Enterprise-SSID")

# Verify connection
if wlan.isconnected():
    print("Connected successfully!")
    print("IP Config:", wlan.ifconfig())
else:
    print("Connection failed")

Testing
Environment

MicroPython Version: v1.26.0-preview-460-g59e3c8c59
ESP-IDF Version: v5.2.x/v5.3.x (bundled with MicroPython)
Hardware: ESP32-DevKit-C v4, ESP32-WROOM-32 modules

Network Environments Tested

University WPA2-Enterprise networks (PEAP/MSCHAPv2)
Corporate WiFi with EAP-TTLS authentication
Test environment with FreeRADIUS server
Multiple enterprise WiFi configurations

Test Results

✅ Successful connection to enterprise networks
✅ Proper error handling for invalid credentials
✅ Network timeout scenarios handled correctly
✅ Disable/re-enable functionality working
✅ Memory usage optimized with BTREE removal
✅ Stable operation under extended testing

Memory Impact

Before: ~180KB free heap
After WPA2 connection: ~165KB free heap
BTREE removal: Compensates for WPA2 memory overhead
Net impact: Minimal memory footprint increase

Implementation Details
Files Modified

ports/esp32/mpconfigport.h - Configuration changes
ports/esp32/network_wlan.c - Core WPA2 enterprise implementation
ports/esp32/sdkconfig.defaults - SDK configuration updates

Files Added

ports/esp32/esp_wpa2.h - WPA2 compatibility header
ports/esp32/esp_eap_client.h - EAP client definitions

Error Handling
All WPA2 enterprise methods include proper error handling:

Invalid parameters raise ValueError
ESP-IDF errors raise OSError with appropriate error codes
Network failures provide clear error messages

Compatibility

Compatible with existing WLAN API
No breaking changes to current functionality
Follows MicroPython coding standards and conventions
Integrates seamlessly with ESP-IDF WPA2 enterprise APIs

Use Cases
This enhancement enables MicroPython ESP32 devices to connect to:

University campus networks
Corporate enterprise WiFi
Government and institutional networks
Any WPA2-Enterprise protected WiFi network

Future Enhancements
Potential future additions could include:

Certificate-based authentication (EAP-TLS with client certificates)
Additional EAP methods
Advanced configuration options

@UniverCom UniverCom force-pushed the feature/wpa2-support branch 2 times, most recently from 6fcc7ab to f5d6744 Compare July 30, 2025 21:25
AJMansfield and others added 4 commits July 31, 2025 00:36
Disable BTREE module to free memory for WPA2 enterprise
and update SDK config to exclude BTREE functionality.

Signed-off-by: UniverCom <[email protected]>
Add esp_wpa2.h for backward compatibility and esp_eap_client.h for modern EAP client API definitions required for WPA2 enterprise.

Signed-off-by: UniverCom <[email protected]>
- Implement wpa2_ent_enable() / wpa2_ent_disable() support
- Add configuration for identity, username, and password
- Integrate with ESP-IDF WPA2 Enterprise APIs:
    * esp_wifi_sta_wpa2_ent_set_identity()
    * esp_wifi_sta_wpa2_ent_set_username()
    * esp_wifi_sta_wpa2_ent_set_password()
    * esp_wifi_sta_wpa2_ent_enable()
- Provide support for EAP-TLS, PEAP, and EAP-TTLS authentication methods
- Introduce error handling with OSError exceptions on failure
- Update `network.WLAN` API to expose WPA2 Enterprise configuration

Signed-off-by: UniverCom <[email protected]>
@UniverCom UniverCom force-pushed the feature/wpa2-support branch from f5d6744 to 73097e2 Compare July 30, 2025 21:42
Copy link

codecov bot commented Jul 30, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.38%. Comparing base (3a72f95) to head (73097e2).
⚠️ Report is 37 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master   #17789   +/-   ##
=======================================
  Coverage   98.38%   98.38%           
=======================================
  Files         171      171           
  Lines       22240    22257   +17     
=======================================
+ Hits        21881    21898   +17     
  Misses        359      359           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copy link

Code size report:

   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
     mimxrt:    +0 +0.000% TEENSY40
        rp2:    +0 +0.000% RPI_PICO_W
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS
  qemu rv32:    +0 +0.000% VIRT_RV32

@projectgus
Copy link
Contributor

Thanks @UniverCom for submitting this. I took the liberty of making a minor edit in the PR description - the example code block didn't terminate. The description could probably use some more editing in the second half to add some formatting.

A quick look at the changes suggest you've copied an ESP-IDF header (esp_eap_client.h) into the MicroPython repo. That's not something that we would ever accept, you should be able to include the header from the ESP-IDF component.

To be accepted this PR would also need documentation and/or example code, in addition to a proper review.

Have you seen the esp32 WPA Enterprise support submitted in #17234? That PR is more complete and currently under review. It might be a better use of efforts to collaborate on it rather than starting a new approach.

Also, may I ask, did you use an AI coding agent to develop part or all of this PR?

@UniverCom
Copy link
Author

Thanks @UniverCom for submitting this. I took the liberty of making a minor edit in the PR description - the example code block didn't terminate. The description could probably use some more editing in the second half to add some formatting.

A quick look at the changes suggest you've copied an ESP-IDF header (esp_eap_client.h) into the MicroPython repo. That's not something that we would ever accept, you should be able to include the header from the ESP-IDF component.

To be accepted this PR would also need documentation and/or example code, in addition to a proper review.

Have you seen the esp32 WPA Enterprise support submitted in #17234? That PR is more complete and currently under review. It might be a better use of efforts to collaborate on it rather than starting a new approach.

Also, may I ask, did you use an AI coding agent to develop part or all of this PR?

Hi, @projectgus. I am currently a third-year undergraduate student living in my university’s dormitory. Normally, I work in the fields of Machine Learning and Natural Language Processing, developing various projects. About a month ago, I began learning IoT systems in order to advance my design-stage projects. To test my first ESP32 prototypes, I needed to log and monitor sensor data on a local web server, this required connecting the sensors to my university’s Wi-Fi network, since I reside in a campus dormitory.

Upon discovering that MicroPython does not yet support WPA2-Enterprise, I wondered whether I could implement and enable this feature myself. I reviewed the ESP-IDF and C documentation and attempted to integrate the necessary support into my project. Having primarily worked in Python, I lack professional C experience; nonetheless, I read through the documentation, wrote the C code, and consulted AI code agents to identify any gaps or errors. After successfully testing locally and confirming that I could transmit my project’s data to the web server over the dormitory Wi-Fi, I quickly prepared the documentation and opened this pull request.

I have now seen the previous PR you mentioned. My goal in sharing this code here is threefold: to provide a solution for others facing the same issue, to address any remaining shortcomings, and to solicit advice on the best path forward.

I will take your comments into account and revise the PR accordingly. If you have any further recommendations or warnings regarding this submission, I would greatly appreciate your feedback. Alternatively, I am happy to contribute by working through the PR you referenced. Since solving this problem personally has been very rewarding, I endeavored to follow all guidelines when creating this PR but I recognize that my experience in this area may still be lacking. I hope I have not inadvertently caused any complications.

Sincerely Yours.

@dpgeorge dpgeorge added board-definition New or updated board definition files. Combine with a port- label. port-esp32 and removed board-definition New or updated board definition files. Combine with a port- label. labels Aug 1, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants