ESP32 HTTPS Server
|
This repository contains an HTTPS server library that can be used with the ESP32 Arduino Core. It supports HTTP as well.
Connection: keep-alive
and SSL Session reuse to reduce the overhead of SSL handshakes and speed up data transferThe library is self-contained and just needs the Arduino and ESP32 system libraries. Running the examples requires the WiFi library in addition to that.
Clone or download the content of this git repository into your Arduino/libraries folder and restart your IDE.
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.
You then should be able to add the library to your project if you selected the ESP32 as architecture.
You will find several examples showing how you can use the library:
create_cert.sh
to use this example.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).
You might also want to check out the (work-in-progress) Documentation.
The following includes are required to be able to setup the server.
Then, you can create the server like this:
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.
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.
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:
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.
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).
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/).
The second parameter is the HTTP method, "GET" in this case.
Finally, you pass a reference to the request handler function to link it to the URL and method.
Now you just need to register the created ResourceNode
at your server:
That's everything you need to do for a single web page on your server.
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.
A call to HTTPServer::start()
will start the server so that it is listening on the port specified:
This code usually goes into your setup()
function. You can use HTTPServer::isRunning()
to check whether the server started successfully.
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.
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.
See the Async-Server example to see how this can be done.
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.
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.
The following flags are currently available:
Flag | Effect |
---|---|
HTTPS_DISABLE_SELFSIGNING | Removes the code for generating a self-signed certificate at runtime. You will need to provide certificate and private key data from another data source to use the HTTPSServer . |
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.
Example: Configuration with Platform IO
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:
Note the -D
in front of the actual flag name, that passes this flag as a definition to the preprocessor. Multiple flags can be added one per line.
The server provides some internal logging, which is used on level INFO
by default. This will look like this on your serial console:
Logging output can also be controlled by using compiler flags. This requires an advanced development environment like explained in Saving Space by Reducing Functionality.
There are two parameters that can be configured:
HTTPS_LOGLEVEL
defines the log level to useHTTPS_LOGTIMESTAMP
adds a timestamp (based on uptime) to each log entryValue of HTTPS_LOGLEVEL | Error | Warning | Info | Debug |
---|---|---|---|---|
0 | ||||
1 | ✓ | |||
2 | ✓ | ✓ | ||
3 | ✓ | ✓ | ✓ | |
4 | ✓ | ✓ | ✓ | ✓ |
Example: Configuration with Platform IO
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