Non-Volatile Storage (NVS)

NVS extension layer for data persistence and configuration profiles. More...

String
Functions for reading and writing strings to NVS with length validation.
esp_err_t	eif_nvs_value_save (const char *const key, const char *const value, size_t min_len, size_t max_len, bool it_can_be_empty)
	Validates string length and writes it to NVS. More...
esp_err_t	eif_nvs_value_load (const char *const key, char *const value_out, size_t max_len)
	Loads a string from NVS into a pre-allocated buffer. More...
esp_err_t	eif_nvs_value_load_malloc (const char *key, char **const value_out, size_t *const value_out_len)
	Dynamically allocates memory and loads a string from NVS. More...

Wi-Fi profile
Functions for reading and writing Wi-Fi network credentials to NVS.
esp_err_t	eif_nvs_wifi_profile_save (uint8_t index, const char *const ssid, const char *const pass)
	Saves Wi-Fi network credentials for a specific profile index. More...
esp_err_t	eif_nvs_wifi_profile_load (uint8_t index, char *const ssid_out, char *const pass_out)
	Loads Wi-Fi network credentials for a specific profile index. More...

HTTP Basic Authentication
Functions for reading, encoding, and writing Basic Auth credentials to NVS.
esp_err_t	eif_nvs_basic_auth_line_save (const unsigned char *const pass)
	Encodes and saves the HTTP Basic Auth credentials to NVS. More...
esp_err_t	eif_nvs_basic_auth_line_load (char *const buf_out)
	Loads the complete HTTP Basic Auth credentials from NVS. More...

Detailed Description

This module provides high-level functions for data persistence in NVS. It enforces runtime buffer protection, boundary validation, and key compatibility checks, completely preventing memory corruption and invalid configurations within the framework.

Note

Before calling any function in this group, eif_core_initialize() and eif_nvs_initialize() must be executed exactly once.

Examples:

#include <esp_err.h>
#include <esp_iot_framework_core.h>
#include <esp_iot_framework_core_ext.h>
 
void app_main(void) {
    ESP_ERROR_CHECK(eif_core_initialize());
    ESP_ERROR_CHECK(eif_nvs_initialize());
   
    // Further code...
}

Function Documentation

eif_nvs_value_save()

esp_err_t eif_nvs_value_save	(	const char *const	key,
		const char *const	value,
		size_t	min_len,
		size_t	max_len,
		bool	it_can_be_empty
	)

Writes the passed string (value) to NVS using the passed key (key). Before writing, the function checks whether the string length is in the range from min_len to max_len.

Checking the length depending on it_can_be_empty (len it is length value):

• If it_can_be_empty is true: ((len >= min_len) && (len <= max_len)) || (len == 0)
• If it_can_be_empty is false: ((len >= min_len) && (len <= max_len))

Parameters

key	NVS storage key (maximum 15 characters). Cannot be NULL.
value	The string to save. Cannot be NULL.
min_len	Minimum allowed length (excluding the null-terminator).
max_len	Maximum allowed length (including the null-terminator).
it_can_be_empty	Allow saving an empty string, bypassing length limits.

Returns

• ESP_OK: String verified, written, and committed successfully.
• ESP_ERR_INVALID_ARG: The pointer key or value is NULL.
• ESP_ERR_INVALID_SIZE: The length of the value is outside the acceptable range.
• ESP_ERR_NVS_*: System errors propagated from nvs_open(), nvs_set_str(), or nvs_commit().

Example of use:

#include <esp_log.h>
#include <esp_err.h>
#include <esp_iot_framework_core_ext.h>
 
#define TAG "CONFIG"
 
void save_dev_name(char *new_name) {
    // Save device name (min 3, max 31 chars, cannot be empty)
    esp_err_t err = eif_nvs_value_save("dev_name", new_name, 3, 32, false);
 
    if (err == ESP_OK) {
        ESP_LOGI(TAG, "Name saved!");
    } else {
        ESP_LOGE(TAG, "Failed to save: %s", esp_err_to_name(err));
    }
}

eif_nvs_value_load()

esp_err_t eif_nvs_value_load	(	const char *const	key,
		char *const	value_out,
		size_t	max_len
	)

Reads the string associated with the key and copies it into value_out. The function prevents buffer overflows by forcing the native read operation to respect the max_len limit, ensuring the output is safely stored within the allocated boundaries.

Note

If ESP_ERR_NVS_NOT_FOUND occurs and max_len > 1U, the value_out[0] is explicitly set to \0 to ensure safety.

Warning

max_len must match the length of value_out, as this requires nvs_get_str(). Otherwise, data may be truncated.

Parameters

key	NVS storage key (maximum 15 characters). Cannot be NULL.
value_out	Pointer to the buffer where the string will be stored. Cannot be NULL.
max_len	Maximum bytes allocated for value_out (including the null-terminator).

Returns

• ESP_OK: Value located and copied successfully.
• ESP_ERR_INVALID_ARG: The pointer key or value_out is NULL.
• ESP_ERR_NVS_NOT_FOUND: The key does not exist in storage.
• ESP_ERR_NVS_*: System errors propagated from nvs_open() or nvs_get_str().

Example of use:

#include <esp_log.h>
#include <esp_err.h>
#include <esp_iot_framework_core_ext.h>
 
#define TAG "CONFIG"
 
void load_dev_name(void) {
    char buffer[32] = {0};
 
    // Load saved name. If not found, buffer will be empty ("")
    esp_err_t ret = eif_nvs_value_load("dev_name", buffer, sizeof(buffer));
 
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Loaded name: %s", buffer);
    } else if (ret == ESP_ERR_NVS_NOT_FOUND) {
        ESP_LOGW(TAG, "Name not found, using default.");
    } else {
        ESP_LOGE(TAG, "Error: %s", esp_err_to_name(ret));
    }
}

eif_nvs_value_load_malloc()

esp_err_t eif_nvs_value_load_malloc	(	const char *	key,
		char **const	value_out,
		size_t *const	value_out_len
	)

Queries storage to determine the data size, allocates a buffer from the heap via pvPortMalloc(), and copies the string into it. If any operation fails, *value_out is guaranteed to be set to NULL and *value_out_len is set to 0U.

Note

This function automatically calls vPortFree(*value_out) at the beginning to clear pre-existing allocations.

Warning

The caller assumes ownership of the allocated buffer. If this function returns ESP_OK, the caller MUST release the memory using vPortFree(*value_out) (or the respective pointer variable) to avoid leaks.

Parameters

key	NVS storage key (maximum 15 characters). Cannot be NULL.
value_out	Double pointer to store the allocated buffer address. Cannot be NULL.
value_out_len	Pointer to store the string length (including the \0). Cannot be NULL.

Returns

• ESP_OK: Memory allocated and string loaded successfully.
• ESP_ERR_INVALID_ARG: The pointer key, value_out, or value_out_len is NULL.
• ESP_ERR_NVS_NOT_FOUND: The key does not exist in storage.
• ESP_ERR_NO_MEM: Memory could not be allocated due to the lack of an empty block of the required size.
• ESP_ERR_NVS_*: System errors propagated from nvs_open() or nvs_get_str().

Example of use:

#include <esp_log.h>
#include <esp_err.h>
#include <esp_iot_framework_core_ext.h>
 
#define TAG "CONFIG"
 
void load_dynamic_token(void) {
    char *token_buf = NULL; // Must be initialized to NULL
    size_t token_len = 0U;
 
    esp_err_t err = eif_nvs_value_load_malloc("huge_token", &token_buf, &token_len);
 
    if (err == ESP_OK) {
        ESP_LOGI(TAG, "Token loaded (%u bytes): %s", token_len, token_buf);
       
        // Mandatory resource cleanup
        vPortFree(token_buf);
        token_buf = NULL;
    } else if (err == ESP_ERR_NVS_NOT_FOUND) {
        ESP_LOGW(TAG, "Token not found.");
    } else {
        ESP_LOGE(TAG, "Failed to load token: %s", esp_err_to_name(err));
    }
}

eif_nvs_wifi_profile_save()

esp_err_t eif_nvs_wifi_profile_save	(	uint8_t	index,
		const char *const	ssid,
		const char *const	pass
	)

Writes the provided SSID and password to NVS under auto-generated keys. Before writing, the function verifies that the profile index is within the valid user range and checks the credential string lengths.

Valid index range check: (index >= 1) && (index <= WIFI_PROFILES_MAX_COUNT)

If both the ssid and the pass have a length of 0, the length checks are ignored. This is done to clear the specified slot. The verification is bypassed according to the following logic: (len(ssid) == 0) && (len(pass) == 0)

Note

Profile index 0 is system-reserved (read-only). If you try to overwrite it, you will get an error.

Parameters

index	Profile index slot. Must be from 1 to EIF_WIFI_PROFILES_MAX_COUNT.
ssid	Wi-Fi SSID string. Cannot be NULL. The length should be from EIF_WIFI_SSID_MIN_LEN to EIF_WIFI_SSID_MAX_LEN.
pass	Wi-Fi Password string. Cannot be NULL. The length should be from EIF_WIFI_PASS_MIN_LEN to EIF_WIFI_PASS_MAX_LEN.

Returns

• ESP_OK: Profile validated and saved successfully.
• ESP_ERR_INVALID_ARG: The pointer ssid or pass is NULL.
• ESP_ERR_INVALID_SIZE: The index is out of the possible range.
• ESP_ERR_NVS_*: System errors propagated from eif_nvs_value_save().

Example of use:

#include <esp_log.h>
#include <esp_err.h>
#include <esp_iot_framework_core_ext.h>
 
#define TAG "WIFI_CONFIG"
 
void save_user_network(void) {
    // Save user credentials to slot index 1
    esp_err_t err = eif_nvs_wifi_profile_save(1U, "MyHomeWiFi", "SecretPass123");
 
    if (err == ESP_OK) {
        ESP_LOGI(TAG, "Profile 1 stored successfully.");
    } else {
        ESP_LOGE(TAG, "Failed to store profile: %s", esp_err_to_name(err));
    }
}

eif_nvs_wifi_profile_load()

esp_err_t eif_nvs_wifi_profile_load	(	uint8_t	index,
		char *const	ssid_out,
		char *const	pass_out
	)

Reads SSID and password from NVS into pre-allocated buffers.

Valid index range: (index >= 0) && (index <= WIFI_PROFILES_MAX_COUNT)

Note

Querying profile 0 directly returns system-hardcoded credentials (EIF_WIFI_SSID_DEFAULT and EIF_WIFI_PASS_DEFAULT), completely bypassing flash memory access. Any other profile index explicitly queries the underlying NVS partition.

Parameters

index	Profile index slot. Must be from 0 to EIF_WIFI_PROFILES_MAX_COUNT.
ssid_out	Buffer for SSID. Cannot be NULL. The length should be EIF_WIFI_SSID_MAX_LEN.
pass_out	Buffer for password. Cannot be NULL. The length should be EIF_WIFI_PASS_MAX_LEN.

Returns

• ESP_OK: Profile loaded successfully.
• ESP_ERR_INVALID_ARG: The pointer ssid_out or pass_out is NULL.
• ESP_ERR_INVALID_SIZE: The index is out of the possible range.
• ESP_ERR_NVS_NOT_FOUND: No data at specified index.
• ESP_ERR_NVS_*: System errors propagated from eif_nvs_value_load().

Example of use:

#include <esp_log.h>
#include <esp_err.h>
#include <esp_iot_framework_core_ext.h>
 
#define TAG "WIFI_CFG"
 
void load_profile(uint8_t idx) {
    char ssid[EIF_WIFI_SSID_MAX_LEN] = {0};
    char pass[EIF_WIFI_PASS_MAX_LEN] = {0};
 
    if (eif_nvs_wifi_profile_load(idx, ssid, pass) == ESP_OK) {
        ESP_LOGI(TAG, "Profile %u: SSID=[%s]", idx, ssid);
    }
}

eif_nvs_basic_auth_line_save()

esp_err_t eif_nvs_basic_auth_line_save

(

const unsigned char *const

pass

)

Takes the raw password, combines it with the default username (admin), and encodes the admin:password combination into Base64. The final string is prefixed with Basic  (e.g., Basic YWRtaW46cGFzcw==) and saved to NVS.

If an empty password (length 0) is provided, the function automatically generates and saves the default empty-password line (Basic YWRtaW46).

Parameters

pass	Raw password string. Cannot be NULL. The length should be from EIF_BASIC_AUTH_PASS_MIN_LEN to EIF_BASIC_AUTH_PASS_MAX_LEN.

Returns

• ESP_OK: Password successfully encoded, formatted, and saved to NVS.
• ESP_ERR_INVALID_ARG: The pass pointer is NULL.
• ESP_ERR_INVALID_SIZE: The length of the pass is outside the acceptable range.
• ESP_ERR_NO_MEM: Memory could not be allocated due to the lack of an empty block of the required size.
• ESP_ERR_NVS_*: System errors propagated from eif_nvs_value_save().

#include <esp_log.h>
#include <esp_err.h>
#include <esp_iot_framework_core_ext.h>
#include <esp_iot_framework_core_macros.h>
 
#define TAG "AUTH_CFG"
 
void update_web_password(const unsigned char *new_pass) {
    EIF_TAG_WITH_UNUSED "AUTH";
    esp_err_t ret = ESP_OK;
 
    // Handles validation, Base64 encoding, and NVS storage automatically
    EIF_IF_OK_CHECK_ESP_ERR_T(ret, eif_nvs_basic_auth_line_save(new_pass),
        "Failed to save Basic Auth credentials");
 
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Web authentication updated successfully.");
    }
}

eif_nvs_basic_auth_line_load()

esp_err_t eif_nvs_basic_auth_line_load

(

char *const

buf_out

)

Reads the stored authorization string from NVS into a pre-allocated buffer. The output string contains the configuration prefix, username, and password.

Example of output written to buf_out:

Basic YWRtaW46bXlfcGFzcw==

Parameters

buf_out

Buffer for Basic Auth string (e.g., Basic YWRtaW46cGFzcw==). Cannot be NULL. The length should be EIF_BASIC_AUTH_LINE_MAX_LEN.

Returns

• ESP_OK: Credential string located and loaded successfully.
• ESP_ERR_INVALID_ARG: The buf_out pointer is NULL.
• ESP_ERR_NVS_*: System errors propagated from eif_nvs_value_load().

#include <esp_log.h>
#include <esp_err.h>
#include <esp_iot_framework_core_ext.h>
#include <esp_iot_framework_core_macros.h>
 
#define TAG "AUTH_RUN"
 
void apply_auth_header(void) {
    EIF_TAG_WITH_UNUSED "AUTH";
    esp_err_t ret = ESP_OK;
    char auth_line[EIF_BASIC_AUTH_LINE_MAX_LEN] = {0};
 
    EIF_IF_OK_CHECK_ESP_ERR_T(ret, eif_nvs_basic_auth_line_load(auth_line),
        "Failed to load auth line");
 
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Loaded Auth Header: %s", auth_line);
        // Pass auth_line to HTTP client configuration here
    }
}