hmolavi/nvs_config

[![Component Registry](https://components.espressif.com/components/hmolavi/nvs_config/badge.svg)](https://components.espressif.com/components/hmolavi/nvs_config) [![Espressif](https://img.shields.io/badge/Espressif-Components-blue.svg?style=flat-square)](https://components.espressif.com/components/hmolavi/nvs_config) [![GitHub](https://img.shields.io/badge/GitHub-hmolavi/nvs_config-blue.svg?style=flat-square)](https://github.com/hmolavi/nvs_config) # NVS Config Library The **NVS Storage Config Library** is an ESP-IDF component designed to simplify the creation, management, and persistence of application parameters using Non-Volatile Storage (NVS). It supports both scalar values and array parameters, provides automatic verification against default values, and enables periodic saving of modified parameters using a FreeRTOS timer. ## Features - **Easy Parameter Declaration:** Use the `PARAM` and `ARRAY` macros (via an external parameter table file) to define parameters and their default values. - **Secure Parameter Management:** Configure security levels to protect sensitive parameters. - **Automatic Persistence:** Modified parameters are marked as “dirty” and are safely saved to flash. - **Runtime Updates:** Change security levels and update parameters at runtime without needing to rebuild the firmware. - **Cross-Platform Compatibility:** Built with ESP-IDF for seamless integration in ESP32-based projects. ## How It Works 1. **Initialization:** The `NvsConfig_Init()` function initializes NVS flash storage, loads parameter values from flash (or sets defaults if not present), and creates a periodic timer to check and save modified parameters. 2. **Setting and Getting Parameters:** Each parameter has generated API functions, such as `Param_Set<name>`, `Param_Get<name>`, and `Param_Reset<name>`, to manage its value. 3. **Security Levels:** Access to parameters is controlled via security levels. Use `NvsConfig_SecureLevel()` and `NvsConfig_SecureLevelChange()` to check and update the current security level. ## Getting Started 1. **Add the Component:** Include the component in your ESP-IDF project by referencing it in your project's `CMakeLists.txt` and adding it as a dependency: ```bash idf.py add-dependency "hmolavi/nvs-config" ``` 2. **Define Your NVS Parameters:** Create an `param_table.inc` file in your project's `main` directory. Use either the provided example file, [param_table_example.inc](param_table_example.inc), or one here: ```c /* param_table.inc */ #define ARRAY_INIT(...) {__VA_ARGS__} #ifndef SECURE_LEVEL #define SECURE_LEVEL(secure_level, description) #endif #ifndef PARAM #define PARAM(secure_level, type, name, default, description) #endif #ifndef ARRAY #define ARRAY(secure_level, type, size, name, default, description) #endif SECURE_LEVEL(0, "Full access") SECURE_LEVEL(1, "User level") PARAM(1, char, Letter, 'A', "example char") ARRAY(1, char, 32, Sentence, "example char array", "example char array") ARRAY(1, uint8_t, 5, Numbers, ARRAY_INIT(1, 2, 3, 4, 5), "example uint8_t array") /* Add other parameters... */ #undef PARAM #undef ARRAY #undef SECURE_LEVEL ``` 3. **Initialize in User Code:** Call `NvsConfig_Init()` at startup to load and manage parameters. 4. **Use your parameters:** ```c Param_SetLetter('A'); size_t s_count; const char* s = Param_GetSentence(&s_count); printf("Sentence: %s\n", s); printf("Length of: %d", s_count) uint8_t new_nums[] = {5, 4, 3, 2, 1}; size_t new_nums_count = 5; esp_err_t err = Param_SetNumbers(new_nums, new_nums_count); ``` ## Example ```c #include "nvs_config.h" void app_main(void) { // Initialize the NVS configuration system. if (NvsConfig_Init() != ESP_OK) { printf("NvsConfig Failed\n"); } // Set or get specific parameters using generated functions. Param_SetLetter('A'); // Change example char parameter char value = Param_GetLetter(); // Change security level if needed. NvsConfig_SecureLevelChange(0); } ``` ## Build & Integration - **idf_component.yml** Ensure the component’s version and dependencies are correctly specified. - **CMakeLists.txt** The component is registered with ESP-IDF using `idf_component_register`. ## License This project is released under the [MIT License](LICENSE). ## Support For support and contributions, please visit the [GitHub repository](https://github.com/hmolavi/nvs_config).

# API Reference ## Header Files - [nvs_config.h](#file-nvs_configh) ## File: nvs_config.h This header provides the interface for the NVS Storage Config Library component. ## Core Functions | Type | Name | | --------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | esp_err_t | [**NvsConfig_Init**](#function-nvsconfig_init)(void) <br>_Initializes NVS flash storage and configuration parameters._ | | void | [**NvsConfig_SaveDirtyParameters**](#function-nvsconfig_savedirtyparameters)(void) <br>_Saves modified parameters to NVS flash._ | | uint8_t | [**NvsConfig_SecureLevel**](#function-nvsconfig_securelevel)(void) <br>_Retrieves the current security level._ | | esp_err_t | [**NvsConfig_SecureLevelChange**](#function-nvsconfig_securelevelchange)(uint8*t new_secure_level) <br>\_Changes the current security level and logs the transition.* | --- ### function `NvsConfig_Init` Initializes NVS flash storage and loads configuration parameters from flash (or sets defaults). Also starts a periodic FreeRTOS timer (every 30 seconds) to commit any changes. ```c esp_err_t NvsConfig_Init(void); ``` **Returns:** ESP_OK if initialization is successful; otherwise, ESP_FAIL. --- ### function `NvsConfig_SaveDirtyParameters` Iterates through all parameters, saving modified (“dirty”) parameters to NVS flash and committing the changes. ```c void NvsConfig_SaveDirtyParameters(void); ``` --- ### function `NvsConfig_SecureLevel` Retrieves the current security level for parameter access. ```c uint8_t NvsConfig_SecureLevel(void); ``` --- ### function `NvsConfig_SecureLevelChange` Changes the current security level. Logs the transition between security levels, affecting restrictions on parameter modifications. ```c esp_err_t NvsConfig_SecureLevelChange(uint8_t new_secure_level); ``` **Returns:** ESP_OK on success. --- ## Parameter Functions (Generated via Macros) For each parameter declared in the external `param_table.inc`, several functions are automatically generated. ### Scalar Parameters - **Set a Parameter:** ```c esp_err_t Param_Set<name>(const type value); ``` _Updates the parameter value if allowed by the current security level and marks it as dirty if changed._ - **Get a Parameter:** ```c type Param_Get<name>(void); ``` _Returns the current value of the parameter._ - **Reset a Parameter:** ```c esp_err_t Param_Reset<name>(void); ``` _Resets the parameter to its default value and marks it as dirty._ - **Print a Parameter:** ```c int Param_Print<name>(char *buffer, size_t buffer_size); ``` _Generates a formatted string representation of the parameter and writes it into `buffer` using a defined format. The function returns the total number of characters that were written (excluding the null terminator) in the normal case. If the function detects that there isn’t enough space in the provided buffer (for example, while printing array elements or adding a separator), it returns a value equal to `buffer_size` to indicate truncation/error._ --- ### Array Parameters - **Set an Array Parameter:** ```c esp_err_t Param_Set<name>(const type *value, size_t length); ``` _Updates the array parameter, ensuring the length does not exceed the defined maximum._ - **Get an Array Parameter:** ```c const type* Param_Get<name>(size_t *out_array_length); ``` _Retrieves the array along with its current length._ - **Copy an Array Parameter:** ```c esp_err_t Param_Copy<name>(type *buffer, size_t buffer_size); ``` _Copies the array’s contents into the provided buffer. Returns ESP_OK on success or an error code if the buffer is too small._ - **Reset an Array Parameter:** ```c esp_err_t Param_Reset<name>(void); ``` _Resets the array parameter to its default values and marks it as dirty._ - **Print an Array Parameter:** ```c int Param_Print<name>(char *buffer, size_t buffer_size); ``` _Generates a formatted string representation of the array parameter. The resulting string is written into `buffer`. In normal operation, the function returns the total number of characters written (excluding the null terminator). If the provided buffer is not large enough to hold the complete output (for example, while adding separators between array elements), the function returns a value equal to `buffer_size` as an indicator of truncation/error._ --- ## Additional Notes - **Parameter Declarations:** Refer to the [parameter table example file](param_table_example.inc) for guidelines on defining parameters using the `PARAM` and `ARRAY` macros. - **Logging:** The library utilizes ESP-IDF’s logging system (`esp_log.h`) to output debug and error messages to assist with troubleshooting. - **Error Handling:** All functions (except the print functions) return standard ESP error codes, enabling seamless integration into your application’s error handling routines. Print functions follow the `snprintf` convention and return an integer indicating the number of characters that would have been written if sufficient space were available; if truncation or an error occurs, they return `buf_size`. For further examples and usage scenarios, please refer to the [README.md](README.md) or visit the [GitHub repository](https://github.com/hmolavi/nvs_config). Happy coding!

readme

api

Links

Supports all targets

License: MIT

Stats

Badge