Easy Home Webserver, IoT, Automation & More With ESP32-S3

The ESP32 S3 Webserver Project was designed to provide a flexible base for building various web-enabled micro-controller projects on from within the Arduino environment. It can be used to build a personal webserver, monitoring, facilitate home automation and more. Using the powerful ESP32 S3, it offers 240MHz and 320KB RAM. Depending on the ESP32 S3 module used, 4-32MB of Flash is available. The ESP32 S3 offers built-in WiFi and Bluetooth support. The asynchronous library used allows up to 8 clients to be connected to the server simultaneously. It supports HTML and WebSockets.

The ESP32 S3 Webserver Project is divided into hardware and software sections which can each be used independently or combined to provide the synergy to get a project up and running quickly. The project provides the necessary infrastructure for a wide range of simple to complex IOT projects. Using The ESP32 S3 Webserver Project allows you to concentrate on the individual aspects of your project without having to worry about the web server infrastructure. The ESP32 S3 Webserver Project hardware can be used for rapid prototyping as well as in finished projects without the need of building the hardware twice.

The ESP32 S3 Webserver Project software optionally supports Over the Air (OTA) flashing, SD and/or LittleFS (file storage in flash memory), connectivity as an access point and WiFi, client-side webpage caching, a local timezone including daylight savings time where appropriate, time synching over the internet, an Admin, File Manager and Status webpage, Serial Monitor support over a webpage, WebSockets and sending/receiving Telegram messages. The various options are easily selected and configured from a single header file.

While not absolutely necessary to use the software, The ESP32 S3 Webserver Project hardware makes it easier by providing breakouts and connectors for many things. The board has been designed as a standalone or to attach to the back of a 3.5 inch 480 x 320 TFT Display, with or without a touchscreen. The board provides connectors for 5V in/out, 3.3V in/out, I2C, SPI SD/SDHC card (or connect to one already on the TFT display), SD/SDXC MMC card, TX/RX Port, USB Port, reset button, and boot button. A standard SPI port is also provided for additional SPI devices. The gerber files are included and can be used to easily order your own boards. Minimal soldering skill is needed - even a beginner can handle it.

The ESP32 S3 Webserver Project is fully documented. The full documentation (44 pages), as well as the gerber files for the PCB and the complete software are available from MicroControllerReal/ESP32S3WebServerProject (github.com).

You can use the software with no additional hardware other than an ESP32-S2 DevKit module.

As mentioned in the introduction, The ESP32 S3 Webserver Project has lots of options. Some of them are easily implemented by simply making entries in customize.h (such as implementing the status webpage). Others may require specific hardware (such as an SD module or a TFT display). A few require specific libraries to be installed within your Arduino IDO (such as Telegram or my SerialWS library which is included within this project).

To get you started quickly and show you just how powerful this project can be, the Quickstart presented below requires no additional hardware other than an ESP32 S3 DevKit module. The Quickstart is included in the manual as well and is followed by several examples of how you can implement your own custom features such as webpages, sensors, etc.

The Quickstart presented below should be enough to whet your appetite but you will definitely want to read through the full documentation before getting too deep into your own projects.

This quick start assumes you have made NO changes to customize.h. Therefore, this will be a minimal installation and:

1. The server name will be WebServer and create its’ own access point
2. The password to connect to the WebServer access point will be “TopSecret”
3. The server will not connect to your local WiFi
4. The local timezone will be set to US Eastern Time
5. Administration will only be available from the WebServer access point
6. The logon and password for administration will be “Admin” and “Secret”
7. LittleFS (files on flash) will be enabled and may be formatted if necessary
8. No SD card is used
9. The Serial Monitor will be enabled and setup will be verbose (lots of messages)
10. The file manager will be enabled (so you can easily load the required files later)
11. SerialWS will be enabled (but not yet available until you load the files using fileman)
12. Telegram messaging will be disabled

Set your board settings to the correct settings and be sure to select a partition that allows some LittleFS usage. For example:

1. Board: "ESP32S3 Dev Module"
2. Flash Size: "4MB (32Mb)"
3. Partition Scheme: "Minimal (1.3MB APP/700KB SPIFFS)"
4. Erase All Flash Before Sketch Upload: "Disabled"

(Make sure you select a partition scheme that includes SPIFFS or LittleFS!)

The ESP32 S3 Webserver Project software uses my SerialWS library. If you have not previously installed it, you will need to do so before compiling the sketch. To do so:

1. From the Arduino menu, select Sketch -> Include Library -> Add ZIP Library
2. Locate the SerialWS.zip file I have included with the rest of the files for this project and open it.
3. The Arduino IDE will do the rest for you.

EDIT: I've had the libraries installed so long that I take them for granted and don't think about them. Of course, there are other libraries used within this sketch. You may also need to download and install additional libraries such as ESPAsyncWebServer, by lacamera, 3.1.0, ESPAsyncTCP, by dvarrel, 1.2.4, ArduinoJson, by Benoit Blanchon, 7.0.2, and UniversalTelegramBot, by Brian Lough, 1.3.0 (or later versions).

You should open the Arduino Serial Monitor before loading the sketch. That way, you will see the messages from the server as it starts up. If errors occur, you will see them too. You will receive warnings about missing files and the current time will be strange, but we will take care of those issues in the next steps. A sample Serial Monitor output is shown in the picture.

Once you have loaded the sketch onto your board you will be able to:

1. See the access point in your WiFi settings and log onto it using the password you set with #define def_APpassword in customize.h- Go ahead and log on now. (Tip: Open the documentation pdf before logging onto the webserver access point)
2. ping webserver from a command line and get a result.
3. Access http://webserver/fileman from your web browser.

Congratulations! The webserver is up and running! The first thing that needs to be done is to load some more files onto the webserver.

Once the files have been created on the mass storage (which you will do in a later step), you will be able to:

1. Access http://webserver from your browser and get the clock wegpage contained in /main.htm or even enter simply webserver into your browser and get the same response
2. Access http://webserver/status from your browser and get the Status wegpage which is fully described in the documentation.
3. Access http://webserver/SerialWS from your browser and get the SerialWS web based Serial Monitor which is fully described later in the documentation.
4. Access http://webserver/admin from your browser and get the Admin wegpage which is fully described in the documentation.

If you are using a SD or MMC card, connect it now. You may want to test the SD/MMC card using the examples included within the SD or SD_MMC libraries. If you are using The ESP32 S3 Webserver Project hardware, be sure to configure using the pins designated within this documentation for the SD/MMC card.

Once that is done, if you are using a SD or MMC card or you want to use Telegram messaging in your project, make those changes to customize.h and, yet again, reload the sketch to your board. Pay particular attention to the Serial Monitor for any warning or error messages and resolve those problems before going any further.

If you configured Telegram to send and receive and have configured the bot and chat id(s) properly, you may get a Telegram message when the server boots (if you configured that option) and may also be able to send “/status” in a Telegram message to your server to get the same status description as in the Status webpage.

It is NOT recommended to set serialEnabled to false until you are fairly sure that the server is running properly. Once everything is running properly, you could disable the Serial and use SerialWS

The first steps you should take are to use the File Manager webpage and load the rest of the files onto the server and use the Admin webpage to configure YOUR project.

The File Manager Webpage is in a file (fileman.htm) and, if enabled in customize.h (#define UseFileManager true) must be on the SD or LittleFS as specified by #define StandardFiles in customize.h. You can call it up in your browser with http://webserver/fileman

To make the webserver fully functional, load the following files to the webserver the first time you use the File Manager.

1. Main.htm: A sample webpage that is basically just a clock
2. admin.htm: The admin webpage for changing basic settings
3. fileman.htm: The file manager webpage which can be used to manage files
4. SerialWS.htm: The web based Serial Monitor
5. favicon.ico: A sample icon for the web page

Once fileman.htm has been loaded to the server, you should change embedFileman to false in customize.h because the embedded version is no longer needed now that you have loaded the fileman.htm file onto LittleFS and the embedded version is only taking up program space.

If OTA was enabled, you might take this opportunity to test loading the sketch via OTA instead of using the USB. You should see the webserver as a network port under tools.

The file manager webpage can be used to list, delete, upload and download files and create new directories on/to/from a SD card and/or LittleFS. When uploading, a progress bar is displayed. This webpage contains samples of using websockets with JSON formatted parameters.

The webpage is rather intuitive to use. The files can be sorted by name, date, or size, in ascending or descending order by clicking on the appropriate header in the file listing. The first click will sort using that column in ascending order, the second click in descending order, and the third click will return to the “natural” order (the order the files are found when reading the directory).

To download a file, simply select the desired file using the radio button to the left of the filename and click the Download button.

To delete a file, simply select the desired file and click the Delete button. WARNING: There is no request for confirmation. You click, you lose. (Which is why you might want to put the system files in the area protected from the file manager. See FMblockedPath in the documentation.)

To upload a new file into the displayed directory, first select the file by clicking on the Select File button (my example in the picture is in German and says “Datei auswählen” because the browser uses the international settings of the computer the browser is on). Then, click on the Upload button. There will be a progress bar displayed, but it really only makes graphical sense when uploading larger files.

You can switch between SD and LittleFS (if enabled in customize.h) using the dropdown. You can move between directories using that dropdown. Note that the directory “..” is used to move up one directory level.

You can create a new directory by clicking the New Dir button. A popup will appear where you enter the name of the new directory.

The Admin Webpage is in a file (Admin.htm) and must be on the SD or LittleFS as specified by #define StandardFiles in customize.h. You can call it up in your browser with http://webserver/admin. Before using the admin webpage for the first time, make an edit to customize.h and set def_FORCE to false. If you don’t set def_FORCE to false, any changes you make to the configuration using the Admin webpage will be overwritten the next time the server boots.

The admin webpage is used to configure The ESP32 S3 Webserver Project software once the server is up and running. It also provides samples of using websockets with simple string array styled parameters.

You will notice that many options of The ESP32 S3 Webserver Project, such as the use of a SD/MMC card, LittleFS or Telegram cannot be configured from the admin webpage. This is intentional. By configuring those options within customize.h, the respective parts of the software can be included or excluded. By excluding unnecessary parts of the software, more space is available for LittleFS (though the Flash Partition may need to be tweaked).

When configuring your webserver:

Host Name: The name given here forms the address for webpages and OTA (if implemented) as well as for the access point (with AP added to the end). The host name must be 4 to 32 characters long. The first character must be A-Z or a-z.

Broadcast AP: If checked, anyone looking for networks in the area will see this access point. If set to false, the name of this access point will not be listed as an available network and they would have to know the name and type it in in order to attempt to access the access point.

AP Password: Must be between 8 and 16 characters. It must have at least one character from at least three of the following four groups: A-Z, a-z, 0-9 or a special character (such as !, ., +, -, or #).

WiFi Name: Must, of course, match your local WiFi name for this server to access your local WiFi. If blank, no WiFi connection will be made and the webserver will only be available over the access point it provides. Without a WiFi connection, time synchronization and Telegram are, of course, also not available.

WiFi Password: Will be ignored if no WiFi name is provided.

Admin Name: Must be 6 to 16 characters long. The first character must be A-Z or a-z. (Yes, the default of “Admin” violates the rules und therefore MUST be changed. This is intentional!) The same logon and password are used for the file manager and SerialWS web pages if they are implemented.

Admin Password: The rules are the same as for AP Password. (Again, the default value of “Secret” violates the rules and therefore MUST be changed and is intentional!)

Timezone: The time zone defines your local time zone and daylight savings time implementation. The entry must be 4 to 50 characters long. Further rules apply simply because timezones have a specific format of how they are expressed. (NOTE: Don’t blame me for the syntax of the entry. I didn’t invent it! It is an international standard.)

If you live in the Eastern Time zone of the US, your entries might be:

EDT+5:00EST+4:00,M3.2.0/2:00,M11.1.1/2:00 and us.pool.ntp.org

In Germany, our timezone data is CET-1:00CEST-2:00,M3.5.0/2:00,M10.5.0/3:00

That entry is interpreted as:

CET and CEST represent the name of the time zone during daylight savings and standard.

-1:00 and -2:00 are the offsets from this time zone to UTC/Greenwich during daylight savings and standard. M3.5.0/2:00 and M10.5.0/3:00 indicates that time changes in month 3 (March) and 10 (October) on the last (1-4 indicates which occurrence and 5 indicates the last occurrence) Sunday (0, Monday is 1, Saturday is 6) at 2:00 or 3:00 AM (24 hour clock).

Time Server: Must be between 8 and 35 characters long. Of course, in order for time synchronization to work, it has to be a valid internet time server. It is strongly recommended to make this entry a “pool” of time servers (indicated by the presence of “pool” in the server name). If in doubt, pool.ntp.org will always work but may be less accurate than using a server closer to your location. Tip, your WiFi router may even provide a time server of its own!

Date/Time: Must be exactly 14 numeric digits expressing the date and time in yyyymmddhhmmss format. (Year, month, day, hour, minutes, seconds) If a WiFi is available, the date and time will be synchronized to the Time Server periodically so this setting only makes sense if no WiFi is available. If there is no WiFi, this setting will need to be manually made each time the server boots.

Once you have The ESP32 S3 Webserver Project (hardware and) software up and running, refer to Customizing Your Own Project in the documentation for information on how to add your own coding and features to your project.

Appendix A in the documentation contains information on how to create your own Flash Partition to optimize the amount of space available for LittleFS.

Appendix B contains an example of a custom project and adds a water detection alarm, complete with it's own webpage.

Appendix C expands on appendix B and adds the ability to send notification messages and control a sump pump via Telegram Messages.

Appendix D expands on appendix C and shows how to add a graphics display to the server which is very easy to do if you are using The ESP32 S3 Webserver Project hardware.

You now have all the infrastructure to realize your own webserver, IoT, home automation, monitoring, ... projects. The sky is the limit!