This template can be a base for your own ESP32 based projects needing a responsive web user interface. It is written using Arduino framework and I show here how to develop both C++ and HTML part of the project in a clear way.

The template combines all useful technologies in one:

WebSockets - to provide a fast and elegant communication between web browser and ESP32 withough reloading a page like in case of HTTP requests.

Bootstrap 4 - one of the most popular frameworks for rapid web page design. Thanks to Bootstrap you can easily write a pretty web UI, looking good both on mobile and desktop devices.

JSON - an elegant way to format data exchanged between web browser and ESP32.

Husarnet - a Virtual LAN network thanks to which you can access ESP32 both from LAN network and through the internet, without static IP adressess, setting port forwarding on your router etc.

A demo is really basic:

control a LED connected to ESP32 by using a button in web UI.

ESP32 sends a counter value every 100ms.

ESP32 sends a button state to change a color of the dot in web UI.

Project configuration

At the top of ESP32_ledstrip_webserver.ino file there is a configuration section for your project:

/* =============== config section start =============== */

const int BUTTON_PIN = 22;

const int LED_PIN = 16;

// WiFi credentials

#define NUM_NETWORKS 2

// Add your networks credentials here

const char* ssidTab[NUM_NETWORKS] = {

"wifi-ssid-one",

"wifi-ssid-two",

};

const char* passwordTab[NUM_NETWORKS] = {

"wifi-pass-one",

"wifi-pass-two",

};

// Husarnet credentials

const char* hostName = "esp32websocket"; //this will be the name of the 1st ESP32 device at https://app.husarnet.com

/* to get your join code go to https://app.husarnet.com

-> select network

-> click "Add element"

-> select "join code" tab

Keep it secret!

*/

const char* husarnetJoinCode = "xxxxxxxxxxxxxxxxxxxxxx";

/* =============== config section end =============== */

You can hardcode more than one Wi-Fi network credentials. Thanks to that you don't need to reprogram your board each time you power that in a new location.

There is also Husarnet configuration section: you define here ESP32 hostname that will be used to identify your device worldwide through you Husarnet Virtual LAN network. Note that thanks to Husarnet, ESP32 webserver will work the same way in LAN and through the internet. All devices within a single Husarnet network (could be computers, ESP32) see each other like they were in the same LAN network. That's a very convenient way to access your devices P2P, with low latency, worldwide without playing with port forwarding settings on your routers, or having static IP addresses.

Useful tips

Here are some ideas that are very helpful while developing a HTML code running in HTTP servers hosted by ESP32:

1. placing HTML code into Cstring in C/C++ code:

In many examples you can find in the internet a HTML code is included in C++/.ino file in the following way:

static const char* htmlHead = "<head><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><link rel=\"icon\" href=\"data:,\"><style>";

Each " sign within original HTML code must be preceded by \ sign to be recognised well by the C++ compiler. That makes creating and maintaining HTML code very hard.

C++11 standard introduced a new way to solve that problem:

static const char* htmlHead = R "delimiter( raw_characters )delimiter";

In raw_characters section you can place the whole HTML file without any modyfications.

2. placing HTML code into CString in C/C++ code:

Often you need to write many lines of HTML code. It may contain also JavaScript sections and long <head> section. Placing that HTML code, even within R"delimiter( ...)delimiter"; section will make your code long and hard to maintain. The good idea is to put the whole HTML file into a separate header file that is included within your C/C++/ino file in the following way:

const char* html =

#include "html.h"

;

html.h file contains 1:1 the same code as in index.html with additional lines at the beggining and end:

R"rawText( //add only this ...

<!DOCTYPE html>

<html>

<head>

...

</head>

...

</html>

)rawText" //and this line to original HTML file to include it easily into your C++/ino code.

Preparing a hardware

Connect push button between pin P22 and GND

Connect LED diode and resistor in series between pin P16 and GND

Connect battery to your ESP32-based board or power it from USB port (depending on your devboard). In the project we use ESP32 devkit with a built-in LDO. Take a look at maximum input voltage level in case of your ESP32-based board to avoid damage.

Prepare your Arduino IDE

To install all needed for the project libraries, open Arduino IDE and follow these steps:

1. Install Husarnet package for ESP32:

open File -> Preferences

in a field Additional Board Manager URLs add this link: https://files.husarion.com/arduino/beta/package_esp32_husarnet_index.json

open Tools -> Board: ... -> Boards Manager ...

Search for esp32-husarnet

Click Install button

2. Select ESP32 dev board:

open Tools -> Board

select ESP32 Dev Module under "ESP32 Arduino (Husarnet)" section

3. Install ArduinoJson library:

open Tools -> Manage Libraries...

search for ArduinoJson

select version 5.13.3

click install button

4. Install arduinoWebSockets library (Husarnet fork):

download https://github.com/husarnet/arduinoWebSockets as a ZIP file (this is Husarnet compatible fork of arduinoWebSockets by Links2004 (Markus) )

https://github.com/husarnet/arduinoWebSockets open Sketch -> Include Library -> Add .ZIP Library ...

choose arduinoWebSockets-master.zip file that you just downloaded and click open button

Run a demo

At this stage your Arduino IDE is ready to build project files. Follow these steps to run a project.

I. Program ESP32 board:

Open ESP32-http-websocket.ino project

modify line 32 with your Husarnet join code (get on https://app.husarnet.com)

modify lines 11 - 20 to add your Wi-Fi network credentials

upload project to your ESP32 board.

II. Open WebUI:

There are two options:

1. Public link: log into your account at https://app.husarnet.com, find esp32websocket device that you just connected and click web UI button. You can also click esp32websocket element to open "Element settings" and select Make the Web UI public checkbox if you want to have a publically available address. In such a scenerio Husarnet proxy servers are used to provide you a web UI.

2. P2P option: add your laptop to the same Husarnet network as ESP32 board. In that scenerio no proxy servers are used and you connect to ESP32 with a very low latency directly with no port forwarding on your router! Currenly only Linux client is available, so open your Linux terminal and type:

$ curl https://install.husarnet.com/install.sh | sudo bash to install Husarnet.

$ husarnet join XXXXXXXXXXXXXXXXXXXXXXX mylaptop replace XXX...X with your own join code (see point 4), and click enter.

At this stage your ESP32 and your laptop are in the same VLAN network. The best hostname support is in Mozilla Firefox web browser (other browsers also work, but you have to use IPv6 address of your device that you will find at https://app.husarnet.com) and type: http://esp32websocket:8000 You should see a web UI to controll your ESP32 now.

-

I hope you will find that project useful. Would be happy to know your feedback. Enjoy :)