ESP32 CAM: Live Streaming Web Server With ESP-IDF

Oct 29, 2025 by Jhon Lennon 50 views

Hey guys! Today, let's dive into building a live streaming web server using the ESP32 CAM and ESP-IDF. This project is super cool because it allows you to stream video from your ESP32 CAM directly to a web browser. Perfect for home monitoring, DIY security systems, or just tinkering around! Let's break down each part and get you streaming in no time.

Setting Up Your Environment

Before we even touch the code, let's get our environment set up. Trust me, a smooth setup saves you a ton of headaches later. Here’s what you need:

ESP-IDF Toolchain:
- First off, you'll need the ESP-IDF (Espressif IoT Development Framework). Think of this as your toolkit for all things ESP32. Espressif provides a detailed guide on how to install it for different operating systems. You can find the official installation guide on the Espressif website. Make sure you follow the instructions closely, as getting this right is crucial for compiling and flashing your code.
ESP32 CAM Board:
- Of course, you need an ESP32 CAM board. These are widely available online from various retailers. When you get your board, double-check the pinout. Different manufacturers might have slight variations. Knowing the pinout will be essential when we configure the code later.
USB to Serial Converter:
- You'll also need a USB to serial converter to flash the code onto the ESP32 CAM. These converters allow your computer to communicate with the ESP32 via the UART interface. Make sure the converter you choose supports 3.3V logic levels, as the ESP32 operates at 3.3V, and using a 5V signal can damage the board.
Wiring:
- Connect the USB to serial converter to the ESP32 CAM. Typically, you'll need to connect the TX (transmit) pin of the converter to the RX (receive) pin of the ESP32 CAM, the RX pin of the converter to the TX pin of the ESP32 CAM, and the ground pins together. You'll also need to provide power to the ESP32 CAM, usually through the 5V and ground pins. Refer to your ESP32 CAM's specific documentation for the correct pinout. And remember, cross-check everything to avoid fried components! We don't want any magic smoke escaping.
Software:
- Code Editor: Grab a decent code editor. VS Code with the ESP-IDF extension is a popular choice, offering great support for ESP-IDF projects. It provides features like code completion, debugging, and integration with the ESP-IDF build system.
- Terminal: You'll need a terminal to navigate to your project directory, compile the code, and flash it to the ESP32 CAM. On Windows, you can use the ESP-IDF command prompt provided during the ESP-IDF installation. On macOS and Linux, any terminal will do.
Verify Installation:
- Once everything is installed, verify that the ESP-IDF is correctly set up by running one of the example projects. This will confirm that the toolchain is working and that you can compile and flash code to your ESP32 CAM. This step can save you a lot of frustration down the road.

Diving into the Code

Alright, with the environment ready, let's dive into the code. This is where the magic happens! We’ll walk through the key components to get that live stream flowing.

Project Setup:
- Create a new project directory for your ESP32 CAM web server. Inside this directory, create the necessary files for your ESP-IDF project, including the main source file (main.c or main.cpp), a component file (if needed), and the CMakeLists.txt file, which is used by CMake to build the project.
Include Headers:
- In your main source file, include the necessary headers for the ESP32 CAM, web server, and camera functionality. These headers provide access to the functions and data structures needed to control the camera, configure the Wi-Fi, and handle HTTP requests.
```
#include <stdio.h>
#include "esp_wifi.h"
#include "esp_system.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"
#include "esp_http_server.h"
#include "camera_fb.h"
#include "camera.h"
#include "dl_lib.h"
```
Wi-Fi Configuration:
- Configure the Wi-Fi settings to connect the ESP32 CAM to your local network. You'll need to provide the SSID (network name) and password for your Wi-Fi network. This will allow the ESP32 CAM to communicate with other devices on the network, including the web browser that will display the live stream.
```
#define WIFI_SSID      "YOUR_WIFI_SSID"
#define WIFI_PASS      "YOUR_WIFI_PASSWORD"
```
- Initialize the Wi-Fi using the esp_wifi_init and esp_wifi_start functions. You'll also need to set the Wi-Fi mode to station mode, which allows the ESP32 CAM to connect to an existing Wi-Fi network.

Camera Initialization:

Initialize the ESP32 CAM using the camera driver. This involves configuring the camera's resolution, pixel format, and other settings. The camera driver provides functions for capturing frames from the camera and accessing the image data.

camera_config_t camera_config = {
    .pin_pwdn  = 32,
    .pin_reset = -1, //software reset will be performed
    .pin_xclk = 0,
    .pin_sccb_sda = 26,
    .pin_sccb_scl = 27,
    .pin_d7 = 35,
    .pin_d6 = 34,
    .pin_d5 = 39,
    .pin_d4 = 36,
    .pin_d3 = 21,
    .pin_d2 = 19,
    .pin_vsync = 5,
    .pin_href = 18,
    .pin_pclk = 23,

    .xclk_freq_hz = 20000000,
    .ledc_timer   = LEDC_TIMER_0,
    .ledc_channel = LEDC_CHANNEL_0,

    .pixel_format = PIXFORMAT_JPEG, //YUV422,GRAYSCALE,RGB565,JPEG
    .frame_size   = FRAMESIZE_UXGA,    //QQVGA-UXGA Do not use sizes above QVGA when not JPEG

    .jpeg_quality = 10, //0-63 lower number means higher quality
    .fb_count     = 2       //if more than one, i2s runs in continuous mode. Use only with JPEG
};

esp_err_t camera_init() {
    //power up the camera if PWDN pin is defined
    if (camera_config.pin_pwdn != -1) {
        gpio_set_direction(camera_config.pin_pwdn, GPIO_MODE_OUTPUT);
        gpio_set_level(camera_config.pin_pwdn, 0);
    }

    //initialize the camera
    esp_err_t err = esp_camera_init(&camera_config);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "Camera init failed with error 0x%x", err);
        return err;
    }

    return ESP_OK;
}

Web Server Setup:

Set up an HTTP server on the ESP32 CAM to handle incoming requests from web browsers. The HTTP server will listen for connections on a specific port (e.g., port 80) and respond to requests for the live video stream.

httpd_handle_t server = NULL;

static esp_err_t stream_handler(httpd_req_t *req){
    camera_fb_t * fb = NULL;
    esp_err_t res = ESP_OK;
    size_t _jpg_buf_len = 0;
    uint8_t * _jpg_buf = NULL;
    char * part_buf[64];

    res = httpd_resp_set_type(req, "multipart/x-mixed-replace;boundary=frame");
    if(res != ESP_OK){
        return res;
    }

    while(true){
        fb = esp_camera_fb_get();
        if (!fb) {
            ESP_LOGE(TAG, "Camera capture failed");
            res = ESP_FAIL;
        } else {
            if(fb->width > 400){
                if(fb->format != PIXFORMAT_JPEG){
                    bool jpeg_converted = frame2jpg(fb, 80, &_jpg_buf, &_jpg_buf_len);
                    esp_camera_fb_return(fb);
                    fb = NULL;
                    if(!jpeg_converted){
                        ESP_LOGE(TAG, "JPEG compression failed");
                        res = ESP_FAIL;
                    } else {
                        res = httpd_resp_send_chunk(req, "--frame\r\n", strlen("--frame\r\n"));
                        if(res != ESP_OK){
                            ESP_LOGE(TAG, "Send failed 1");
                        }
                        sprintf((char *)part_buf, "Content-Type: image/jpeg\r\nContent-Len: %d\r\n\r\n", _jpg_buf_len);
                        res = httpd_resp_send_chunk(req, (const char *)part_buf, strlen((char *)part_buf));
                        if(res != ESP_OK){
                            ESP_LOGE(TAG, "Send failed 2");
                        }
                        res = httpd_resp_send_chunk(req, (const char *)_jpg_buf, _jpg_buf_len);
                        if(res != ESP_OK){
                            ESP_LOGE(TAG, "Send failed 3");
                        }
                        res = httpd_resp_send_chunk(req, "\r\n", strlen("\r\n"));
                        if(res != ESP_OK){
                            ESP_LOGE(TAG, "Send failed 4");
                        }
                    }
                } else {
                    res = httpd_resp_send_chunk(req, "--frame\r\n", strlen("--frame\r\n"));
                    if(res != ESP_OK){
                        ESP_LOGE(TAG, "Send failed 1");
                    }
                    sprintf((char *)part_buf, "Content-Type: image/jpeg\r\nContent-Len: %d\r\n\r\n", fb->len);
                    res = httpd_resp_send_chunk(req, (const char *)part_buf, strlen((char *)part_buf));
                    if(res != ESP_OK){
                        ESP_LOGE(TAG, "Send failed 2");
                    }
                    res = httpd_resp_send_chunk(req, (const char *)fb->buf, fb->len);
                    if(res != ESP_OK){
                        ESP_LOGE(TAG, "Send failed 3");
                    }
                    res = httpd_resp_send_chunk(req, "\r\n", strlen("\r\n"));
                    if(res != ESP_OK){
                        ESP_LOGE(TAG, "Send failed 4");
                    }
                }
            } else {
                ESP_LOGI(TAG, "Detected a bad frame\n");
            }
            if(fb){
                esp_camera_fb_return(fb);
                fb = NULL;
                _jpg_buf = NULL;
            }
        }
        if(res != ESP_OK){
            break;
        }
    }
    return res;
}

static esp_err_t index_handler(httpd_req_t *req){
    httpd_resp_set_type(req, "text/html");
    httpd_resp_send(req, (const char *)INDEX_HTML, strlen(INDEX_HTML));
    return ESP_OK;
}

void start_webserver(){
    httpd_config_t config = HTTPD_DEFAULT_CONFIG();

    config.server_port = 80;

    if (httpd_start(&server, &config) == ESP_OK) {
        httpd_uri_t index_uri = {
            .uri       = "/",
            .method    = HTTP_GET,
            .handler   = index_handler,
            .user_ctx  = NULL
        };

        httpd_register_uri_handler(server, &index_uri);

        httpd_uri_t stream_uri = {
            .uri       = "/stream",
            .method    = HTTP_GET,
            .handler   = stream_handler,
            .user_ctx  = NULL
        };
        httpd_register_uri_handler(server, &stream_uri);
    }
}

Create Web Page:
- Make a simple HTML page with an <img> tag that points to the stream endpoint (e.g., <img src="/stream">). This web page will be served by the ESP32 CAM and displayed in the web browser. The <img> tag will continuously request frames from the ESP32 CAM, creating the illusion of a live video stream.
```
<!DOCTYPE html>
<html>
<head>
    <title>ESP32 CAM Live Stream</title>
</head>
<body>
    <img src="/stream" width="640" height="480" />
</body>
</html>
```
Main Application Loop:
- In the main application loop, continuously capture frames from the camera and send them to the web browser as an MJPEG stream. The MJPEG stream is a series of JPEG images sent one after another, with a boundary between each image. The web browser interprets this stream as a video.
Error Handling:
- Implement error handling to gracefully handle any errors that may occur during the Wi-Fi connection, camera initialization, or web server operation. This will help prevent the ESP32 CAM from crashing or becoming unresponsive.

Building and Flashing the Code

Okay, now that we've got the code sorted, let's build and flash it to the ESP32 CAM. This part is like the final assembly line, bringing everything together.

Configure Project:
- Open the ESP-IDF command prompt and navigate to your project directory. Use the idf.py menuconfig command to configure the project settings. This will open a menu-based interface where you can configure various aspects of the project, such as the Wi-Fi SSID and password, camera settings, and other options.
Build the Project:
- Use the idf.py build command to build the project. This will compile the source code, link the necessary libraries, and generate the firmware binary that will be flashed to the ESP32 CAM.
Flash the Firmware:
- Connect the ESP32 CAM to your computer using the USB to serial converter. Make sure the correct serial port is selected in the ESP-IDF command prompt. Use the idf.py flash command to flash the firmware to the ESP32 CAM. This will transfer the compiled code to the ESP32 CAM's flash memory, where it will be stored and executed.
Monitor the Output:
- Use the idf.py monitor command to monitor the output from the ESP32 CAM. This will display the serial output from the ESP32 CAM in the command prompt, allowing you to see the status of the Wi-Fi connection, camera initialization, and web server operation. This is also useful for debugging any issues that may arise.

Testing the Live Stream

Alright, the moment of truth! Let's test that live stream and see if all our hard work paid off. Fingers crossed!

Power Up:
- Power up the ESP32 CAM. Once the ESP32 CAM is powered on, it will attempt to connect to the Wi-Fi network and initialize the camera. You can monitor the progress in the serial output.
Get the IP Address:
- Check the serial monitor for the IP address assigned to the ESP32 CAM by your router. This IP address is what you'll use to access the live stream in your web browser.
Open Web Browser:
- Open a web browser on a computer or mobile device connected to the same Wi-Fi network as the ESP32 CAM. Enter the IP address of the ESP32 CAM in the address bar.
View Live Stream:
- You should see the web page served by the ESP32 CAM, with the live video stream displayed in the <img> tag. If everything is working correctly, you should see a continuous stream of video from the ESP32 CAM.

Troubleshooting Common Issues

Even with the best guides, things can sometimes go sideways. Here are a few common issues and how to tackle them:

Failed to Connect to Wi-Fi:
- Double-check the SSID and password in the code. Make sure they match your Wi-Fi network credentials exactly. Also, ensure that your Wi-Fi network is operating on the 2.4 GHz band, as the ESP32 CAM does not support the 5 GHz band.
Camera Initialization Failed:
- Verify the camera pin connections. Make sure that all the camera pins are correctly connected to the ESP32 CAM. Also, check the camera initialization code for any errors or incorrect settings.
No Image Displayed:
- Check the IP address in the web browser. Make sure that you are entering the correct IP address of the ESP32 CAM. Also, check the web server code for any errors or issues with serving the MJPEG stream.
Choppy Video:
- Reduce the camera resolution or JPEG quality. Higher resolutions and quality settings require more processing power and bandwidth, which can lead to choppy video. Try reducing these settings to improve the frame rate.

Conclusion

And there you have it! You've successfully built a live streaming web server using the ESP32 CAM and ESP-IDF. This project opens up a world of possibilities for DIY security systems, remote monitoring, and more. Keep tinkering, keep experimenting, and most importantly, have fun!