search

khoih-prog / WiFiWebServer_RTL8720

Simple WiFiWebServer, HTTP Client, MQTT and WebSocket Client library for Realtek RTL8720DN, RTL8722DM, RTM8722CSM boards using WiFi. Supporting WiFi at 2.4GHz and 5GHz
MIT License
11 stars 5 forks source link
2-4-ghz 5ghz amebad-core amebaiot mqtt-client ntp-client realtek rtl8720dn rtl8722 tcp-client tcp-server thingstream udp webserver wifi

readme

WiFiWebServer_RTL8720 Library

arduino-library-badge GitHub release GitHub contributions welcome GitHub issues

Donate to my libraries using BuyMeACoffee

Table of Contents

Why do we need this WiFiWebServer_RTL8720 library

Features

This WiFiWebServer_RTL8720 library is a simple yet complete WebServer library for Realtek RTL8720DN, RTL8722DM and RTL8722CSM boards.

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 WiFiWebServer_RTL8720 library also provides high-level HTTP and WebSocket Client with the functions are similar and compatible to those of ArduinoHttpClient Library

The library provides supports to:

  1. WiFi Client, STA and AP mode
  2. TCP Server and Client
  3. UDP Server and Client
  4. HTTP Server and Client
  5. HTTP GET and POST requests, provides argument parsing, handles one client at a time.
  6. High-level HTTP (GET, POST, PUT, PATCH, DELETE) and WebSocket Client.

It is based on and modified from:

  1. Ivan Grokhotkov's ESP8266WebServer
  2. Ivan Grokhotkov's ESP32 WebServer
  3. ArduinoHttpClient Library

The WiFiWebServer class found in WiFiWebServer_RTL8720.h header, is a simple web server that knows how to handle HTTP requests such as GET and POST and can only support one client at a time.

Currently Supported Boards

This WiFiWebServer_RTL8720 library currently supports these following boards:

  1. Realtek RTL8720DN, RTL8722DM and RTL8722CSM

Prerequisites

  1. Arduino IDE 1.8.19+ for Arduino. GitHub release
  2. Arduino AmebaD core 3.1.4+ for Realtek RTL8720DN, RTL8722DM and RTL8722CSM. GitHub release
  3. Functional-Vlpp library v1.0.2+ to use server's lambda function. To install. check arduino-library-badge

Installation

Use Arduino Library Manager

The best and easiest way is to use Arduino Library Manager. Search for WiFiWebServer_RTL8720, then select / install the latest version. You can also use this link arduino-library-badge for more detailed instructions.

Manual Install

  1. Navigate to WiFiWebServer_RTL8720 page.
  2. Download the latest release WiFiWebServer_RTL8720-main.zip.
  3. Extract the zip file to WiFiWebServer_RTL8720-main directory
  4. Copy the whole WiFiWebServer_RTL8720-main folder to Arduino libraries' directory such as ~/Arduino/libraries/.

VS Code & PlatformIO:

  1. Install VS Code
  2. Install PlatformIO
  3. Install WiFiWebServer_RTL8720 library by using Library Manager. Search for WiFiWebServer_RTL8720 in Platform.io Author's Libraries
  4. Please visit documentation for the other options and examples at Project Configuration File

Packages' Patches

1. For RTL8720DN boards using AmebaD core

To avoid compile error relating to PROGMEM, you have to copy the file Realtek AmebaD core pgmspace.h into Realtek AmebaD directory (~/.arduino15/packages/realtek/hardware/AmebaD/3.1.4/cores/ambd/avr/pgmspace.h).

Supposing the Realtek AmebaD core version is 3.1.4. This file must be copied into the directory:

Whenever a new version is installed, remember to copy this file into the new version directory. For example, new version is x.yy.zz This file must be copied into the directory:

Usage

Class Constructor

  WiFiWebServer server(80);

Creates the WiFiWebServer 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();

Examples:

Original Examples

  1. AdvancedWebServer
  2. ConnectWPA
  3. HelloServer
  4. HelloServer2
  5. HttpBasicAuth
  6. MQTTClient_Auth
  7. MQTTClient_Basic
  8. MQTT_ThingStream
  9. PostServer
    1. ScanNetworks
    2. SimpleAuthentication
    3. UdpNTPClient
    4. UdpSendReceive
    5. WebClient
    6. WebClientRepeating
    7. WebServer
    8. WiFiUdpNtpClient

HTTP and WebSocket Client New Examples

  1. BasicAuthGet
  2. CustomHeader
  3. DweetGet
  4. DweetPost
  5. HueBlink
  6. node_test_server
  7. PostWithHeaders
  8. SimpleDelete
  9. SimpleGet
    1. SimpleHTTPExample
    2. SimplePost
    3. SimplePut
    4. SimpleWebSocket

Example AdvancedWebServer

1. File AdvancedWebServer.ino

https://github.com/khoih-prog/WiFiWebServer_RTL8720/blob/74723f4d6f07671dc33d9d6421eea8f537bf01af/examples/AdvancedWebServer/AdvancedWebServer.ino#L40-L245

2. File defines.h

https://github.com/khoih-prog/WiFiWebServer_RTL8720/blob/74723f4d6f07671dc33d9d6421eea8f537bf01af/examples/AdvancedWebServer/defines.h#L11-L42

Debug Terminal Output Samples

1. AdvancedWebServer on Rtlduino RTL8720DN

The following are debug terminal output and screen shot when running example AdvancedWebServer on Rtlduino RTL8720DN

Starting AdvancedServer on Rtlduino RTL8720DN with RTL8720DN
WiFiWebServer_RTL8720 v1.1.2
interface 0 is initialized
interface 1 is initialized
Initializing WIFI ...
WIFI initialized
Current Firmware Version = 1.0.0
Attempting to connect to SSID: HueNet1
RTL8721D[Driver]: set ssid [HueNet1] 
RTL8721D[Driver]: rtw_set_wpa_ie[1160]: AuthKeyMgmt = 0x2 
RTL8721D[Driver]: rtw_restruct_sec_ie[4225]: no pmksa cached 
RTL8721D[Driver]: start auth to 68:7f:74:94:f4:a5
RTL8721D[Driver]: auth alg = 2
RTL8721D[Driver]: 
OnAuthClient:algthm = 0, seq = 2, status = 0, sae_msg_len = 11
RTL8721D[Driver]: auth success, start assoc
RTL8721D[Driver]: association success(res=1)
RTL8721D[Driver]: ClientSendEAPOL[1624]: no use cache pmksa 
RTL8721D[Driver]: ClientSendEAPOL[1624]: no use cache pmksa 
RTL8721D[Driver]: set pairwise key to hw: alg:4(WEP40-1 WEP104-5 TKIP-2 AES-4)
RTL8721D[Driver]: set group key to hw: alg:2(WEP40-1 WEP104-5 TKIP-2 AES-4) keyid:1
Interface 0 IP address : 192.168.2.117
[INFO] Listen socket successfully
[INFO] Socket conntect successfully 
HTTP server started @ 192.168.2.117
[INFO] Accept connection successfully
A client connected to this server :
[PORT]: 36912
[IP]:192.168.2.30
[INFO] Accept connection successfully
A client connected to this server :
[PORT]: 36914
[IP]:192.168.2.30

[WIFI] String Len = 0, extend to 2048
[INFO] Accept connection successfully

2. WebClient on Rtlduino RTL8720DN

The following are debug terminal output and screen shot when running example WebClient on Rtlduino RTL8720DN

Starting WebClientRepeating on Rtlduino RTL8720DN with RTL8720DN
WiFiWebServer_RTL8720 v1.1.2
interface 0 is initialized
interface 1 is initialized
Initializing WIFI ...
WIFI initialized
Current Firmware Version = 1.0.0
Attempting to connect to SSID: HueNet1
RTL8721D[Driver]: set ssid [HueNet1] 
RTL8721D[Driver]: rtw_set_wpa_ie[1160]: AuthKeyMgmt = 0x2 
RTL8721D[Driver]: rtw_restruct_sec_ie[4225]: no pmksa cached 
RTL8721D[Driver]: start auth to 68:7f:74:94:f4:a5
RTL8721D[Driver]: auth alg = 2
RTL8721D[Driver]: 
OnAuthClient:algthm = 0, seq = 2, status = 0, sae_msg_len = 11
RTL8721D[Driver]: auth success, start assoc
RTL8721D[Driver]: association success(res=1)
RTL8721D[Driver]: ClientSendEAPOL[1624]: no use cache pmksa 
RTL8721D[Driver]: ClientSendEAPOL[1624]: no use cache pmksa 
RTL8721D[Driver]: set pairwise key to hw: alg:4(WEP40-1 WEP104-5 TKIP-2 AES-4)
RTL8721D[Driver]: set group key to hw: alg:2(WEP40-1 WEP104-5 TKIP-2 AES-4) keyid:1
Interface 0 IP address : 192.168.2.117You're connected to the network, IP = 192.168.2.117
SSID: HueNet1, Signal strength (RSSI):-26 dBm
[INFO]server_drv.cpp:  start_client
[INFO] Create socket successfully
[INFO] Connect to Server successfully!
Connecting...
HTTP/1.1 200 OK
Date: Thu, 28 Apr 2022 02:46:07 GMT
Content-Type: text/plain
Content-Length: 2263
Connection: close
x-amz-id-2: 0v2VZitmKPb1GvH/Of2rACgGVIyluvsMCTX1kbkYKmtOMZMLlHXAT1n7wdAcMiFQ6LPQ1Qy2tSg=
x-amz-request-id: 72CSXT4AMDTCDJYE
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=vdeduIIMRyhO44T972z7Z0qfco3T5svA5zYhyMJqQE5hTNGvTxTg%2B8S8e90uedVsSDo5oj73gg%2BxEoPfXW1%2FUCfu6XkFt6oLuf9zjLCo%2BSe58OLsZhr25mZ3MxPD%2ByY%3D"}],"group":"cf-nel","max_age":604800}
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Server: cloudflare
CF-RAY: 702c77389848b671-YWG
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400

           `:;;;,`                      .:;;:.           
        .;;;;;;;;;;;`                :;;;;;;;;;;:     TM 
      `;;;;;;;;;;;;;;;`            :;;;;;;;;;;;;;;;      
     :;;;;;;;;;;;;;;;;;;         `;;;;;;;;;;;;;;;;;;     
    ;;;;;;;;;;;;;;;;;;;;;       .;;;;;;;;;;;;;;;;;;;;    
   ;;;;;;;;:`   `;;;;;;;;;     ,;;;;;;;;.`   .;;;;;;;;   
  .;;;;;;,         :;;;;;;;   .;;;;;;;          ;;;;;;;  
  ;;;;;;             ;;;;;;;  ;;;;;;,            ;;;;;;. 
 ,;;;;;               ;;;;;;.;;;;;;`              ;;;;;; 
 ;;;;;.                ;;;;;;;;;;;`      ```       ;;;;;`
 ;;;;;                  ;;;;;;;;;,       ;;;       .;;;;;
`;;;;:                  `;;;;;;;;        ;;;        ;;;;;
,;;;;`    `,,,,,,,,      ;;;;;;;      .,,;;;,,,     ;;;;;
:;;;;`    .;;;;;;;;       ;;;;;,      :;;;;;;;;     ;;;;;
:;;;;`    .;;;;;;;;      `;;;;;;      :;;;;;;;;     ;;;;;
.;;;;.                   ;;;;;;;.        ;;;        ;;;;;
 ;;;;;                  ;;;;;;;;;        ;;;        ;;;;;
 ;;;;;                 .;;;;;;;;;;       ;;;       ;;;;;,
 ;;;;;;               `;;;;;;;;;;;;                ;;;;; 
 `;;;;;,             .;;;;;; ;;;;;;;              ;;;;;; 
  ;;;;;;:           :;;;;;;.  ;;;;;;;            ;;;;;;  
   ;;;;;;;`       .;;;;;;;,    ;;;;;;;;        ;;;;;;;:  
    ;;;;;;;;;:,:;;;;;;;;;:      ;;;;;;;;;;:,;;;;;;;;;;   
    `;;;;;;;;;;;;;;;;;;;.        ;;;;;;;;;;;;;;;;;;;;    
      ;;;;;;;;;;;;;;;;;           :;;;;;;;;;;;;;;;;:     
       ,;;;;;;;;;;;;;,              ;;;;;;;;;;;;;;       
         .;;;;;;;;;`                  ,;;;;;;;;:         

    ;;;   ;;;;;`  ;;;;:  .;;  ;; ,;;;;;, ;;. `;,  ;;;;   
    ;;;   ;;:;;;  ;;;;;; .;;  ;; ,;;;;;: ;;; `;, ;;;:;;  
   ,;:;   ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;,`;, ;;  ;;  
   ;; ;:  ;;  ;;  ;;  ;; .;;  ;;   ,;,   ;;;;`;, ;;  ;;. 
   ;: ;;  ;;;;;:  ;;  ;; .;;  ;;   ,;,   ;;`;;;, ;;  ;;` 
  ,;;;;;  ;;`;;   ;;  ;; .;;  ;;   ,;,   ;; ;;;, ;;  ;;  
  ;;  ,;, ;; .;;  ;;;;;:  ;;;;;: ,;;;;;: ;;  ;;, ;;;;;;  
  ;;   ;; ;;  ;;` ;;;;.   `;;;:  ,;;;;;, ;;  ;;,  ;;;;

3. ScanNetworks on Rtlduino RTL8720DN

The following are debug terminal output and screen shot when running example ScanNetworks on Rtlduino RTL8720DN

Starting ScanNetworks on Rtlduino RTL8720DN with RTL8720DN
WiFiWebServer_RTL8720 v1.1.2
Current Firmware Version = 1.0.0
Attempting to connect to SSID: HueNet_5G
You're connected to the network, IP = 192.168.2.152
MAC address: 69:4E:06:60:C9:94

Scanning available networks...
Number of available networks:19
0) HueNet   Signal: -26 dBm Encryption: WPA2_PSK
1) HueNet_5G    Signal: -32 dBm Encryption: WPA2_PSK
2) HueNetTek    Signal: -32 dBm Encryption: WPA2_PSK
3) HueNetTek_5G Signal: -33 dBm Encryption: WPA2_PSK
4) HueNet1  Signal: -36 dBm Encryption: WPA2_PSK
5) HueNet2  Signal: -58 dBm Encryption: WPA2_PSK
6) HueNet2_5G   Signal: -60 dBm Encryption: WPA2_PSK
7) guest_24 Signal: -64 dBm Encryption: WPA2_PSK
8) bacau    Signal: -65 dBm Encryption: WPA2_PSK
9) guest_5  Signal: -77 dBm Encryption: WPA2_PSK
10) pitesti Signal: -77 dBm Encryption: WPA2_PSK

4. MQTTClient_Auth on Rtlduino RTL8720DN

The following are debug terminal output and screen shot when running example MQTTClient_Auth on Rtlduino RTL8720DN

Starting MQTTClient_Auth on Rtlduino RTL8720DN with RTL8720DN
WiFiWebServer_RTL8720 v1.1.2
Current Firmware Version = 1.0.0
Attempting to connect to SSID: HueNet_5G
Connected! IP address: 192.168.2.152
Attempting MQTT connection to broker.emqx.io...connected
Message Send : MQTT_Pub => Hello from MQTTClient_Auth on Rtlduino RTL8720DN with RTL8720DN
Message arrived [MQTT_Pub] Hello from MQTTClient_Auth on Rtlduino RTL8720DN with RTL8720DN
Message Send : MQTT_Pub => Hello from MQTTClient_Auth on Rtlduino RTL8720DN with RTL8720DN
Message arrived [MQTT_Pub] Hello from MQTTClient_Auth on Rtlduino RTL8720DN with RTL8720DN

5. MQTT_ThingStream on Rtlduino RTL8720DN

The following are debug terminal output and screen shot when running example MQTT_ThingStream on Rtlduino RTL8720DN

Start MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
WiFiWebServer_RTL8720 v1.1.2
Current Firmware Version = 1.0.0
Attempting to connect to SSID: HueNet_5G
Connected! IP address: 192.168.2.152
***************************************
STM32_Pub
***************************************
Attempting MQTT connection to broker.emqx.io
...connected
Published connection message successfully!
Subscribed to: STM32_Sub
MQTT Message Send : STM32_Pub => Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
MQTT Message receive [STM32_Pub] Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
MQTT Message Send : STM32_Pub => Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
MQTT Message receive [STM32_Pub] Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
MQTT Message Send : STM32_Pub => Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
MQTT Message receive [STM32_Pub] Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
MQTT Message Send : STM32_Pub => Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN
MQTT Message receive [STM32_Pub] Hello from MQTT_ThingStream on Rtlduino RTL8720DN with RTL8720DN

6. WiFiUdpNTPClient on Rtlduino RTL8720DN

The following are debug terminal output and screen shot when running example WiFiUdpNTPClient on Rtlduino RTL8720DN

Starting WiFiUdpNTPClient on Rtlduino RTL8720DN with RTL8720DN
WiFiWebServer_RTL8720 v1.1.2
Current Firmware Version = 1.0.0
Attempting to connect to SSID: HueNet_5G
Connected! IP address: 192.168.2.152
SSID: HueNet1, Signal strength (RSSI):-39 dBm
Starting connection to server...
Listening on port 2390
packet received
Seconds since Jan 1 1900 = 3835239949
Unix time = 1626251149
The UTC time is 8:25:49
packet received
Seconds since Jan 1 1900 = 3835239960
Unix time = 1626251160
The UTC time is 8:26:00
packet received
Seconds since Jan 1 1900 = 3835239971
Unix time = 1626251171
The UTC time is 8:26:11

Debug

Debug is enabled by default on Serial. Debug Level from 0 to 4. To disable, change the _WIFILOGLEVEL to 0

// Use this to output debug msgs to Serial
#define DEBUG_WIFI_WEBSERVER_PORT   Serial

// Debug Level from 0 to 4
#define _WIFI_LOGLEVEL_             1

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.

This WiFiWebServer_RTL8720 library currently supports these following boards:

  1. Realtek RTL8720DN, RTL8722DM and RTL8722CSM

The library provides supports to:

  1. WiFi Client, STA and AP mode
  2. TCP Server and Client
  3. UDP Server and Client
  4. HTTP Server and Client
  5. HTTP GET and POST requests, provides argument parsing, handles one client at a time.
  6. High-level HTTP (GET, POST, PUT, PATCH, DELETE) and WebSocket Client.

Issues

Submit issues to: WiFiWebServer_RTL8720 issues

TO DO

  1. Bug Searching and Killing
  2. Add SSL/TLS Client

DONE

  1. Add support to Realtek RTL8720DN, RTL8722DM and RTL8722CSM
  2. Add High-level HTTP (GET, POST, PUT, PATCH, DELETE) and WebSocket Client
  3. Fix bug related to usage of Arduino String
  4. Optimize library code and examples by using reference-passing instead of value-passing.
  5. Change from arduino.cc to arduino.tips in examples
  6. Add astyle using allman style. Restyle the library

Contributions and Thanks

  1. Based on and modified from Ivan Grokhotkov's ESP8266WebServer
  2. Adrian McEwen for HttpClient Library on which the ArduinoHttpClient Library and this EthernetWebServer library are relied.
igrr
⭐️⭐️ Ivan Grokhotkov
 amcewen
⭐️ Adrian McEwen

Contributing

If you want to contribute to this project:

License

Copyright

Copyright (c) 2021- Khoi Hoang