01 Overview

NVS (Non-Volatile Storage) is a lightweight key-value store provided by ESP-IDF, backed by a dedicated partition in the module's internal flash. It is designed for small data items such as configuration parameters, calibration data, counters, and device flags.

Unlike RAM, NVS retains data across power cycles, making it the default place to store Wi-Fi credentials, device serial numbers, user settings, and other critical information. Using NVS avoids re-configuring the device on every boot and preserves user data across OTA updates.

Typical use cases include saving provisioning results (e.g., SSID and password), storing sensor calibration offsets, recording device operation counts, and saving user interface preferences. It is not suitable for large files (firmware, logs, images) — use SPIFFS or SD card for those.

NVS supports multiple namespaces, each containing multiple key-value pairs. Key names are limited to 15 characters, and value types include integers, strings, and binary blobs.

NVS includes wear leveling and power-loss safety mechanisms, but frequent writes accelerate flash wear. Therefore, design write frequency carefully, e.g., cache counters or use wear-leveling algorithms.

In ESP-IDF, NVS is the underlying storage for many components (Wi-Fi, Bluetooth), so understanding it is essential for reliable firmware development.

02 Hardware

• Storage medium: Uses the NVS partition in the module's internal flash; no extra chip required. The partition table is defined at compile time and includes an nvs partition by default.
• Flash wear: NVS is flash-based, with limited write cycles (about 100k). Frequent writes (e.g., every second) will quickly exhaust the lifetime; implement software caching or reduce write frequency.
• Power-loss protection: NVS writes have power-loss safety, but extreme cases (e.g., power cut mid-write) may corrupt data; consider backup or checksums for critical data.
• Partition size: The NVS partition size is configured in the partition table, default 24KB. Adjust if more storage is needed, but be careful not to crowd out firmware space.
• Encryption support: NVS supports flash encryption to protect sensitive data (e.g., Wi-Fi passwords). Enabling it requires key management.
• No external connections: This example involves no external hardware; it relies solely on the module's flash.

03 Software flow

1. Call `nvs_flash_init()` to initialize the NVS library. If it returns an error (e.g., partition erased), erase and re-init with `nvs_flash_erase()`.

2. Open a namespace (e.g., "storage") using `nvs_open()` with read/write mode.

3. Use `nvs_get_*` or `nvs_set_*` functions to read/write keys. For example, read SSID or write calibration values.

4. After writing, you must call `nvs_commit()` to commit changes to flash; otherwise data is not actually saved.

5. Handle read failures: if a key does not exist, the function returns a specific error code; use default values or initialize then.

6. On firmware upgrades, if key structure changes, write migration logic: read old keys, convert to new format, delete old keys.

7. For Wi-Fi credentials, you can use `esp_wifi_set_storage(WIFI_STORAGE_FLASH)` to let the Wi-Fi driver manage NVS automatically, avoiding manual read/write.

8. Optionally enable NVS encryption using `nvs_flash_secure_init()` and configure a key partition.

04 Core points

• No commit means no save: Forgetting to call `nvs_commit()` is a common mistake; data stays only in cache and is lost on power-off.
• Frequent writes wear flash: For high-frequency updates like counters, accumulate in RAM and write to NVS periodically.
• Key name length limit: Key names are limited to 15 characters; exceeding causes errors, so design accordingly.
• Version migration: After firmware upgrades, key formats may change; check version at boot and migrate data.
• Don't store large files: NVS is for small data; use SPIFFS or SD card for large files.
• Customizable: Design a config model per product, use multiple namespaces, and enable encrypted NVS for sensitive data.