Production-ready MCU-integrated non-volatile storage implementation. More...

#include <EspNvs.h>

Inheritance diagram for EspNvs:

Collaboration diagram for EspNvs:

Public Member Functions
	EspNvs (const char *namespace_name) noexcept
	Constructor with namespace specification.

	~EspNvs () noexcept override
	Destructor - ensures proper cleanup.

hf_nvs_err_t	Initialize () noexcept override
	Initialize the NVS system and open the namespace.

hf_nvs_err_t	Deinitialize () noexcept override
	Deinitialize the NVS system and close the namespace.

hf_nvs_err_t	SetU32 (const char *key, hf_u32_t value) noexcept override
	Store a 32-bit unsigned integer value.

hf_nvs_err_t	GetU32 (const char *key, hf_u32_t &value) noexcept override
	Retrieve a 32-bit unsigned integer value.

hf_nvs_err_t	SetString (const char key, const char value) noexcept override
	Store a string value.

hf_nvs_err_t	GetString (const char key, char buffer, size_t buffer_size, size_t *actual_size=nullptr) noexcept override
	Retrieve a string value.

hf_nvs_err_t	SetBlob (const char key, const void data, size_t data_size) noexcept override
	Store binary data (blob).

hf_nvs_err_t	GetBlob (const char key, void buffer, size_t buffer_size, size_t *actual_size=nullptr) noexcept override
	Retrieve binary data (blob).

hf_nvs_err_t	EraseKey (const char *key) noexcept override
	Remove a key from storage.

hf_nvs_err_t	Commit () noexcept override
	Commit any pending writes to non-volatile storage.

bool	KeyExists (const char *key) noexcept override
	Check if a key exists in storage.

hf_nvs_err_t	GetSize (const char *key, size_t &size) noexcept override
	Get the size of a stored value.

const char *	GetDescription () const noexcept override
	Get description of this NVS implementation.

size_t	GetMaxKeyLength () const noexcept override
	Get maximum key length supported.

size_t	GetMaxValueSize () const noexcept override
	Get maximum value size supported.

hf_nvs_err_t	GetStatistics (hf_nvs_statistics_t &statistics) const noexcept override
	Get NVS operation statistics.

hf_nvs_err_t	GetDiagnostics (hf_nvs_diagnostics_t &diagnostics) const noexcept override
	Get NVS diagnostic information.

Public Member Functions inherited from BaseNvs
virtual	~BaseNvs () noexcept=default
	Virtual destructor to ensure proper cleanup.

	BaseNvs (const BaseNvs &)=delete

BaseNvs &	operator= (const BaseNvs &)=delete

bool	EnsureInitialized ()
	Ensures that the NVS storage is initialized (lazy initialization).

bool	EnsureDeinitialized ()
	Ensures that the NVS storage is deinitialized.

bool	IsInitialized () const noexcept
	Check if storage is initialized.

const char *	GetNamespace () const noexcept
	Get the namespace name.

virtual hf_nvs_err_t	ResetStatistics () noexcept
	Reset NVS operation statistics.

virtual hf_nvs_err_t	ResetDiagnostics () noexcept
	Reset NVS diagnostic information.

Private Member Functions
hf_nvs_err_t	ConvertMcuError (int mcu_error) const noexcept
	Convert MCU-specific error code to HardFOC NVS error.

void	UpdateStatistics (bool error_occurred) noexcept
	Update operation statistics and performance counters.

bool	IsValidKey (const char *key) const noexcept
	Validate key name according to ESP32 NVS constraints.

Private Attributes
void *	nvs_handle_
	Platform-specific NVS handle (nvs_handle_t on ESP32)

int	last_error_code_
	Last MCU-specific error code for debugging.

hf_nvs_statistics_t	statistics_
	Operation statistics.

hf_nvs_diagnostics_t	diagnostics_
	Diagnostic information.

PlatformMutex	mutex_
	Mutex for thread-safe operations.

Additional Inherited Members
Protected Member Functions inherited from BaseNvs
	BaseNvs (const char *namespace_name) noexcept
	Protected constructor with namespace specification.

void	SetInitialized (bool initialized) noexcept
	Set the initialized state.

Protected Attributes inherited from BaseNvs
const char *	namespace_name_
	Namespace name.

bool	initialized_
	Initialization status.

hf_nvs_statistics_t	statistics_
	NVS operation statistics.

hf_nvs_diagnostics_t	diagnostics_
	NVS diagnostic information.

Detailed Description

Production-ready MCU-integrated non-volatile storage implementation.

This class provides comprehensive non-volatile storage using the microcontroller's built-in storage mechanisms with enterprise-grade features. On ESP32-C6, it leverages the modern ESP-IDF v5.5+ NVS library with advanced security, performance optimizations, and comprehensive error handling. The implementation provides the unified BaseNvs API while exposing platform-specific advanced features.

Core Features:

Key-value storage using MCU's integrated NVS with namespace isolation
Multiple data type support (uint32_t, string, blob) with type safety
Atomic operations with consistency guarantees and durability
Comprehensive error handling with detailed error reporting
Performance monitoring and statistics tracking
Thread-safe operations with optional mutex protection

ESP32-C6 Advanced Features:

HMAC-based encryption for secure storage without flash encryption
XTS encryption with eFuse-based key management
Handle-based modern ESP-IDF v5.5+ API with improved performance
Comprehensive error mapping for all ESP32-C6 NVS error conditions
Support for encrypted and non-encrypted partitions
Advanced partition management and configuration options

Performance Characteristics:

Optimized for high-frequency read/write operations
Intelligent commit strategies balancing durability vs. performance
Efficient handle management with validation caching
Statistics tracking with minimal performance overhead
Key validation with comprehensive constraint checking

Security Features:

Hardware-backed encryption using ESP32-C6 HMAC peripheral
Tamper-resistant key storage in eFuse blocks
Data integrity validation and corruption detection
Secure key generation and management
Protection against unauthorized access and data tampering

Note: This implementation requires sufficient flash storage on the MCU.; ESP32-C6 encryption features require proper eFuse configuration.; Thread safety is optional and controlled by HF_THREAD_SAFE define.; All operations are atomic and provide consistency guarantees.

Warning: Encryption keys stored in eFuse are permanent and irreversible.; Ensure proper backup and key management procedures.

See also: BaseNvs for the abstract interface definition; McuTypes.h for platform-specific type definitions; McuSelect.h for platform selection and configuration

Constructor & Destructor Documentation

◆ EspNvs()

EspNvs::EspNvs ( const char * namespace_name )

explicitnoexcept

Constructor with namespace specification.

Parameters

namespace_name Name of the storage namespace

◆ ~EspNvs()

EspNvs::~EspNvs ( )

overridenoexcept

Destructor - ensures proper cleanup.

Member Function Documentation

◆ Commit()

hf_nvs_err_t EspNvs::Commit ( )

overridevirtualnoexcept

Commit any pending writes to non-volatile storage.

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ ConvertMcuError()

hf_nvs_err_t EspNvs::ConvertMcuError ( int mcu_error ) const

privatenoexcept

Convert MCU-specific error code to HardFOC NVS error.

Provides comprehensive mapping from ESP32-C6 NVS error codes to unified HardFOC error enumeration, including all encryption and advanced feature error conditions.

Parameters

mcu_error MCU-specific error code (esp_err_t on ESP32)

Returns: Corresponding hf_nvs_err_t enumeration value

Note: Supports all ESP-IDF v5.5+ NVS error codes including encryption

◆ Deinitialize()

hf_nvs_err_t EspNvs::Deinitialize ( )

overridevirtualnoexcept

Deinitialize the NVS system and close the namespace.

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ EraseKey()

hf_nvs_err_t EspNvs::EraseKey ( const char * key )

overridevirtualnoexcept

Remove a key from storage.

Parameters

key	Storage key to remove

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ GetBlob()

hf_nvs_err_t EspNvs::GetBlob	(	const char *	key,
		void *	buffer,
		size_t	buffer_size,
		size_t *	actual_size = nullptr )

overridevirtualnoexcept

Retrieve binary data (blob).

Parameters

key	Storage key (null-terminated string)
buffer	Buffer to store the retrieved data
buffer_size	Size of the buffer in bytes
actual_size	Actual size of the data (optional)

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ GetDescription()

const char * EspNvs::GetDescription ( ) const

overridevirtualnoexcept

Get description of this NVS implementation.

Returns: Description string

Implements BaseNvs.

◆ GetDiagnostics()

hf_nvs_err_t EspNvs::GetDiagnostics ( hf_nvs_diagnostics_t & diagnostics ) const

overridevirtualnoexcept

Get NVS diagnostic information.

Parameters

diagnostics Reference to diagnostics structure to fill

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Reimplemented from BaseNvs.

◆ GetMaxKeyLength()

size_t EspNvs::GetMaxKeyLength ( ) const

overridevirtualnoexcept

Get maximum key length supported.

Returns: Maximum key length in characters

Implements BaseNvs.

◆ GetMaxValueSize()

size_t EspNvs::GetMaxValueSize ( ) const

overridevirtualnoexcept

Get maximum value size supported.

Returns: Maximum value size in bytes

Implements BaseNvs.

◆ GetSize()

hf_nvs_err_t EspNvs::GetSize	(	const char *	key,
		size_t &	size )

overridevirtualnoexcept

Get the size of a stored value.

Parameters

key	Storage key
size	Reference to store the size

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ GetStatistics()

hf_nvs_err_t EspNvs::GetStatistics ( hf_nvs_statistics_t & statistics ) const

overridevirtualnoexcept

Get NVS operation statistics.

Parameters

statistics Reference to statistics structure to fill

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Reimplemented from BaseNvs.

◆ GetString()

hf_nvs_err_t EspNvs::GetString	(	const char *	key,
		char *	buffer,
		size_t	buffer_size,
		size_t *	actual_size = nullptr )

overridevirtualnoexcept

Retrieve a string value.

Parameters

key	Storage key (null-terminated string)
buffer	Buffer to store the retrieved string
buffer_size	Size of the buffer in bytes
actual_size	Actual size of the string (optional)

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ GetU32()

hf_nvs_err_t EspNvs::GetU32	(	const char *	key,
		hf_u32_t &	value )

overridevirtualnoexcept

Retrieve a 32-bit unsigned integer value.

Parameters

key	Storage key (null-terminated string)
value	Reference to store the retrieved value

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ Initialize()

hf_nvs_err_t EspNvs::Initialize ( )

overridevirtualnoexcept

Initialize the NVS system and open the namespace.

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ IsValidKey()

bool EspNvs::IsValidKey ( const char * key ) const

privatenoexcept

Validate key name according to ESP32 NVS constraints.

Parameters

key	Key name to validate

Returns: true if key is valid, false otherwise

◆ KeyExists()

bool EspNvs::KeyExists ( const char * key )

overridevirtualnoexcept

Check if a key exists in storage.

Parameters

key	Storage key to check

Returns: true if key exists, false otherwise

Implements BaseNvs.

◆ SetBlob()

hf_nvs_err_t EspNvs::SetBlob	(	const char *	key,
		const void *	data,
		size_t	data_size )

overridevirtualnoexcept

Store binary data (blob).

Parameters

key	Storage key (null-terminated string)
data	Pointer to data to store
data_size	Size of data in bytes

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ SetString()

hf_nvs_err_t EspNvs::SetString	(	const char *	key,
		const char *	value )

overridevirtualnoexcept

Store a string value.

Parameters

key	Storage key (null-terminated string)
value	String value to store

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ SetU32()

hf_nvs_err_t EspNvs::SetU32	(	const char *	key,
		hf_u32_t	value )

overridevirtualnoexcept

Store a 32-bit unsigned integer value.

Parameters

key	Storage key (null-terminated string)
value	Value to store

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ UpdateStatistics()

void EspNvs::UpdateStatistics ( bool error_occurred )

privatenoexcept

Update operation statistics and performance counters.

Tracks operation counts, error rates, and timing for performance monitoring and debugging purposes.

Parameters

error_occurred Whether the operation resulted in an error

Member Data Documentation

◆ diagnostics_

hf_nvs_diagnostics_t EspNvs::diagnostics_

mutableprivate

Diagnostic information.

◆ last_error_code_

int EspNvs::last_error_code_

mutableprivate

Last MCU-specific error code for debugging.

◆ mutex_

PlatformMutex EspNvs::mutex_

mutableprivate

Mutex for thread-safe operations.

◆ nvs_handle_

void* EspNvs::nvs_handle_

private

Platform-specific NVS handle (nvs_handle_t on ESP32)

◆ statistics_

hf_nvs_statistics_t EspNvs::statistics_

mutableprivate

Operation statistics.

The documentation for this class was generated from the following file:

inc/mcu/esp32/EspNvs.h

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ EspNvs()

◆ ~EspNvs()

Member Function Documentation

◆ Commit()

◆ ConvertMcuError()

◆ Deinitialize()

◆ EraseKey()

◆ GetBlob()

◆ GetDescription()

◆ GetDiagnostics()

◆ GetMaxKeyLength()

◆ GetMaxValueSize()

◆ GetSize()

◆ GetStatistics()

◆ GetString()

◆ GetU32()

◆ Initialize()

◆ IsValidKey()

◆ KeyExists()

◆ SetBlob()

◆ SetString()

◆ SetU32()

◆ UpdateStatistics()

Member Data Documentation

◆ diagnostics_

◆ last_error_code_

◆ mutex_

◆ nvs_handle_

◆ statistics_