NVS-EEPROM - Arduino EEPROM API for ESP-IDF
Arduino-style EEPROM API backed by ESP-IDF's NVS flash system. Dual C/C++ interface with 8 functions, type-safe macros, C++ templates for any POD type, RAM-buffered writes with explicit commit for minimal flash wear, 0xFF default initialization matching real EEPROM behavior, NVS auto-recovery, and full bounds checking.
Technical Specs
Arduino-Compatible, Zero Arduino Dependencies
The API mirrors Arduino's EEPROM library - begin(size), read(addr), write(addr, val), commit(), end() - so developers migrating from Arduino to ESP-IDF can use the same calling conventions. In C++ projects, NVS_EEPROM EEPROM; gives you an object with identical method signatures. The C API provides NVS_EEPROM_GET() and NVS_EEPROM_PUT() macros for type-safe access to any data type via sizeof, while the C++ class offers get<T>() and put<T>() templates.
RAM-Buffered Flash Wear Minimization
All writes go to a RAM buffer - nothing touches flash until commit() is called, which flushes the entire buffer to NVS as a single binary blob under the "eeprom" namespace and "data" key. This minimizes flash wear by batching multiple writes into one NVS transaction. Unwritten addresses read as 0xFF, matching real physical EEPROM behavior and enabling first-run detection patterns.
Defensive & Self-Healing
begin() handles NVS corruption automatically - if it encounters ESP_ERR_NVS_NO_FREE_PAGES or ESP_ERR_NVS_NEW_VERSION_FOUND, it erases and reinitializes NVS without crashing. If the stored blob size differs from the requested size (e.g., after a firmware update changes the EEPROM layout), the buffer is freshly initialized to 0xFF rather than reading corrupt data. All functions validate address bounds - out-of-range reads return 0xFF, out-of-range writes are silently ignored, and block operations clamp to available space. Double-initialization is caught with a warning log.