ESP-IDF: ESP32 Simple Web Server (Serve HTML Page)

This guide shows how to build a simple local web server with the ESP32 programmed with ESP-IDF that serves a simple HTML web page. This web page can then be accessed on your local network. This example can then be further expanded to add buttons or text fields to control and monitor the ESP32 GPIOs.

Using Arduino IDE? Follow this tutorial instead: Building an ESP32 Web Server: The Complete Guide for Beginners (Arduino IDE).

Prerequisites

Before following this guide, you need to install the ESP-IDF extension on VS Code IDE (Microsoft Visual Studio Code). Follow the next guide to install it, if you haven’t already:

• Getting Started Guide: Programming ESP32 with ESP-IDF using VS Code

You will also need an ESP32 development board model of your choice.

Introducing Web Servers

In simple terms, a web server is a “computer” that delivers web pages. It stores the website’s files, including HTML documents and related assets like images, CSS style sheets, fonts, and other files. When a user makes a request, the server sends those files to the user’s web browser.

When you access a web page in your browser, you’re actually sending a request to a server using HTTP. This protocol handles how information is requested and delivered on the Internet. The server then responds by sending the web page you asked for, also through HTTP.

Client-Server (ESP32 as a Server)

When you type a URL in your browser, your device (the client) sends a request to a server using the Hypertext Transfer Protocol (HTTP). The server receives the request and responds—also via HTTP—by sending back the web page.

Throughout this tutorial, we’ll treat the ESP32 as the server, and you, using your browser, as the client.

ESP-IDF: ESP32 Web Server

For this tutorial, let’s take a look at a practical example with the ESP32 that acts as a local web server in the local network.

Typically, a web server with the ESP32 in the local network looks like this: the ESP32 running as a web server is connected via Wi-Fi to your router. Your computer, smartphone, or tablet, are also connected to your router via Wi-Fi or Ethernet cable. So, the ESP32 and your browser are on the same network.

When you type the ESP32 IP address in your browser, you are sending an HTTP request to your ESP32. Then, the ESP32 responds with a response that can contain a value, a reading, HTML text to display a web page, or any other data.

In this particular tutorial, when you type the ESP32 IP address in your web browser, the ESP32 will respond by sending HTML text to create a simple web page (the page shown in the picture below).

For simplicity, we’re creating this very simple web page. This example can then be further expanded to add buttons or text fields to control and monitor the ESP32 GPIOs (we’ll cover this in future tutorials).

Creating an ESP-IDF Template App Project for the ESP32

The ESP-IDF extension provides an easy way to create a project from scratch with all the required files and configurations generated automatically.

To create a new ESP-IDF project on VS Code, follow these steps:

1. Open the ESP-IDF Espressif extension
2. Expand the “Advanced” menu
3. Click the “New Project Wizard” option
4. Choose the “Use ESP-IDF v5.4.1” to select the framework version

A new window opens, you need to fill in these fields:

• Project Name: type the desired project name;
• Enter Project Directory: click the folder icon and select the target folder to save all your project files. You can use any directory. Note: do NOT use a Google Drive / One Drive / Dropbox folder, because it will write/create many files during the building process—if it’s on a cloud folder, this process might be extremely slow;
• ESP-IDF Target: select the target device chip, I’m using an ESP32 with the esp32s3 chip;
• ESP-IDF Board: for the esp32s3 chip, I also need to select the configuration: ESP32-S chip (via builtin USB-JTAG);
• Serial Port: while having your ESP32 board connected to your computer, select the correct COM port number that refers to your ESP32;
• Choose Template: click the blue button to create a new project using a template.

In the menu, select the “ESP-IDF Templates” sample project and press the “Create project using template sample project” button.

Opening the ESP-IDF Project on VS Code

After a few seconds, a notification will appear in a new window in VS Code. You can click “Open Project” to open the newly created ESP-IDF sample project template.

IMPORTANT: if you didn’t see the notification that allows you to automatically open the ESP-IDF project on VS Code, you can easily do it by following these instructions:

Go to File > Open Folder…

Browse on your computer for the esp-idf-project folder (your project folder name that you’ve previously defined) and “Select Folder“.

That’s it! Your new ESP-IDF project template has been successfully created and opened.

ESP-IDF generates many files, folders, and subfolders for your project. For this guide, I recommend keeping all the default files unchanged; we will only modify the main.c file.

The example code will be written in the main.c file. To open it, follow these instructions:

1. Open the project explorer by clicking the first icon on the left sidebar.
2. Select your project folder name, in my case it’s “ESP-IDF-PROJECT“.
3. Expand the “main” folder.
4. Click the “main.c” file.
5. The default main.c template file loads in the code window.

Create the Wi-Fi Config Options File – Kconfig.projbuild

The Kconfig.projbuild file in ESP-IDF is a configuration file placed in a project’s main folder to define custom options in the SDK Configuration Editor (menuconfig tool). This allows users to set specific settings like strings or values that will be used during build configuration.

To create the Kconfig.projbuild file, go to the File Explorer left sidebar and right-click on top of the main folder. Then, select the “New File…” option:

Name the new file exactly as follows: Kconfig.projbuild and copy the content (shown after the following screenshot) to your newly created file.

menu "Wi-Fi Configuration"
    config ESP_WIFI_SSID
        string "WiFi SSID"
        help
            SSID (network name) you want to connect to.

    config ESP_WIFI_PASSWORD
        string "WiFi Password"
        help
            Password of the Wi-Fi network you want to connect to.
endmenu

Save the file content. This will create a new menu called “Wi-Fi Configuration” in the SDK Configuration Editor where you can type you SSID and Password, so the ESP can connect to your network.

Having the Kconfig.projbuild file prepared, click the gear icon to open the SDK Configuration Editor (menuconfig).

Now, instead of typing your network credentials inside the main.c file, you can configure them in the menuconfig tool. Follow these next steps:

1. Search for “wifi“;
2. Type your SSID and Password in the fields;
3. Press the “Save” button to apply the changes.

Code: ESP32 Simple Web Server using ESP-IDF

Copy the following code to the main.c file. This code serves a basic HTML web page hosted on an ESP32 with some text content.

/*  
  Rui Santos & Sara Santos - Random Nerd Tutorials
  https://RandomNerdTutorials.com/esp-idf-esp32-web-server/
*/
#include <stdio.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"
#include "esp_netif.h"
#include "esp_http_server.h"
#include "sdkconfig.h"

#define MY_ESP_WIFI_SSID      CONFIG_ESP_WIFI_SSID
#define MY_ESP_WIFI_PASS      CONFIG_ESP_WIFI_PASSWORD

static const char *TAG = "web_server";

// HTML web page to serve 
static const char *html_page = 
    "<!DOCTYPE html>"
    "<html>"
    "<head>"
    "<title>ESP-IDF: ESP32 Web Server</title>"
    "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
    "</head>"
    "<body>"
    "<h1>ESP-IDF: ESP32 Web Server</h1>"
    "<p>Hello from ESP32!</p>"
    "</body>"
    "</html>";

// (Another option) HTML web page to serve (can be defined as a raw string literal for better readability)
/*
static const char *html_page = R"raw(
<!DOCTYPE html>
<html>
<head>
    <title>ESP-IDF: ESP32 Web Server</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
    <h1>ESP-IDF: ESP32 Web Server</h1>
    <p>Hello from ESP32!</p>
</body>
</html>
)raw";*/

// HTTP GET handler for root "/"
static esp_err_t root_get_handler(httpd_req_t *req)
{
    httpd_resp_set_type(req, "text/html");
    httpd_resp_send(req, html_page, HTTPD_RESP_USE_STRLEN);
    return ESP_OK;
}

// Start the HTTP server
static httpd_handle_t start_web_server(void)
{
    httpd_config_t config = HTTPD_DEFAULT_CONFIG();
    httpd_handle_t server = NULL;

    if (httpd_start(&server, &config) == ESP_OK) {
        ESP_LOGI(TAG, "HTTP server started on port %d", config.server_port);
        
        // Register URI handler
        httpd_uri_t uri_get = {
            .uri       = "/",
            .method    = HTTP_GET,
            .handler   = root_get_handler,
            .user_ctx  = NULL
        };
        httpd_register_uri_handler(server, &uri_get);
        
        return server;
    }
    
    ESP_LOGE(TAG, "Failed to start HTTP server");
    return NULL;
}

// Wi-Fi and IP event handler
static void wifi_event_handler(void* arg, esp_event_base_t event_base,
                               int32_t event_id, void* event_data)
{
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
        ESP_LOGI(TAG, "Wi-Fi STA started. Connecting to %s...", MY_ESP_WIFI_SSID);
        esp_wifi_connect();
    } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        ESP_LOGW(TAG, "Wi-Fi disconnected. Retrying connection...");
        esp_wifi_connect();
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
        ESP_LOGI(TAG, "Got IP Address: " IPSTR, IP2STR(&event->ip_info.ip));
        ESP_LOGI(TAG, "Web Server ready! Access at http://" IPSTR "/", IP2STR(&event->ip_info.ip));
    }
}

void app_main(void)
{
    // Initialize NVS
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        ret = nvs_flash_init();
    }
    ESP_ERROR_CHECK(ret);

    // Initialize TCP/IP stack and event loop
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());

    // Create default Wi-Fi STA interface
    esp_netif_create_default_wifi_sta();

    // Initialize Wi-Fi
    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    ESP_ERROR_CHECK(esp_wifi_init(&cfg));

    // Register event handlers
    ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT,
                                                        ESP_EVENT_ANY_ID,
                                                        &wifi_event_handler,
                                                        NULL, NULL));
    ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT,
                                                        IP_EVENT_STA_GOT_IP,
                                                        &wifi_event_handler,
                                                        NULL, NULL));

    // Configure Wi-Fi STA
    wifi_config_t wifi_config = {
        .sta = {
            .ssid = MY_ESP_WIFI_SSID,
            .password = MY_ESP_WIFI_PASS,
        },
    };
    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
    ESP_ERROR_CHECK(esp_wifi_start());

    // Start the web server (it will be ready once IP is assigned)
    httpd_handle_t server = start_web_server();
    if (server) {
        ESP_LOGI(TAG, "Web Server initialized. Waiting for Wi-Fi connection...");
    }
}

View raw code

How the Code Works

In this section, we’ll take a look at the code to see how it works.

Libraries

We start by including the required libraries:

• stdio.h – the standard C library will be used for the printf function that prints the debugging information in the serial monitor;
• string.h – the standard C library used for string manipulation;
• FreeRTOS.h – provides the core FreeRTOS types and functions;
• task.h – allows to use task management;
• esp_system.h – system level functions like restart and hardware info;
• esp_wifi.h – library for Wi-Fi configuration (station and access point modes and connection options);
• esp_event.h – handles events like Wi-Fi status changes;
• esp_log.h – offers a framework to format log messages in the serial monitor for debugging;
• nvs_flash.h – stores key-value data in non-volatile storage (NVS) memory persistently ;
• esp_netif.h – provides the network interface;
• esp_http_server.h – library to create an HTTP server and handle HTTP requests/responses;
• sdkconfig.h – includes the project’s configuration file.

#include <stdio.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"
#include "esp_netif.h"
#include "esp_http_server.h"
#include "sdkconfig.h"

Wi-Fi Configuration

These variables will be retrieved from the menuconfig options as described in the previous section “Create the Wi-Fi Config Options File – Kconfig.projbuild“.

#define MY_ESP_WIFI_SSID      CONFIG_ESP_WIFI_SSID
#define MY_ESP_WIFI_PASS      CONFIG_ESP_WIFI_PASSWORD

Logging Tag

The “web_server” prefix will be used to log all the debugging messages.

static const char *TAG = "web_server";

HTML Web Page

This is the HTML web page that will be sent to the connected client. You can either do as shown below where each line is inside quotation marks.

static const char *html_page = 
    "<!DOCTYPE html>"
    "<html>"
    "<head>"
    "<title>ESP-IDF: ESP32 Web Server</title>"
    "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
    "</head>"
    "<body>"
    "<h1>ESP-IDF: ESP32 Web Server</h1>"
    "<p>Hello from ESP32!</p>"
    "</body>"
    "</html>";

Or you can use the R”raw( to have the full web page inside without quotation marks.

static const char *html_page = R"raw(
<!DOCTYPE html>
<html>
<head>
    <title>ESP-IDF: ESP32 Web Server</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
    <h1>ESP-IDF: ESP32 Web Server</h1>
    <p>Hello from ESP32!</p>
</body>
</html>
)raw";

HTTP GET Handler

This function (root_get_handler) runs every time a client enters the ESP IP address in the browser (this makes a request to the root / web page). The httpd_resp_set_type function tells the browser that the file to be sent is in HTML format. Finally, the httpd_resp_send sends the html_page to the client.

static esp_err_t root_get_handler(httpd_req_t *req)
{
    httpd_resp_set_type(req, "text/html");
    httpd_resp_send(req, html_page, HTTPD_RESP_USE_STRLEN);
    return ESP_OK;
}

Start the HTTP Web Server

The start_web_server() function starts by configuring the server (uses the default port 80):

httpd_config_t config = HTTPD_DEFAULT_CONFIG();
httpd_handle_t server = NULL;

The httpd_start(&server, &config) starts the actual HTTP web server and starts listening to connections on port 80, so a client can connect to it. Then, we register the route, so when someone opens the / URL, it runs the root_get_handler() function that sends the html_page variable defined earlier.

if (httpd_start(&server, &config) == ESP_OK) {
    ESP_LOGI(TAG, "HTTP server started on port %d", config.server_port);
        
    // Register URI handler
    httpd_uri_t uri_get = {
        .uri       = "/",
        .method    = HTTP_GET,
        .handler   = root_get_handler,
        .user_ctx  = NULL
    };
    httpd_register_uri_handler(server, &uri_get);
        
    return server;
}

If it fails to start the HTTP web server, it prints a failed message.

ESP_LOGE(TAG, "Failed to start HTTP server");

Wi-Fi and IP event handler

This callback function runs when an event related to Wi-Fi happens.

static void wifi_event_handler(void* arg, esp_event_base_t event_base,
                               int32_t event_id, void* event_data)
{
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
        ESP_LOGI(TAG, "Wi-Fi STA started. Connecting to %s...", MY_ESP_WIFI_SSID);
        esp_wifi_connect();
    } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        ESP_LOGW(TAG, "Wi-Fi disconnected. Retrying connection...");
        esp_wifi_connect();
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
        ESP_LOGI(TAG, "Got IP Address: " IPSTR, IP2STR(&event->ip_info.ip));
        ESP_LOGI(TAG, "Web Server ready! Access at http://" IPSTR "/", IP2STR(&event->ip_info.ip));
    }
}

For example, when the ESP32 gets assigned an IP address, it triggers the IP_EVENT that prints this message in the Serial Monitor:

ESP_LOGI(TAG, "Got IP Address: " IPSTR, IP2STR(&event->ip_info.ip));
ESP_LOGI(TAG, "Web Server ready! Access at http://" IPSTR "/", IP2STR(&event->ip_info.ip));

app_main(void)

When creating an ESP-IDF project, the app_main function will always be called to run. This function is where you need to write your code for any ESP-IDF applications; it is the equivalent of the setup() in Arduino programming. When the ESP32 boots, the ESP-IDF framework calls app_main.

void app_main(void)
{
    // your code goes here
}

In the app_main(void) function, you start by initializing the NVS (storage)—the ESP32 stores the Wi-Fi settings in flash.

esp_err_t ret = nvs_flash_init();
if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
    ESP_ERROR_CHECK(nvs_flash_erase());
    ret = nvs_flash_init();
}
ESP_ERROR_CHECK(ret);

Then, initialize the TCP/IP stack required for network functions usage.

ESP_ERROR_CHECK(esp_netif_init());
ESP_ERROR_CHECK(esp_event_loop_create_default());

Start the Wi-Fi interface in station mode, so the ESP32 can connect to the router. It also initializes the Wi-Fi functionalities.

esp_netif_create_default_wifi_sta();

wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_wifi_init(&cfg));

Assign the Wi-Fi events, so that when the ESP32 establishes a Wi-Fi connection or gets an IP address, it runs the corresponding Wi-Fi event.

ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT,
                                                    ESP_EVENT_ANY_ID,
                                                    &wifi_event_handler,
                                                    NULL, NULL));
ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT,
                                                    IP_EVENT_STA_GOT_IP,
                                                    &wifi_event_handler,
                                                    NULL, NULL));

These next few lines set the SSID and password so the ESP32 can connect to your network, set the ESP in station mode, and start Wi-Fi.

wifi_config_t wifi_config = {
    .sta = {
        .ssid = MY_ESP_WIFI_SSID,
        .password = MY_ESP_WIFI_PASS,
    },
};
ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
ESP_ERROR_CHECK(esp_wifi_start());

Finally, start the web server:

httpd_handle_t server = start_web_server();
if (server) {
    ESP_LOGI(TAG, "Web Server initialized. Waiting for Wi-Fi connection...");
}

Build and Flash Code to the ESP32 Board

To build and flash ESP-IDF code to the ESP32, you always need to follow this procedure. You need to select the flash method (UART), the COM port number, the target device (ESP32), build the code, and finally, flash it to the board. All these commands are available in the bottom menu bar of VS Code.

Make sure all your options are correct (they may already be properly configured if you used the project wizard).

However, if your setup is not correct, follow the next instructions to ensure everything is set up correctly. First, click the “Star” icon and select the flash method as UART.

While the ESP32 board is connected to your computer, click the COM Port (plug icon) and select the correct port number that refers to your ESP32.

You also need to select the target device. Click on the chip icon at the bottom bar. In my case, I have an ESP32 with the esp32s3 chip.

For this board, I also need to select the configuration: ESP32-S chip (via builtin USB-JTAG).

Finally, your command bar at the bottom of VS Code should have similar options selected.

Now, you can build the project by clicking the wrench icon (Build Project) as shown in the image below.

The first time you build a project, it usually takes a bit more time. Once completed, it should print a similar message in the Terminal menu and show a “Build Successfully” message.

This is the final step. You can now flash the ESP-IDF project to the ESP32 by clicking the “Flash Device” button (thunder icon).

Depending on your board, you might need to hold down the on-board BOOT button on your ESP32 to put it into flashing mode. Once the process is completed, it will pop-up a info message saying “Flash Done“.

Demonstration

If you followed all the steps, the example should be running successfully on your board. Open your Terminal window — click the “Monitor Device” tool that is illustrated with a screen icon.

The ESP32 connects to Wi-Fi and prints its IP address on the Serial Monitor. Copy that IP address because you need it to access the ESP32 web server.

Note: if nothing shows up on the Serial Monitor, press the ESP32 “EN” button (ENABLE/RESET button next to the microUSB port).

To access your web server in your local netowrk, open your browser and type the ESP32 IP address. You should see a similar web page being served by your ESP32.

Wrapping Up

In this tutorial, you learned how to program the ESP32 with the ESP-IDF framework using VS Code to run a simple web server that serves HTML pages to a client connected to your local network.

In future tutorials, we’ll expand this project to created buttons to control the ESP32 GPIOs, and add fields to show the state of GPIOs or readings from sensors connected to the ESP32.

You might find it helpful to read other ESP-IDF guides:

• ESP-IDF: ESP32 Blink LED Example (VS Code)
• ESP-IDF: ESP32 GPIO PWM with LEDC (Control LED Brightness)
• ESP-IDF: ESP32 GPIO – Read Analog Input (ADC – Analog to Digital Converter)

Meanwhile, you can check our ESP32 resources (with Arduino IDE) to learn more about the ESP32 board:

• Learn ESP32 with Arduino IDE (eBook)
• ESP-IDF: ESP32 Projects, Tutorials and Guides

Thanks for reading.

To learn more about creating ESP32 web servers (but using Arduino Core), we recommend exploring our eBook: Build Web Servers with ESP32 and ESP8266 (3rd Edition).