HTTP(S) Server

Management of HTTP/HTTPS endpoints and server tuning. More...

Functions
esp_err_t	eif_set_server_config_https (const httpd_ssl_config_t *const server_config)
	Tune the HTTPS server settings. More...
esp_err_t	eif_set_server_config_http (const httpd_config_t *const server_config)
	Tune the HTTP server settings. More...
esp_err_t	eif_set_uri_handlers (const httpd_uri_t *const uri_handlers, size_t uri_handlers_count)
	Register custom URI handlers (endpoints). More...

Detailed Description

This module allows registering custom routes and fine-tuning server. The framework automatically manages the server lifecycle, starting it only when a valid IP is obtained and stopping it upon disconnection.

Note

To enable or disable encryption (TLS/HTTPS), use the CONFIG_EIF_ENABLE_TLS flag from Kconfig via idf.py menuconfig. Depending on this setting, the server will operate in either HTTP or HTTPS mode, and the corresponding configuration functions will be available.

If you frequently intersect between HTTP and HTTPS during development and need custom server settings, you can use the following construct:

#include <esp_err.h>
#include <esp_https_server.h>
#include <esp_iot_framework_core.h>
#include <esp_iot_framework_device.h>
 
void app_main(void) {
    ESP_ERROR_CHECK(eif_core_initialize());
    ESP_ERROR_CHECK(eif_device_initialize());
    ESP_ERROR_CHECK(eif_nvs_initialize());
 
    #ifdef CONFIG_EIF_ENABLE_TLS
        // Creating default server settings
        httpd_ssl_config_t config = HTTPD_SSL_CONFIG_DEFAULT();
        // Set custom settings unique to this type.
        config.httpd.server_port = 443;
        config.port_secure = 443;
        config.httpd.stack_size = 10240;
        // Selecting general settings
        httpd_config_t *cfg_httpd = &config.httpd;
    #else
        // Creating default server settings
        httpd_config_t config = HTTPD_DEFAULT_CONFIG();
        // Set custom settings unique to this type.
        config.server_port = 80;
        config.stack_size = 4096;
        // Selecting general settings
        httpd_config_t *cfg_httpd = &config;
    #endif
 
    // Changing general settings
    cfg_httpd->max_open_sockets = 4;
    cfg_httpd->recv_wait_timeout = 8;
    cfg_httpd->send_wait_timeout = 8;
    cfg_httpd->lru_purge_enable = true;
 
    #ifdef CONFIG_EIF_ENABLE_TLS
        ESP_ERROR_CHECK(eif_set_server_config_https(&config));
    #else
        ESP_ERROR_CHECK(eif_set_server_config_http(&config));
    #endif
 
    // Further code...
}

Function Documentation

eif_set_server_config_https()

esp_err_t eif_set_server_config_https

(

const httpd_ssl_config_t *const

server_config

)

Note

Only available if the Kconfig option CONFIG_EIF_ENABLE_TLS is enabled.

Overrides default HTTPS server parameters (ports, stack size, timeouts, etc.). You can also change the server's HTTP settings via server_config. The framework creates an internal copy of the structure, so the original data's lifecycle no longer matters after the call.

Note

This function must be called after eif_initialize() but before eif_wifi_initialize().

Warning

The framework handles TLS credentials internally. To ensure stability and prevent memory conflicts, the following fields in server_config are explicitly overwritten with the following values:

• cacert_pem - NULL
• prvtkey_pem - NULL
• cacert_len - 0
• prvtkey_len - 0
• transport_mode - HTTPD_SSL_TRANSPORT_SECURE
• session_tickets - false
• httpd.max_uri_handlers - calculated automatically

Parameters

server_config

Pointer to server configuration. Use HTTPD_SSL_CONFIG_DEFAULT() as base.

Returns

• ESP_OK: Configuration applied.
• ESP_ERR_INVALID_ARG: If server_config is NULL.

Example of use:

#include <esp_err.h>
#include <esp_https_server.h>
#include <esp_iot_framework_core.h>
#include <esp_iot_framework_device.h>
 
void app_main(void) {
    ESP_ERROR_CHECK(eif_core_initialize());
    ESP_ERROR_CHECK(eif_device_initialize());
    ESP_ERROR_CHECK(eif_nvs_initialize());
 
    // Creating default server settings
    httpd_ssl_config_t config = HTTPD_SSL_CONFIG_DEFAULT();
    // Changing server settings
    config.httpd.stack_size = 10240;
    config.httpd.server_port = 443;
    config.port_secure = 443;
 
    ESP_ERROR_CHECK(eif_set_server_config_https(&config));
 
    // Further code...
}

eif_set_server_config_http()

esp_err_t eif_set_server_config_http

(

const httpd_config_t *const

server_config

)

Note

Only available if the Kconfig option CONFIG_EIF_ENABLE_TLS is disabled.

Overrides default HTTP server parameters (ports, stack size, priority, timeouts, etc.). You can also change the server's HTTP settings via server_config. The framework creates an internal copy of the structure, so the original data's lifecycle no longer matters after the call.

Note

This function must be called after eif_initialize() but before eif_wifi_initialize().

Warning

To ensure stability and prevent memory conflicts, the following fields in server_config are explicitly overwritten with the following values:

• max_uri_handlers - calculated automatically

Parameters

server_config

Pointer to server configuration. Use HTTPD_DEFAULT_CONFIG() as base.

Returns

• ESP_OK: Configuration applied.
• ESP_ERR_INVALID_ARG: If server_config is NULL.

Example of use:

#include <esp_err.h>
#include <esp_http_server.h>
#include <esp_iot_framework_core.h>
#include <esp_iot_framework_device.h>
 
void app_main(void) {
    ESP_ERROR_CHECK(eif_core_initialize());
    ESP_ERROR_CHECK(eif_device_initialize());
    ESP_ERROR_CHECK(eif_nvs_initialize());
 
    // Creating default server settings
    httpd_config_t config = HTTPD_DEFAULT_CONFIG();
    // Changing server settings
    config.max_open_sockets = 3;
    config.recv_wait_timeout = 15;
    config.send_wait_timeout = 15;
    config.server_port = 80;
 
    ESP_ERROR_CHECK(eif_set_server_config_http(&config));
 
    // Further code...
}

eif_set_uri_handlers()

esp_err_t eif_set_uri_handlers	(	const httpd_uri_t *const	uri_handlers,
		size_t	uri_handlers_count
	)

Note

This function must be called after eif_initialize() but before eif_wifi_initialize().

Passes application-specific routes (e.g., /api/data, /status) to the framework. The passed handlers are automatically registered in the server at startup. The framework creates an internal copy of the structure, so the original data's lifecycle no longer matters after the call. When the function is called again, the handlers saved in advance will be deleted.

Warning

The handler array length must be equal to uri_handlers_count. If the count exceeds the actual array length, a Buffer Overread will occur. If the count is less than the actual length, Truncation will occur (only the first uri_handlers_count elements will be registered).
If the array is accessible by value at the function call site, you can use the following code to automatically calculate the length:

sizeof(array) / sizeof(array[0])

Parameters

uri_handlers	Array of URI structures defining paths and callbacks.
uri_handlers_count	Number of elements in the array.

Returns

• ESP_OK: Handlers stored successfully.
• ESP_ERR_INVALID_ARG: If uri_handlers is NULL.
• ESP_ERR_NO_MEM: Failed to allocate memory for the internal copy.

Example of use:

#include <esp_err.h>
#include <esp_log.h>
#include <esp_http_server.h>
#include <esp_iot_framework_core.h>
#include <esp_iot_framework_device.h>
 
esp_err_t get_handler(httpd_req_t *req) {
    const char *resp = "Hello from esp_iot_framework_device!";
    httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
    return ESP_OK;
}
 
esp_err_t post_handler(httpd_req_t *req) {
    ESP_LOGI("post_handler", "Data received!");
    httpd_resp_send(req, "OK", HTTPD_RESP_USE_STRLEN);
    return ESP_OK;
}
 
static const httpd_uri_t my_uris[] = {
    { .uri = "/hello", .method = HTTP_GET,  .handler = get_handler },
    { .uri = "/data",  .method = HTTP_POST, .handler = post_handler }
};
 
void app_main(void) {
    ESP_ERROR_CHECK(eif_core_initialize());
    ESP_ERROR_CHECK(eif_device_initialize());
    ESP_ERROR_CHECK(eif_nvs_initialize());
    ESP_ERROR_CHECK(eif_set_uri_handlers(my_uris, 2));
 
    // Further code...
}