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
Copy file name to clipboardExpand all lines: README.md
+78-31Lines changed: 78 additions & 31 deletions
Original file line number
Diff line number
Diff line change
@@ -4,28 +4,65 @@ This repository contains an HTTPS server library that can be used with the [ESP3
4
4
5
5
## Features
6
6
7
-
- Make use of the built-in encryption of the ESP32 module
8
-
- Handle multiple clients in parallel (max 3-4 SSL clients due to memory limits)
9
-
- Usage of `Connection: keep-alive` and SSL Session reuse to reduce the overhead of SSL handshakes and speed up data transfer
10
-
- Abstraction of handling the HTTP stuff and providing a simple API for it, eg. to access parameters, headers, HTTP Basic Auth etc.
11
-
- Handling requests in callback functions that can be bound to URLs
12
-
- Using middleware functions as proxy to every request to perform central tasks like authentication or logging
13
7
- Providing support for HTTP, HTTPS or both at the same time
8
+
- Handling requests in callback functions that can be bound to URLs, like for example in Express or Servlets.
9
+
- Abstraction of handling the HTTP stuff and providing a simple API for it, eg. to access parameters, headers, HTTP Basic Auth etc.
10
+
- Using middleware functions as proxy to every request to perform central tasks like authentication or logging.
11
+
- Make use of the built-in encryption of the ESP32 module for HTTPS.
12
+
- Handle multiple clients in parallel (max. 3-4 TLS clients due to memory limits).
13
+
- Usage of `Connection: keep-alive` and SSL session reuse to reduce the overhead of SSL handshakes and speed up data transfer.
14
14
15
15
## Dependencies
16
16
17
17
The library is self-contained and just needs the Arduino and ESP32 system libraries. Running the examples requires the WiFi library in addition to that.
18
18
19
19
## Setup Instructions
20
20
21
-
Clone or download the content of this git repository into your Arduino/libraries folder and restart your IDE.
21
+
The steps to install this library depend on the IDE you are using. PlatformIO is recommended as you have more options to configure the library (see [Advanced Configuration](#advanced-configuration)), but the library can be used with the plain Arduino IDE.
22
+
23
+
### PlatformIO (Recommended)
24
+
25
+
The library is listed in PlatformIO's [library registry](https://platformio.org/lib/show/5887/esp32_https_server/). If you're using the IDE, search for `esp32_https_server` and install it, on the command line, just run:
26
+
27
+
```bash
28
+
pio lib install "esp32_https_server"
29
+
```
30
+
31
+
New release can take one or two days before they get picked up by the library crawler which makes them available in the registry. The version numbers of [releases](https://github.com/fhessel/esp32_https_server/releases) are based on [semantic versioning](https://semver.org/).
22
32
23
-
To run the examples (except for the _Self-Signed-Certificates_ example), you need to execute the script extras/create_cert.sh first. This script will create a simple CA to sign certificates that are used with the examples. Some notes on the usage can be found in the extras/README.md file.
33
+
Add the library to your `platform.ini` like in the following example:
34
+
35
+
```ini
36
+
[platformio]
37
+
env_default = wrover
38
+
39
+
[env:wrover]
40
+
platform = espressif32
41
+
board = esp32dev
42
+
framework = arduino
43
+
lib_deps = esp32_https_server
44
+
```
45
+
46
+
If you want a specific version, you can use a notation like `lib_deps = [email protected]`. More information on this can be found in the [PlatformIO documentation](https://docs.platformio.org/en/latest/projectconf/section_env_library.html).
47
+
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.
55
+
56
+
### Arduino
57
+
58
+
Download [the latest release](https://github.com/fhessel/esp32_https_server/releases) and extract it into your Arduino/libraries folder. Then restart your IDE.
24
59
25
60
You then should be able to add the library to your project if you selected the ESP32 as architecture.
26
61
27
62
## Examples
28
63
64
+
> **Note:** To run the examples (except for the _Self-Signed-Certificates_ example), you need to execute the script extras/create_cert.sh first (see [Issue #26](https://github.com/fhessel/esp32_https_server/issues/26) for Windows). This script will create a simple CA to sign certificates that are used with the examples. Some notes on the usage can be found in the extras/README.md file.
65
+
29
66
You will find several examples showing how you can use the library:
30
67
31
68
-[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.
@@ -67,7 +104,15 @@ using namespace httpsserver
67
104
```
68
105
### Create Server Instance
69
106
70
-
Then, you can create the server like this:
107
+
You can create your server instance like shown below:
108
+
109
+
**For HTTP:**
110
+
111
+
```C++
112
+
HTTPServer myServer = HTTPServer();
113
+
```
114
+
115
+
**For HTTPS:**
71
116
72
117
```C++
73
118
// Create certificate data (see extras/README.md on how to create it)
@@ -83,13 +128,13 @@ SSLCert cert = SSLCert(
83
128
HTTPSServer myServer = HTTPSServer(cert);
84
129
```
85
130
86
-
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 HTTPSServer constructor.
131
+
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.
87
132
88
-
If you want to have just an HTTP server, you can skip the SSLCert part and replace HTTPSServer by HTTPServer. Everything else is the same for both protocols.
133
+
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`.
89
134
90
135
### Add Resources to the Server
91
136
92
-
Every URL 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 URL and HTTP method. The handler function could look like this:
137
+
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:
As you can see, the function gets references to the HTTP request and response. You can use the request to read headers, parameters, authentication information etc. The response can be used to send data to the client, set headers or HTTP status codes.
156
+
As you can see, the function gets references to the [`HTTPRequest`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPRequest.html) and [`HTTPResponse`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1HTTPResponse.html). You can use the request to read headers, parameters, authentication information etc. The response can be used to send data to the client, set headers or HTTP status codes.
112
157
113
-
Now we need to tell the server which URL should be served by this function. This can be done by creating a `ResourceNode` (usually in your `setup()` function).
158
+
Now we need to tell the server which URL should be served by this function. This can be done by creating a [`ResourceNode`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1ResourceNode.html) (usually in your `setup()` function).
114
159
115
160
```C++
116
161
ResourceNode * nodeRoot = new ResourceNode("/", "GET", &handleRoot);
117
162
```
118
163
119
-
The first parameter defines the URL. It should always start with a slash, and using just a slash like here means that the function will be called for requests to the server's root (like https:/10.0.x.x/).
164
+
The first parameter defines the route. It should always start with a slash, and using just a slash like in this example means that the function will be called for requests to the server's root (like https://10.0.x.x/).
120
165
121
-
The second parameter is the HTTP method, "GET" in this case.
166
+
The second parameter is the HTTP method, `"GET"` in this case.
122
167
123
-
Finally, you pass a reference to the request handler function to link it to the URL and method.
168
+
Finally, you pass a reference to the request handler function to link it to the route and method.
124
169
125
-
Now you just need to register the created `ResourceNode` at your server:
170
+
Now you just need to register the created [`ResourceNode`](https://fhessel.github.io/esp32_https_server/classhttpsserver_1_1ResourceNode.html) at your server:
126
171
127
172
```C++
128
173
myServer.registerNode(nodeRoot);
129
174
```
130
175
131
176
That's everything you need to do for a single web page on your server.
132
177
133
-
Note that you can define a single `ResourceNode` via `HTTPServer::setDefaultNode()`, which will be called if no other node on the server matches. Method and Path are ignored in this case. All examples use this to define a 404-handler, which might be a good idea for most scenarios.
178
+
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.
134
179
135
180
### Start the Server
136
181
137
-
A call to `HTTPServer::start()` will start the server so that it is listening on the port specified:
182
+
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:
138
183
139
184
```C++
140
185
myServer.start();
141
186
```
142
187
143
188
This code usually goes into your `setup()` function. You can use `HTTPServer::isRunning()` to check whether the server started successfully.
144
189
145
-
By default, you need to pass control to the server explicitly. This is done by calling the `HTTPServer::loop()` 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.
190
+
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.
146
191
147
192
### Running the Server asynchronously
148
193
149
194
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.
150
195
151
-
See the Async-Server example to see how this can be done.
196
+
See the [Async-Server example](https://github.com/fhessel/esp32_https_server/tree/master/examples/Async-Server) to see how this can be done.
152
197
153
198
## Advanced Configuration
154
199
155
-
This section covers some advanced configuration options that allow you e.g. to customize the build process, but which might require more advanced programming skills and a more sophisticated IDE that just the default Arduino IDE.
200
+
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.
156
201
157
202
### Saving Space by Reducing Functionality
158
203
@@ -166,15 +211,16 @@ The following flags are currently available:
166
211
167
212
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.
168
213
169
-
**Example: Configuration with Platform IO**
214
+
**Example: Configuration with PlatformIO**
170
215
171
-
To set these flags in Platform IO, you can modify your `platformio.ini`. To disable for example the self-signed-certificates part of the library, the file could look like this:
216
+
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:
172
217
173
218
```ini
174
-
[env:esp32dev]
219
+
[env:wroom]
175
220
platform = espressif32
176
221
board = esp32dev
177
222
framework = arduino
223
+
lib_deps = esp32_https_server
178
224
build_flags =
179
225
-DHTTPS_DISABLE_SELFSIGNING
180
226
```
@@ -183,15 +229,15 @@ Note the `-D` in front of the actual flag name, that passes this flag as a defin
183
229
184
230
### Configure Logging
185
231
186
-
The server provides some internal logging, which is used on level `INFO` by default. This will look like this on your serial console:
232
+
The server provides some internal logging, which is activated on level `INFO` by default. This will look like this on your serial console:
187
233
188
234
```
189
235
[HTTPS:I] New connection. SocketFID=55
190
236
[HTTPS:I] Request: GET / (FID=55)
191
237
[HTTPS:I] Connection closed. Socket FID=55
192
238
```
193
239
194
-
Logging output can also be controlled by using compiler flags. This requires an advanced development environment like explained in *Saving Space by Reducing Functionality*.
240
+
Logging output can also be controlled by using compiler flags. This requires an advanced development environment like explained in [Saving Space by Reducing Functionality](#saving-space-by-reducing-functionality).
195
241
196
242
There are two parameters that can be configured:
197
243
@@ -206,15 +252,16 @@ There are two parameters that can be configured:
206
252
| 3 | ✓ | ✓ | ✓ ||
207
253
| 4 | ✓ | ✓ | ✓ | ✓ |
208
254
209
-
**Example: Configuration with Platform IO**
255
+
**Example: Configuration with PlatformIO**
210
256
211
-
To set these flags in Platform IO, you can modify your `platformio.ini`. The following entries set the minimum log level to warning and enable timestamps
257
+
To set these flags in PlatformIO, you can modify your `platformio.ini`. The following entries set the minimum log level to warning and enable timestamps
0 commit comments