You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 29, 2023. It is now read-only.
1. Merge some upstream PRs
- Handling of errors - like unstable network - coming via SSL fhessel#89
- WIP: Prevent crash on WebSocket request to non-WebSocket node. fhessel#106
- Fix infinite loop when the buffer ends with \r fhessel#123
- Fixed memory leak in the Websocket example fhessel#157
2. Update examples and `README.md`
If you want a specific version, you can use a notation like `lib_deps = esp32_https_server@0.3.0`. More information on this can be found in the [PlatformIO documentation](https://docs.platformio.org/en/latest/projectconf/section_env_library.html).
46
+
If you want a specific version, you can use a notation like `lib_deps = https://github.com/khoih-prog/esp32_https_server.git@1.1.0`. More information on this can be found in the [PlatformIO documentation](https://docs.platformio.org/en/latest/projectconf/section_env_library.html).
47
47
48
48
To use the current master of the library, don't add it to your `platform.ini` but go to your project's `libs` folder and run the following command to get a copy of repository:
> **Note:** While the `master` branch should contain a running version of the library at any time, the API might already have changes towards the next major release. So for a stable setup, it is recommended to use a published release.
You can install the library using Arduino IDE's [library manager](https://www.arduino.cc/en/Guide/Libraries). In the _Sketch_ menu, click on _Include Library_ and select _Manage Libraries..._ directly at the top of the menu. Then search for "ESP32 HTTPS Server" and click on the _Install_ button.
59
59
60
-
Alternatively, you can download [a release](https://github.com/fhessel/esp32_https_server/releases) and extract it into your `Arduino/libraries` folder. Then restart your IDE.
60
+
Alternatively, you can download [a release](https://github.com/khoih-prog/esp32_https_server/releases) and extract it into your `Arduino/libraries` folder. Then restart your IDE.
61
61
62
62
If you want to use the latest `master` branch, open a command line, navigate to the libraries folder and run:
> **Note:** While the `master` branch should contain a running version of the library at any time, the API might already have changes towards the next major release. So for a stable setup, it is recommended to use a published release.
You will find several examples showing how you can use the library:
75
75
76
+
### For ESP32
77
+
76
78
-[Static-Page](examples/Static-Page/Static-Page.ino): Short example showing how to serve some static resources with the server. You should start with this sketch and get familiar with it before having a look at the more complex examples.
77
79
-[Parameters](examples/Parameters/Parameters.ino): Shows how you can access request parameters (the part after the question mark in the URL) or parameters in dynamic URLs (like /led/1, /led/2, ...)
78
80
-[Put-Post-Echo](examples/Put-Post-Echo/Put-Post-Echo.ino): Implements a simple echo service for PUT and POST requests that returns the request body as response body. Also shows how to differentiate between multiple HTTP methods for the same URL.
@@ -85,10 +87,30 @@ You will find several examples showing how you can use the library:
85
87
-[Self-Signed-Certificate](examples/Self-Signed-Certificate/Self-Signed-Certificate.ino): Shows how to generate a self-signed certificate on the fly on the ESP when the sketch starts. You do not need to run `create_cert.sh` to use this example.
86
88
-[REST-API](examples/REST-API/REST-API.ino): Uses [ArduinoJSON](https://arduinojson.org/) and [SPIFFS file upload](https://github.com/me-no-dev/arduino-esp32fs-plugin) to serve a small web interface that provides a REST API.
87
89
88
-
If you encounter error messages that cert.h or private\_key.h are missing when running an example, make sure to run create\_cert.sh first (see Setup Instructions).
90
+
### For WT32_ETH01
91
+
92
+
-[Static-Page](examples/WT32_ETH01/Static-Page/Static-Page.ino): Short example showing how to serve some static resources with the server. You should start with this sketch and get familiar with it before having a look at the more complex examples.
93
+
-[Parameters](examples/WT32_ETH01/Parameters/Parameters.ino): Shows how you can access request parameters (the part after the question mark in the URL) or parameters in dynamic URLs (like /led/1, /led/2, ...)
94
+
-[Put-Post-Echo](examples/WT32_ETH01/Put-Post-Echo/Put-Post-Echo.ino): Implements a simple echo service for PUT and POST requests that returns the request body as response body. Also shows how to differentiate between multiple HTTP methods for the same URL.
95
+
-[HTTPS-and-HTTP](examples/WT32_ETH01/HTTPS-and-HTTP/HTTPS-and-HTTP.ino): Shows how to serve resources via HTTP and HTTPS in parallel and how to check if the user is using a secure connection during request handling
96
+
-[Middleware](examples/WT32_ETH01/Middleware/Middleware.ino): Shows how to use the middleware API for logging. Middleware functions are defined very similar to webservers like Express.
97
+
-[Authentication](examples/WT32_ETH01/Authentication/Authentication.ino): Implements a chain of two middleware functions to handle authentication and authorization using HTTP Basic Auth.
98
+
-[Async-Server](examples/WT32_ETH01/Async-Server/Async-Server.ino): Like the Static-Page example, but the server runs in a separate task on the ESP32, so you do not need to call the loop() function in your main sketch.
99
+
-[Websocket-Chat](examples/WT32_ETH01/Websocket-Chat/Websocket-Chat.ino): Provides a browser-based chat built on top of websockets. **Note:** Websockets are still under development!
100
+
-[Parameter-Validation](examples/WT32_ETH01/Parameter-Validation/Parameter-Validation.ino): Shows how you can integrate validator functions to do formal checks on parameters in your URL.
101
+
-[Self-Signed-Certificate](examples/WT32_ETH01/Self-Signed-Certificate/Self-Signed-Certificate.ino): Shows how to generate a self-signed certificate on the fly on the ESP when the sketch starts. You do not need to run `create_cert.sh` to use this example.
102
+
-[REST-API](examples/WT32_ETH01/REST-API/REST-API.ino): Uses [ArduinoJSON](https://arduinojson.org/) and [SPIFFS file upload](https://github.com/me-no-dev/arduino-esp32fs-plugin) to serve a small web interface that provides a REST API.
103
+
104
+
---
105
+
---
106
+
107
+
If you encounter error messages that cert.h or private\_key.h are missing when running an example, make sure to run `create_cert.sh` first (see Setup Instructions).
89
108
90
109
You might also want to check out the (work-in-progress) [Documentation](https://fhessel.github.io/esp32_https_server/).
91
110
111
+
---
112
+
---
113
+
92
114
## Get Started
93
115
94
116
The following includes are required to be able to setup the server.
@@ -110,6 +132,9 @@ The following includes are required to be able to setup the server.
110
132
// Easier access to the classes of the server
111
133
usingnamespacehttpsserver
112
134
```
135
+
136
+
---
137
+
113
138
### Create Server Instance
114
139
115
140
You can create your server instance like shown below:
@@ -136,16 +161,19 @@ SSLCert cert = SSLCert(
136
161
HTTPSServer myServer = HTTPSServer(cert);
137
162
```
138
163
139
-
By default, the server will listen on port 443. If you want to change that (or some other options), you can have a look at the optional parameters of the [`HTTPServer`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPServer.html) or [`HTTPSServer`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPSServer.html) constructors.
164
+
By default, the server will listen on port `443`. If you want to change that (or some other options), you can have a look at the optional parameters of the [`HTTPServer`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPServer.html) or [`HTTPSServer`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPSServer.html) constructors.
140
165
141
166
The only difference between the HTTP and HTTPS version is the certificate which you have to configure. Keep in mind that each opened connection of the TLS-enabled `HTTPSServer` requires additional 40 to 50 kB of heap memory for the TLS connection itself. This has to be considered when increasing `maxConnections`.
142
167
168
+
---
169
+
143
170
### Add Resources to the Server
144
171
145
172
Every _route_ (or path) that should be accessible on the server has to be configured as a so-called `ResourceNode`. Such a node links a handler function to a specific route (like `/test`) and HTTP method (like `GET`). The handler function could look like this:
// We want to deliver an HTML page, so we set the content type
150
178
res->setHeader("Content-Type", "text/html");
151
179
// The response implements the Print interface, so you can use it just like
@@ -185,6 +213,8 @@ That's everything you need to do for a single web page on your server.
185
213
186
214
Note that you can define a single [`ResourceNode`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1ResourceNode.html) via `HTTPServer::setDefaultNode()`, which will be called if no other node on the server matches. Method and route are ignored in this case. Most examples use this to define a 404-handler, which might be a good idea for most scenarios. In case no default node is specified, the server will return with a small error page if no matching route is found.
187
215
216
+
---
217
+
188
218
### Start the Server
189
219
190
220
A call to [`HTTPServer::start()`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPServer.html#a1b1b6bce0b52348ca5b5664cf497e039) will start the server so that it is listening on the previously specified port:
@@ -197,16 +227,22 @@ This code usually goes into your `setup()` function. You can use `HTTPServer::is
197
227
198
228
By default, you need to pass control to the server explicitly. This is done by calling the [`HTTPServer::loop()`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPServer.html#af8f68f5ff6ad101827bcc52217249fe2) function, which you usually will put into your Arduino sketch's `loop()` function. Once called, the server will first check for incoming connection (up to the maximum connection count that has been defined in the constructor), and then handle every open connection if it has new data on the socket. So your request handler functions will be called during the call to `loop()`. Note that if one of your handler functions is blocking, it will block all other connections as well.
199
229
230
+
---
231
+
200
232
### Running the Server asynchronously
201
233
202
234
If you want to have the server running in the background (and not calling `loop()` by yourself every few milliseconds), you can make use of the ESP32's task feature and put the whole server in a separate task.
203
235
204
236
See the [Async-Server example](https://github.com/fhessel/esp32_https_server/tree/master/examples/Async-Server) to see how this can be done.
205
237
238
+
---
239
+
206
240
## Advanced Configuration
207
241
208
242
This section covers some advanced configuration options that allow you, for example, to customize the build process, but which might require more advanced programming skills and a more sophisticated IDE that just the default Arduino IDE.
209
243
244
+
---
245
+
210
246
### Saving Space by Reducing Functionality
211
247
212
248
To save program space on the microcontroller, there are some parts of the library that can be disabled during compilation and will then not be a part of your program.
@@ -219,6 +255,8 @@ The following flags are currently available:
219
255
220
256
Setting these flags requires a build environment that gives you some control of the compiler, as libraries are usually compiled separately, so just doing a `#define HTTPS_SOMETHING` in your sketch will not work.
221
257
258
+
---
259
+
222
260
**Example: Configuration with PlatformIO**
223
261
224
262
To set these flags in PlatformIO, you can modify your `platformio.ini`. To disable for example the self-signed-certificates part of the library, the file could look like this:
@@ -228,7 +266,7 @@ To set these flags in PlatformIO, you can modify your `platformio.ini`. To disab
0 commit comments