WebServer_ESP32_W5500 Library
Table of Contents
Features
This WebServer_ESP32_W5500 library is a simple yet complete WebServer wrapper library for ESP32-based boards using LwIP W5500 Ethernet. The functions are similar and compatible to those of ESP32 WebServer and ESP8266WebServer libraries to make life much easier to port sketches from ESP8266/ESP32.
This WebServer_ESP32_W5500 library also provides high-level HTTP(S), MQTT(S) and WebSockets Client by using the functions from ESP32’s HTTPClient Library
The library provides these features:
- TCP Server and Client
- UDP Server and Client
- HTTP(S) Server and Client
- HTTP(S) GET and POST requests, provides argument parsing, handles one client at a time.
- High-level HTTP(S) (GET, POST, PUT, PATCH, DELETE), MQTT(S) and WebSocket Client.
Library is providing similar functions to:
- Ivan Grokhotkov’s ESP32 WebServer
- HTTPClient Library
Sibling libraries
Please also check these sibling libraries
- WebServer_WT32_ETH01 for ESP32-based
WT32_ETH01 using LwIP LAN8720
- WebServer_ESP32_ENC for ESP32-boards using
LwIP ENC28J60
- WebServer_ESP32_W5500 for ESP32-boards using
LwIP W5500
- WebServer_ESP32_W6100 for ESP32-boards using
LwIP W6100
- WebServer_ESP32_SC_ENC for ESP32_S3-boards using
LwIP ENC28J60
- WebServer_ESP32_SC_W5500 for ESP32_S3-boards using
LwIP W5500
- WebServer_ESP32_SC_W6100 for ESP32_S3-boards using
LwIP W6100
and more complex libraries for ESP32-based using LwIP Ethernet
General Libraries
- AsyncHTTPRequest_ESP32_Ethernet
- AsyncHTTPSRequest_ESP32_Ethernet
- AsyncMQTT_ESP32
- HTTPS_Server_Generic
ESP32_Ethernet_Manager Libraries
- ESP32_ENC_Manager
- ESP32_W5500_Manager
- ESP32_Ethernet_Manager
- ESP32_SC_ENC_Manager
- ESP32_SC_W5500_Manager
- ESP32_SC_Ethernet_Manager
AsyncESP32_Ethernet_Manager Libraries
- AsyncESP32_ENC_Manager
- AsyncESP32_W5500_Manager
- AsyncESP32_Ethernet_Manager
- AsyncESP32_SC_ENC_Manager
- AsyncESP32_SC_W5500_Manager
- AsyncESP32_SC_Ethernet_Manager
AsyncUDP_ESP32 Libraries
- AsyncUDP_ESP32_ENC
- AsyncUDP_ESP32_W5500
- AsyncUDP_ESP32_W6100
- AsyncUDP_ESP32_Ethernet
- AsyncUDP_ESP32_SC_ENC
- AsyncUDP_ESP32_SC_W5500
- AsyncUDP_ESP32_SC_W6100
- AsyncUDP_ESP32_SC_Ethernet
AsyncDNSServer_ESP32 Libraries
- AsyncDNSServer_ESP32_ENC
- AsyncDNSServer_ESP32_W5500
- AsyncDNSServer_ESP32_W6100
- AsyncDNSServer_ESP32_Ethernet
Currently supported Boards
This WebServer_ESP32_W5500 library currently supports these following boards:
- ESP32_DEV using
LwIP W5500 Ethernet
W5500
FULL_DUPLEX, 100Mbps
Prerequisites
Arduino IDE 1.8.19+ for Arduino. 
ESP32 Core 2.0.6+ for ESP32-based ESP32_DEV with W5500 boards. 
Installation
Use Arduino Library Manager
The best and easiest way is to use Arduino Library Manager. Search for WebServer_ESP32_W5500, then select / install the latest version.
You can also use this link for more detailed instructions.
Manual Install
- Navigate to WebServer_ESP32_W5500 page.
- Download the latest release
WebServer_ESP32_W5500-main.zip.
- Extract the zip file to
WebServer_ESP32_W5500-main directory
- Copy the whole
WebServer_ESP32_W5500-main folder to Arduino libraries’ directory such as ~/Arduino/libraries/.
- Install VS Code
- Install PlatformIO
- Install WebServer_ESP32_W5500 library by using Library Manager. Search for WebServer_ESP32_W5500 in Platform.io Author’s Libraries
- Use included platformio.ini file from examples to ensure that all dependent libraries will installed automatically. Please visit documentation for the other options and examples at Project Configuration File
Libraries’ Patches
1. For fixing ESP32 compile error
To fix ESP32 compile error, just copy the following file into the ESP32 cores/esp32 directory (e.g. ./arduino-1.8.19/hardware/espressif/cores/esp32) to overwrite the old file:
HOWTO Fix Multiple Definitions Linker Error
The current library implementation, using xyz-Impl.h instead of standard xyz.cpp, possibly creates certain Multiple Definitions Linker error in certain use cases.
You can include this .hpp file
// Can be included as many times as necessary, without `Multiple Definitions` Linker Error
#include "WebServer_ESP32_W5500.hpp" //https://github.com/khoih-prog/WebServer_ESP32_W5500
in many files. But be sure to use the following .h file in just 1 .h, .cpp or .ino file, which must not be included in any other file, to avoid Multiple Definitions Linker Error
// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
#include "WebServer_ESP32_W5500.h" //https://github.com/khoih-prog/WebServer_ESP32_W5500
Check the new multiFileProject example for a HOWTO demo.
HOWTO Use analogRead() with ESP32 running WiFi and/or BlueTooth (BT/BLE)
Please have a look at ESP_WiFiManager Issue 39: Not able to read analog port when using the autoconnect example to have more detailed description and solution of the issue.
1. ESP32 has 2 ADCs, named ADC1 and ADC2
2. ESP32 ADCs functions
ADC1 controls ADC function for pins GPIO32-GPIO39ADC2 controls ADC function for pins GPIO0, 2, 4, 12-15, 25-27
3… ESP32 WiFi uses ADC2 for WiFi functions
Look in file adc_common.c
In ADC2, there’re two locks used for different cases:
-
lock shared with app and Wi-Fi:
ESP32:
When Wi-Fi using the ADC2, we assume it will never stop, so app checks the lock and returns immediately if failed.
ESP32S2:
The controller’s control over the ADC is determined by the arbiter. There is no need to control by lock.
-
lock shared between tasks:
when several tasks sharing the ADC2, we want to guarantee
all the requests will be handled.
Since conversions are short (about 31us), app returns the lock very soon,
we use a spinlock to stand there waiting to do conversions one by one.
adc2_spinlock should be acquired first, then adc2_wifi_lock or rtc_spinlock.
- In order to use
ADC2 for other functions, we have to acquire complicated firmware locks and very difficult to do
- So, it’s not advisable to use
ADC2 with WiFi/BlueTooth (BT/BLE).
- Use
ADC1, and pins GPIO32-GPIO39
- If somehow it’s a must to use those pins serviced by
ADC2 (GPIO0, 2, 4, 12, 13, 14, 15, 25, 26 and 27), use the fix mentioned at the end of ESP_WiFiManager Issue 39: Not able to read analog port when using the autoconnect example to work with ESP32 WiFi/BlueTooth (BT/BLE).
Usage
Class Constructor
WebServer server(80);
Creates the WebServer_ESP32_W5500 class object.
Parameters:
host port number: int port (default is the standard HTTP port 80)
Basic Operations
Starting the server
void begin();
Handling incoming client requests
void handleClient();
Disabling the server
void close();
void stop();
Both methods function the same
Client request handlers
void on();
void addHandler();
void onNotFound();
void onFileUpload();
Example:
server.on("/", handlerFunction);
server.onNotFound(handlerFunction); // called when handler is not assigned
server.onFileUpload(handlerFunction); // handle file uploads
Sending responses to the client
void send();
void send_P();
Parameters:
code - HTTP response code, can be 200 or 404, etc.
content_type - HTTP content type, like "text/plain" or "image/png", etc.
content - actual content body
Advanced Options
Getting information about request arguments
const String & arg();
const String & argName();
int args();
bool hasArg();
Function usage:
arg - get request argument value, use arg("plain") to get POST body
argName - get request argument name
args - get arguments count
hasArg - check if argument exist
Getting information about request headers
const String & header();
const String & headerName();
const String & hostHeader();
int headers();
bool hasHeader();
Function usage:
header - get request header value
headerName - get request header name
hostHeader - get request host header if available, else empty string
headers - get header count
hasHeader - check if header exist
Authentication
bool authenticate();
void requestAuthentication();
Function usage:
authenticate - server authentication, returns true if client is authenticated else false
requestAuthentication - sends authentication failure response to the client
Example Usage:
if(!server.authenticate(username, password))
{
server.requestAuthentication();
}
Other Function Calls
const String & uri(); // get the current uri
HTTPMethod method(); // get the current method
WiFiClient client(); // get the current client
HTTPUpload & upload(); // get the current upload
void setContentLength(); // set content length
void sendHeader(); // send HTTP header
void sendContent(); // send content
void sendContent_P();
void collectHeaders(); // set the request headers to collect
void serveStatic();
size_t streamFile();
How to connect W5500 to ESP32
You can change the INT pin to another one. Default is GPIO4
// Must connect INT to GPIOxx or not working
#define INT_GPIO 4
W5500
FULL_DUPLEX, 100Mbps
ESP32_DEV
| W5500 |
<—> |
ESP32 |
| MOSI |
<—> |
GPIO23 |
| MISO |
<—> |
GPIO19 |
| SCK |
<—> |
GPIO18 |
| SS/CS |
<—> |
GPIO5 |
| INT |
<—> |
GPIO4 |
| RST |
<—> |
RST |
| GND |
<—> |
GND |
| 3.3V |
<—> |
3.3V |
Examples:
Original Examples
- AdvancedWebServer
- HelloServer
- HelloServer2
- HttpBasicAuth
- MQTTClient_Auth
- MQTTClient_Basic
- MQTT_ThingStream
- PostServer
- SimpleAuthentication
- UdpNTPClient
- UdpSendReceive
- WebClient
- WebClientRepeating
- WebServer
- multiFileProject New
https://github.com/khoih-prog/WebServer_ESP32_W5500/blob/c8bccad4dfff3a3e15611537fa023d6ea3c28937/examples/AdvancedWebServer/AdvancedWebServer.ino#L41-L275
Debug Terminal Output Samples
1. AdvancedWebServer on ESP32_DEV with ESP32_W5500
The following are debug terminal output and screen shot when running example AdvancedWebServer on ESP32_DEV with ESP32_W5500
Start AdvancedWebServer on ESP32_DEV with ESP32_W5500
WebServer_ESP32_W5500 v1.5.3 for core v2.0.0+
[EWS] Default SPI pinout:
[EWS] SPI_HOST: 2
[EWS] MOSI: 23
[EWS] MISO: 19
[EWS] SCK: 18
[EWS] CS: 5
[EWS] INT: 4
[EWS] SPI Clock (MHz): 25
[EWS] =========================
ETH Started
ETH Connected
ETH MAC: B4:E6:2D:E9:68:AC, IPv4: 192.168.2.78
FULL_DUPLEX, 100Mbps
HTTP EthernetWebServer is @ IP : 192.168.2.78
.......... .......... .......... .....
2. MQTT_ThingStream on ESP32_DEV with ESP32_W5500
The terminal output of ESP32_DEV with W5500 running MQTT_ThingStream example
Start MQTT_ThingStream on ESP32_DEV with ESP32_W5500
WebServer_ESP32_W5500 v1.5.3 for core v2.0.0+
[EWS] Default SPI pinout:
[EWS] SPI_HOST: 2
[EWS] MOSI: 23
[EWS] MISO: 19
[EWS] SCK: 18
[EWS] CS: 5
[EWS] INT: 4
[EWS] SPI Clock (MHz): 25
[EWS] =========================
ETH Started
ETH Connected
ETH MAC: B4:E6:2D:E9:68:AC, IPv4: 192.168.2.78
FULL_DUPLEX, 100Mbps
***************************************
ESP32_Pub
***************************************
MQTT Message Send : ESP32_Pub => Hello from MQTT_ThingStream on ESP32_DEV with ESP32_W5500
MQTT Message receive [ESP32_Pub] Hello from MQTT_ThingStream on ESP32_DEV with ESP32_W5500
MQTT Message Send : ESP32_Pub => Hello from MQTT_ThingStream on ESP32_DEV with ESP32_W5500
MQTT Message receive [ESP32_Pub] Hello from MQTT_ThingStream on ESP32_DEV with ESP32_W5500
4. MQTTClient_Auth on ESP32_DEV with ESP32_W5500
The terminal output of ESP32_DEV with W5500 running MQTTClient_Auth example
Start MQTTClient_Auth on ESP32_DEV with ESP32_W5500
WebServer_ESP32_W5500 v1.5.3 for core v2.0.0+
[EWS] Default SPI pinout:
[EWS] SPI_HOST: 2
[EWS] MOSI: 23
[EWS] MISO: 19
[EWS] SCK: 18
[EWS] CS: 5
[EWS] INT: 4
[EWS] SPI Clock (MHz): 25
[EWS] =========================
ETH Started
ETH Connected
ETH MAC: B4:E6:2D:E9:68:AC, IPv4: 192.168.2.78
FULL_DUPLEX, 100Mbps
Attempting MQTT connection to broker.emqx.io...connected
Message Send : MQTT_Pub => Hello from MQTTClient_Auth on ESP32_DEV with ESP32_W5500
Message arrived [MQTT_Pub] Hello from MQTTClient_Auth on ESP32_DEV with ESP32_W5500
Message Send : MQTT_Pub => Hello from MQTTClient_Auth on ESP32_DEV with ESP32_W5500
Message arrived [MQTT_Pub] Hello from MQTTClient_Auth on ESP32_DEV with ESP32_W5500
5. MQTTClient_Basic on ESP32_DEV with ESP32_W5500
The terminal output of ESP32_DEV with W5500 running MQTTClient_Basic example
Start MQTTClient_Basic on ESP32_DEV with ESP32_W5500
WebServer_ESP32_W5500 v1.5.3 for core v2.0.0+
[EWS] Default SPI pinout:
[EWS] SPI_HOST: 2
[EWS] MOSI: 23
[EWS] MISO: 19
[EWS] SCK: 18
[EWS] CS: 5
[EWS] INT: 4
[EWS] SPI Clock (MHz): 25
[EWS] =========================
ETH Started
ETH Connected
ETH MAC: B4:E6:2D:E9:68:AC, IPv4: 192.168.2.78
FULL_DUPLEX, 100Mbps
Message Send : MQTT_Pub => Hello from MQTTClient_Basic on ESP32_DEV with ESP32_W5500
Message arrived [MQTT_Pub] Hello from MQTTClient_Basic on ESP32_DEV with ESP32_W5500
Message Send : MQTT_Pub => Hello from MQTTClient_Basic on ESP32_DEV with ESP32_W5500
Message Send : MQTT_Pub => Hello from MQTTClient_Basic on ESP32_DEV with ESP32_W5500
Message arrived [MQTT_Pub] Hello from MQTTClient_Basic on ESP32_DEV with ESP32_W5500
6. WebClient on ESP32_DEV with ESP32_W5500
The terminal output of ESP32_DEV with W5500 running WebClient example
Start WebClient on ESP32_DEV with ESP32_W5500
WebServer_ESP32_W5500 v1.5.3 for core v2.0.0+
[EWS] Default SPI pinout:
[EWS] SPI_HOST: 2
[EWS] MOSI: 23
[EWS] MISO: 19
[EWS] SCK: 18
[EWS] CS: 5
[EWS] INT: 4
[EWS] SPI Clock (MHz): 25
[EWS] =========================
ETH Started
ETH Connected
ETH MAC: B4:E6:2D:E9:68:AC, IPv4: 192.168.2.78
FULL_DUPLEX, 100Mbps
Starting connection to server...
Connected to server
HTTP/1.1 200 OK
Date: Wed, 11 Jan 2023 19:19:39 GMT
Content-Type: text/plain
Content-Length: 2263
Connection: close
x-amz-id-2: Tibw9r4/epZQzFM/rmO3cvTdq1DH4jSKocwQ9aMHx4RlkSotUFEGantuPNlKQKGqoHtdqwpFKw0=
x-amz-request-id: SD2XWDHW10J2H90M
Last-Modified: Wed, 23 Feb 2022 14:56:42 GMT
ETag: "667cf48afcc12c38c8c1637947a04224"
CF-Cache-Status: DYNAMIC
Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=HDCMzIyDC7oeBtywXTEb50R8fKz1H%2B7cB18KeeJVTdmf6NrFvvbxfSPcInISlUQCNqHTVbYQp4rVNVXnwo8qvTMn8bP92ozfI53aScTnOJvPaBYaK4vOt%2FZxKfHsj3o%3D"}],"group":"cf-nel","max_age":604800}
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Server: cloudflare
CF-RAY: 78800158694b1839-EWR
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400
`:;;;,` .:;;:.
.;;;;;;;;;;;` :;;;;;;;;;;: TM
`;;;;;;;;;;;;;;;` :;;;;;;;;;;;;;;;
:;;;;;;;;;;;;;;;;;; `;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;; .;;;;;;;;;;;;;;;;;;;;
;;;;;;;;:` `;;;;;;;;; ,;;;;;;;;.` .;;;;;;;;
.;;;;;;, :;;;;;;; .;;;;;;; ;;;;;;;
;;;;;; ;;;;;;; ;;;;;;, ;;;;;;.
,;;;;; ;;;;;;.;;;;;;` ;;;;;;
;;;;;. ;;;;;;;;;;;` ``` ;;;;;`
;;;;; ;;;;;;;;;, ;;; .;;;;;
`;;;;: `;;;;;;;; ;;; ;;;;;
,;;;;` `,,,,,,,, ;;;;;;; .,,;;;,,, ;;;;;
:;;;;` .;;;;;;;; ;;;;;, :;;;;;;;; ;;;;;
:;;;;` .;;;;;;;; `;;;;;; :;;;;;;;; ;;;;;
.;;;;. ;;;;;;;. ;;; ;;;;;
;;;;; ;;;;;;;;; ;;; ;;;;;
;;;;; .;;;;;;;;;; ;;; ;;;;;,
;;;;;; `;;;;;;;;;;;; ;;;;;
`;;;;;, .;;;;;; ;;;;;;; ;;;;;;
;;;;;;: :;;;;;;. ;;;;;;; ;;;;;;
;;;;;;;` .;;;;;;;, ;;;;;;;; ;;;;;;;:
;;;;;;;;;:,:;;;;;;;;;: ;;;;;;;;;;:,;;;;;;;;;;
`;;;;;;;;;;;;;;;;;;;. ;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;; :;;;;;;;;;;;;;;;;:
,;;;;;;;;;;;;;, ;;;;;;;;;;;;;;
.;;;;;;;;;` ,;;;;;;;;:
;;; ;;;;;` ;;;;: .;; ;; ,;;;;;, ;;. `;, ;;;;
;;; ;;:;;; ;;;;;; .;; ;; ,;;;;;: ;;; `;, ;;;:;;
,;:; ;; ;; ;; ;; .;; ;; ,;, ;;;,`;, ;; ;;
;; ;: ;; ;; ;; ;; .;; ;; ,;, ;;;;`;, ;; ;;.
;: ;; ;;;;;: ;; ;; .;; ;; ,;, ;;`;;;, ;; ;;`
,;;;;; ;;`;; ;; ;; .;; ;; ,;, ;; ;;;, ;; ;;
;; ,;, ;; .;; ;;;;;: ;;;;;: ,;;;;;: ;; ;;, ;;;;;;
;; ;; ;; ;;` ;;;;. `;;;: ,;;;;;, ;; ;;, ;;;;
Disconnecting from server...
7. UDPSendReceive on ESP32_DEV with ESP32_W5500
The terminal output of ESP32_DEV with W5500 running UDPSendReceive example
Start UDPSendReceive on ESP32_DEV with ESP32_W5500
WebServer_ESP32_W5500 v1.5.3 for core v2.0.0+
[EWS] Default SPI pinout:
[EWS] SPI_HOST: 2
[EWS] MOSI: 23
[EWS] MISO: 19
[EWS] SCK: 18
[EWS] CS: 5
[EWS] INT: 4
[EWS] SPI Clock (MHz): 25
[EWS] =========================
ETH Started
ETH Connected
ETH MAC: B4:E6:2D:E9:68:AC, IPv4: 192.168.2.78
FULL_DUPLEX, 100Mbps
Starting connection to server...
Listening on port 2390
UDP Packet received, size 48
From 132.163.97.3, port 123
Seconds since Jan 1 1900 = 3882452857
Unix time = 1673464057
The UTC time is 19:07:37
Debug
Debug is enabled by default on Serial. Debug Level from 0 to 4. To disable, change the ETHERNET_WEBSERVER_LOGLEVEL to 0
// Use this to output debug msgs to Serial
#define DEBUG_ETHERNET_WEBSERVER_PORT Serial
// Use this to disable all output debug msgs
// Debug Level from 0 to 4
#define _ETHERNET_WEBSERVER_LOGLEVEL_ 0
Troubleshooting
If you get compilation errors, more often than not, you may need to install a newer version of the board’s core, applying Libraries’ Patches, Packages’ Patches or this library latest version.
Issues
Submit issues to: WebServer_ESP32_W5500 issues
TO DO
- Bug Searching and Killing
DONE
- Add support to ESP32-based ESP32_DEV with W5500 using
LwIP W5500 Ethernet
- Using
SPI_DMA_CH_AUTO
- Using
ESP32 built-in ESP32 Ethernet MAC Address
Contributions and Thanks
Many thanks for everyone for bug reporting, new feature suggesting, testing and contributing to the development of this library.
- Based on the Ivan Grokhotkov’s ESP32 WebServer and HTTPClient Library libraries.
Contributing
If you want to contribute to this project:
- Report bugs and errors
- Ask for enhancements
- Create issues and pull requests
- Tell other people about this library
License
- The library is licensed under GPLv3
Copyright
评论