Skip to content

API.md

Latest commit

 

History

History
432 lines (280 loc) · 17.1 KB

API.md

File metadata and controls

432 lines (280 loc) · 17.1 KB
Raw

API Reference

Header Files

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(void)
Initializes NVS flash storage and configuration parameters.
void NvsConfig_SaveDirtyParameters(void)
Saves modified parameters to NVS flash.
uint8_t NvsConfig_SecureLevel(void)
Retrieves the current security level.
esp_err_t NvsConfig_SecureLevelChange(uint8_t new_secure_level)
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). Creates the thread-safety mutex and starts a periodic FreeRTOS timer (every 30 seconds) to commit any changes. Also checks the schema version and invokes the migration callback if a mismatch is detected.

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. Thread-safe — acquires the internal mutex.

void NvsConfig_SaveDirtyParameters(void);

function NvsConfig_SecureLevel

Retrieves the current security level for parameter access. The security level is atomic and safe to read from any task.

uint8_t NvsConfig_SecureLevel(void);

function NvsConfig_SecureLevelChange

Changes the current security level. Logs the transition between security levels, affecting restrictions on parameter modifications. At level N, only parameters with secure_level >= N are writable.

esp_err_t NvsConfig_SecureLevelChange(uint8_t new_secure_level);

Returns: ESP_OK on success, ESP_ERR_INVALID_ARG if the level is out of range.

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:

    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. Thread-safe.

    Returns: ESP_OK if the value changed, ESP_FAIL if it was the same, ESP_ERR_INVALID_STATE if the security level is insufficient.

  • Get a Parameter:

    type Param_Get<name>(void);

    Returns the current value of the parameter. Thread-safe.

  • Reset a Parameter:

    esp_err_t Param_Reset<name>(void);

    Resets the parameter to its default value and marks it as dirty. Thread-safe.

  • Print a Parameter:

    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:

    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. Thread-safe.

  • Get an Array Parameter:

    const type* Param_Get<name>(size_t *out_array_length);

    Retrieves a pointer to the array along with its current length. Thread-safe.

  • Copy an Array Parameter:

    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 ESP_ERR_INVALID_SIZE if the buffer is too small. Thread-safe.

  • Reset an Array Parameter:

    esp_err_t Param_Reset<name>(void);

    Resets the array parameter to its default values and marks it as dirty. Thread-safe.

  • Print an Array Parameter:

    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.

Parameter Registry

The registry provides runtime introspection over all parameters via a vtable pattern. Each parameter gets one entry in the global g_nvsconfig_params[] array.

struct NvsConfigParamEntry_t

Type Field
const char* name
Parameter name as defined in param_table.inc.
const char* description
Human-readable description string.
uint8_t secure_level
Security level required to write this parameter.
bool is_array
True for array parameters, false for scalars.
size_t element_size
sizeof(type) for one element.
size_t element_count
1 for scalars, array size for arrays.
bool (*)() is_dirty
Returns true if the parameter has been modified since last save.
bool (*)() is_default
Returns true if the parameter is at its default value.
esp_err_t (*)() reset
Resets the parameter to its default value.
int (*)(char*, size_t) print
Prints the value into a buffer. Returns characters written.
esp_err_t (*)(const void*, size_t) set
Sets the value from a raw pointer + size. See below.

set(const void* data, size_t data_size) behavior:

Case Scalar Array
Exact size match Sets value, returns ESP_OK Sets all elements, returns ESP_OK
Too small Returns ESP_ERR_INVALID_SIZE (no write) Zero-fills remaining, writes, returns ESP_ERR_INVALID_SIZE (warning)
Too large Returns ESP_ERR_INVALID_SIZE (no write) Returns ESP_ERR_INVALID_SIZE (no write)

Registry Functions

Type Name
const NvsConfigParamEntry_t* NvsConfig_FindParam(const char* name)
Finds a parameter entry by name.
void NvsConfig_ResetAll(void)
Resets all parameters to their default values.
void NvsConfig_PrintAll(void)
Logs all parameter names and values.

function NvsConfig_FindParam

Looks up a parameter registry entry by name. Performs a linear search over g_nvsconfig_params[].

const NvsConfigParamEntry_t* NvsConfig_FindParam(const char* name);

Parameters:

  • name — The parameter name (case-sensitive, must match the name in param_table.inc).

Returns: Pointer to the entry, or NULL if not found.

function NvsConfig_ResetAll

Resets every parameter to its default value by calling each entry's reset() function pointer.

void NvsConfig_ResetAll(void);

function NvsConfig_PrintAll

Logs all parameters to the ESP-IDF log output in the format name = value.

void NvsConfig_PrintAll(void);

Change Callbacks

Register callbacks that fire when parameter values change. Callbacks are invoked outside the mutex to prevent deadlocks.

Type Name
esp_err_t NvsConfig_RegisterOnChange(const char* param_name, NvsConfigOnChange_t cb, void* user_data)
Registers a per-parameter change callback.
esp_err_t NvsConfig_RegisterGlobalOnChange(NvsConfigOnChange_t cb, void* user_data)
Registers a callback that fires for any parameter change.
void NvsConfig_ClearCallbacks(void)
Removes all registered callbacks.

typedef NvsConfigOnChange_t

typedef void (*NvsConfigOnChange_t)(const char* param_name, void* user_data);

function NvsConfig_RegisterOnChange

Registers a callback that fires when a specific parameter changes.

esp_err_t NvsConfig_RegisterOnChange(const char* param_name,
                                     NvsConfigOnChange_t cb,
                                     void* user_data);

Parameters:

  • param_name — Parameter name to watch (case-sensitive).
  • cb — Callback function.
  • user_data — Passed to the callback on invocation.

Returns: ESP_OK on success, ESP_ERR_NO_MEM if the maximum number of callback slots (16) is reached.

function NvsConfig_RegisterGlobalOnChange

Registers a callback that fires when any parameter changes.

esp_err_t NvsConfig_RegisterGlobalOnChange(NvsConfigOnChange_t cb,
                                           void* user_data);

Returns: ESP_OK on success, ESP_ERR_NO_MEM if the maximum number of callback slots is reached.

function NvsConfig_ClearCallbacks

Removes all registered callbacks. Primarily useful for testing.

void NvsConfig_ClearCallbacks(void);

Wear-Level Tracking

Per-parameter write counters to monitor flash wear. Counters are in-memory and reset on reboot.

Type Name
uint32_t NvsConfig_GetWriteCount(const char* name)
Returns the write count for a parameter.
uint32_t NvsConfig_GetTotalWriteCount(void)
Returns the total write count across all params.
void NvsConfig_ResetWriteCounts(void)
Resets all write counters to zero.

function NvsConfig_GetWriteCount

Returns the number of successful writes to a parameter since initialization.

uint32_t NvsConfig_GetWriteCount(const char* name);

Returns: Write count, or 0 if the parameter name is not found.

function NvsConfig_GetTotalWriteCount

Returns the sum of all per-parameter write counts.

uint32_t NvsConfig_GetTotalWriteCount(void);

function NvsConfig_ResetWriteCounts

Resets all write counters to zero. Primarily useful for testing.

void NvsConfig_ResetWriteCounts(void);

Schema Versioning

Detects parameter table changes across firmware updates. When NvsConfig_Init() finds a version mismatch in NVS, it invokes the registered migration callback. If no callback is registered (or it returns an error), all parameters are reset to defaults.

Type Name
esp_err_t NvsConfig_RegisterMigration(NvsConfigMigrationCb_t cb)
Registers a migration callback. Call before Init.
uint32_t NvsConfig_GetSchemaVersion(void)
Returns the current schema version.

define NVS_CONFIG_SCHEMA_VERSION

Define this macro before including nvs_config.h to set your schema version. Defaults to 1.

#define NVS_CONFIG_SCHEMA_VERSION 2
#include "nvs_config.h"

typedef NvsConfigMigrationCb_t

typedef esp_err_t (*NvsConfigMigrationCb_t)(uint32_t old_version, uint32_t new_version);

function NvsConfig_RegisterMigration

Registers a migration callback. Must be called before NvsConfig_Init(). When a version mismatch is detected, the callback is invoked with the old and new version numbers. If the callback returns ESP_OK, parameters are loaded normally. Any other return value causes a full reset to defaults.

esp_err_t NvsConfig_RegisterMigration(NvsConfigMigrationCb_t cb);

Returns: ESP_OK on success.

function NvsConfig_GetSchemaVersion

Returns the current schema version stored in NVS.

uint32_t NvsConfig_GetSchemaVersion(void);

File: nvs_config_console.h

Optional header for interactive UART console commands. Enable by setting CONFIG_NVS_CONFIG_CONSOLE_ENABLED=y in your sdkconfig or sdkconfig.defaults.

Type Name
esp_err_t NvsConfig_ConsoleInit(void)
Registers console commands for parameter management.

function NvsConfig_ConsoleInit

Registers the following ESP-IDF console commands:

Command Description
param-list List all parameters with current values and flags
param-get <name> Print a single parameter's value
param-set <name> <value> Set a scalar parameter from a string
param-reset <name|all> Reset one parameter or all parameters to defaults
param-save Force-save dirty parameters to NVS flash
param-level [N] Get or set the current security level

Call this after esp_console_init() (or before starting a REPL) and after NvsConfig_Init().

esp_err_t NvsConfig_ConsoleInit(void);

Returns: ESP_OK on success.

Additional Notes

  • Thread Safety: All generated parameter functions and core functions are protected by a FreeRTOS mutex. Change callbacks are invoked outside the mutex to prevent deadlocks.

  • Parameter Declarations: Refer to the parameter table example file 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 or visit the GitHub repository.

Happy coding!