Компонент HTTP Server (esp_http_server) предоставляет возможность запуска облегченного web-сервера на ESP32-C3 (или другом микроконтроллере Espressif, на котором реализован сетевой интерфейс). Здесь приведен перевод оригинальной документации [1].

Выполните следующие шаги для использования API-функций, предоставляемых HTTP Server:

httpd_start(): создаст экземпляр сервера HTTP, выделит для этого память/ресурсы в зависимости от указанной конфигурации, и вернет дескриптор экземпляра сервера. Сервер содержит в себе две составляющие: сокет прослушивания (listening socket, TCP) для HTTP-трафика, и сокет управления (control socket, UDP) для управляющих сигналов, обработка которых осуществляется по принципу round robin в цикле задачи сервера.

Приоритет задачи и размер стека конфигурируется в момент создания экземпляра сервера путем передачи в функцию httpd_start() структуры httpd_config_t. Трафик TCP парсится как HTTP-запросы, и в зависимости от выданного клиентом запрошенной ссылки URI, программист регистрирует необходимые обработчики, вовлекаемые для отправки обратно пакетов HTTP-ответа.

httpd_stop(): остановит сервер по указанному дескриптору и освободит связанные с ним память и ресурсы. Это блокирующая функция, которая сначала посылает сигнал остановки (halt) задаче сервера, и затем ждет завершения этой задачи. При остановке задача сервера закрывает все открытые сетевые соединения, удаляет зарегистрированные URI-обработчики и сбрасывает данные контекста всех сессий.

httpd_register_uri_handler(): URI-обработчик, зарегистрированный путем передачи объекта типа структуры httpd_uri_t, в полях которой находится имя ссылки (uri name), тип метода (например HTTP_GET/HTTP_POST/HTTP_PUT и т. п.), указатель на функцию типа esp_err_t *handler (httpd_req_t *req) и указатель user_ctx на данные контекста пользователя (user context data).

Примечание: API-функции сервера HTTP не являются потокобезопасными (not thread-safe). Если требуется безопасность для потока (thread safety), то это должно обеспечиваться на уровне приложения для обеспечения правильной синхронизации между несколькими потоками.

Примеры приложений:

protocols/http_server/simple - демонстрирует, как обрабатывать контент произвольной длины, читать заголовки запроса и параметры URL-запроса, и как устанавливать заголовки ответа.

protocols/http_server/advanced_tests - демонстрирует, как использовать HTTP-сервер для продвинутого тестирования.

Persistent Connections. HTTP-сервер обеспечивает постоянные соединения (persistent connections), позволяющие повторно использовать то же самое соединение (сессию) для нескольких передач, с обеспечением поддержки специфичных данных контекста для сессии. Данные контекста могут выделяться динамически обработчиком, в этом случае требуется пользовательская функция для обеспечения освобождения этих данных, когда соединение/сессия закрывается.

// Ваша структура контекста
typedef struct {
    char user_id[32];
    int counter;
    void *temp_buffer; // динамически выделенный буфер
} my_session_ctx_t;

// Функция очистки - её вызовет сервер при закрытии сокета
void free_session_ctx(void *ctx) {
    my_session_ctx_t *my_ctx = (my_session_ctx_t *)ctx;
    if (my_ctx->temp_buffer) {
        free(my_ctx->temp_buffer); // освобождаем вложенный буфер
    }
    free(my_ctx); // освобождаем саму структуру
}

// В обработчике запроса
esp_err_t my_handler(httpd_req_t *req) {
    // Выделяем память под контекст для этого соединения (если ещё не выделена)
    my_session_ctx_t *ctx = httpd_session_ctx_get(req);
    if (ctx == NULL) {
        ctx = calloc(1, sizeof(my_session_ctx_t));
        ctx->temp_buffer = malloc(1024);
        // Устанавливаем контекст и указываем, как его освобождать
        httpd_session_ctx_set(req, ctx, free_session_ctx);
    }
    // ... работаем с ctx ...
    return ESP_OK;
}

Пример постоянных соединений:

/* Пользовательская функция для освобождения контекста */
void free_ctx_func(void *ctx)
{
   /* Тут могут быть и другие варианты освобождения выделенных ресурсов */
   free(ctx);
}

esp_err_t adder_post_handler(httpd_req_t *req)
{
   /* Создание контекста сессии, если это еще не сделано */
   if (! req->sess_ctx) {
      // Указатель на данные пользователя:
      req->sess_ctx = malloc(sizeof(ANY_DATA_TYPE));
      // Функция для освобождения данных контекста:
      req->free_ctx = free_ctx_func;
   }

   /* Доступ к данным контекста */
   ANY_DATA_TYPE *ctx_data = (ANY_DATA_TYPE *)req->sess_ctx;

   /* Ответ на запрос req: */
   ...............
   ...............
   ...............

   return ESP_OK;
}

Просмотрите пример в коде protocols/http_server/persistent_sockets. Этот пример демонстрирует, как настроить и использовать HTTP-сервер с поддержкой persistent sockets, позволяя иметь для каждого клиента независимые сессии или контексты.

[WebSocket Server]

Компонент HTTP-сервера предоставляет поддержку WebSocket [2]. Фича WebSocket может быть разрешена в menuconfig опцией CONFIG_HTTPD_WS_SUPPORT.

Проект protocols/http_server/ws_echo_server демонстрирует, как создавать WebSocket echo-сервер с использованием HTTP-сервера, который стартует в локально сети и требует для взаимодействия WebSocket-клиента, отправляя обратно принятые кадры WebSocket.

WebSocket Pre-Handshake Callback. Компонент HTTP-сервера предоставляет функцию обратного вызова, которая вызывается перед рукопожатием (pre-handshake callback) для конечных точек WebSocket. Этот callback запускается перед обработкой WebSocket handshake - в этот момент соединение все еще является соединением HTTP, и пока не прошло апгрейд до протокола WebSocket.

Pre-handshake callback может использоваться для аутентификации, авторизации, или для других проверок. Если callback возвратил ESP_OK, то произойдет переход к WebSocket handshake. Если callback возвратил любое другое значение, то handshake обрывается (aborted), и соединение будет закрыто.

Чтобы использовать WebSocket pre-handshake callback, вы должны разрешить опцию CONFIG_HTTPD_WS_PRE_HANDSHAKE_CB_SUPPORT в конфигурации вашего проекта.

WebSocket Post-Handshake Callback. Подобно pre-handshake callback, компонент HTTP-сервера также предоставляет функцию обратного вызова, вызываемую после рукопожатия (post-handshake callback) для конечных точек WebSocket. Этот callback запускается после того, как был обработан WebSocket.

В этой точке соединение было продвинуто (upgraded) до состояния WebSocket, и сервер ответил WebSocket handshake response. Этот post handshake callback может использоваться для лога, отправки начальных сообщений, или другие задачи настройки.

Для использования WebSocket post-handshake callback вы должны разрешить опцию CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT в конфигурации вашего проекта.

static esp_err_t ws_auth_handler(httpd_req_t *req)
{
    // Здесь находится ваша логика аутентификации. Возвращенное
    // значение ESP_OK разрешает handshake, другое значение
    // отменяет соединение.
    return ESP_OK;
}

// Регистрация обработчика WebSocket URI с pre-handshake аутентификацией:
static const httpd_uri_t ws = {
    .uri        = "/ws",
    .method     = HTTP_GET,
    .handler    = handler,   // Ваш обработчик данных WebSocket
    .user_ctx   = NULL,
    .is_websocket = true,
    .ws_pre_handshake_cb = ws_auth_handler // Установка pre-handshake callback
};

// Регистрация обработчика после старта сервера:
httpd_register_uri_handler(server, &ws);

Event Handling. ESP HTTP-сервер поддерживает различные события (events), для которых библиотека Event Loop может вызвать обработчик, когда возникнет определенное событие. Обработчик необходимо зарегистрировать с помощью функции esp_event_handler_register(). Это помогает в обработке событий (event handling) для ESP HTTP server.

Перечисление esp_http_server_event_id_t описывает все события, которые могут произойти для ESP HTTP server.

Ожидаемые типы данных для различных событий ESP HTTP server в цикле событий (event loop):

HTTP_SERVER_EVENT_ERROR : httpd_err_code_t
HTTP_SERVER_EVENT_START : NULL
HTTP_SERVER_EVENT_ON_CONNECTED : int
HTTP_SERVER_EVENT_ON_HEADER : int
HTTP_SERVER_EVENT_HEADERS_SENT : int
HTTP_SERVER_EVENT_ON_DATA : esp_http_server_event_data
HTTP_SERVER_EVENT_SENT_DATA : esp_http_server_event_data
HTTP_SERVER_EVENT_DISCONNECTED : int
HTTP_SERVER_EVENT_STOP : NULL

File Serving. Пример protocols/http_server/file_serving демонстрирует, как создать простой файловый HTTP-сервер, с функционалом выгрузки (upload) и загрузки (download).

Captive Portal. Пример protocols/http_server/captive_portal демонстрирует два метода создания captive portal, который направляет пользователей на страницу аутентификации перед предоставлением доступа к контенту, с использованием либо запросов DNS и перенаправления запросов HTTP, либо современный метод, применяющий поле в предложении DHCP.

Asynchronous Handlers. Пример protocols/http_server/async_handlers демонстрирует, как обработать несколько долго работающих одновременных запросов на HTTP-сервере, с использованием различных URI для асинхронных запросов (asynchronous requests), быстрых запросов (quick requests) и страницы index.

URI Handlers. HTTP-сервер позволяет вам зарегистрировать обработчики ссылок (URI handlers) для обработки различных запросов HTTP. Каждый URI-обработчик связывается с определенным URI и методом HTTP (GET, POST, и т. п.). Функция-обработчик вызывается при каждом получении запроса, соответствующего URI и методу.

Функция обработчика должна возвращать значение типа esp_err_t.

esp_err_t my_uri_handler(httpd_req_t *req)
{
    // Обработка запроса
    // ...

    // Возврат ESP_OK, если запрос был успешно обработан
    return ESP_OK;

    // Возврат кода ошибки для закрытия соединения
    // return ESP_FAIL;
}

void register_uri_handlers(httpd_handle_t server)
{
    httpd_uri_t my_uri = {
        .uri       = "/my_uri",
        .method    = HTTP_GET,
        .handler   = my_uri_handler,
        .user_ctx  = NULL
    };

    httpd_register_uri_handler(server, &my_uri);
}

В этом примере функция my_uri_handler обрабатывает запросы для URI-ссылки /my_uri. Если обработчик возвратил ESP_OK, то соединение остается открытым. Если же будет возвращено любое другое значение, то соединение закрывается. Такое поведение позволяет приложению управлять закрытием соединения на основе определенных событий или условий.

[Справочник API]

Декларация функций содержится в заголовке components/esp_http_server/include/esp_http_server.h, который подключается директивой:

#include "esp_http_server.h"

Этот заголовочный файл описывает часть API, предоставляемую компонентом esp_http_server. Для декларации, что ваш компонент (например приложение, которое тоже является компонентом) зависит от esp_http_server, добавьте следующее в свой CMakeLists.txt:

REQUIRES esp_http_server

или:

PRIV_REQUIRES esp_http_server

В следующей таблице приведено общее описание функций. Полное описание API-функций и используемых типов, макросов, перечислений и структур см. в документации [1].

[Ссылки]

1. ESP-IDF HTTP Server site:espressif.com.
2. Отправка запросов WebSocket.