ESP-IDF NVS Partition Generator

0.2.0 verified Mon Apr 27 auth: no python maintenance

Python tool to generate NVS (Non-Volatile Storage) binary partition images for ESP-IDF projects. Extracts configuration from CSV files and produces binary blobs for flash. Current version 0.2.0, maintenance mode on PyPI, released when ESP-IDF requires updates.

pip install esp-idf-nvs-partition-gen

Common errors

error ModuleNotFoundError: No module named 'esp_idf_nvs_partition_gen' ↓

cause Package not installed or wrong import path.

fix

Run 'pip install esp-idf-nvs-partition-gen' and use the correct import: 'from esp_idf_nvs_partition_gen import NVSGenerator'.

error TypeError: add_csv_reader() missing 1 required positional argument: 'reader' ↓

cause Trying to use the old 'add_csv_file' method with a file path string.

fix

Use a csv.DictReader object: reader = csv.DictReader(open('file.csv')); generator.add_csv_reader(reader).

error ValueError: Invalid entry type: 'string' ↓

cause CSV 'type' column does not contain a valid ESP-IDF NVS type (e.g., 'data', 'namespace'). Check column content.

fix

Ensure 'type' is one of: 'namespace', 'data', 'file'. For string values, use type='data' and encoding='string'.

error KeyError: 'encoding' ↓

cause CSV missing the 'encoding' column header.

fix

Include all four columns: key,type,encoding,value.

Warnings

deprecated The module 'esp_idf_nvs_partition_gen' is deprecated in favor of ESP-IDF's built-in 'parttool.py' and 'nvs_partition_gen' utility. New projects should use the official ESP-IDF tools. ↓

fix Switch to ESP-IDF's nvs_partition_gen.py tool from the esp-idf repository.

gotcha CSV column names must match exactly: 'key','type','encoding','value'. Missing or extra columns cause silent errors or no output. ↓

fix Ensure CSV header is: key,type,encoding,value (case-sensitive).

gotcha Namespace entries must have 'type' set to 'namespace' and 'encoding' and 'value' left blank. Filling them incorrectly will break the NVS structure. ↓

fix For namespace rows, use: key=my_namespace, type=namespace, encoding=<empty>, value=<empty>.

breaking The 'NVSGenerator' class API changed in 0.2.0: 'add_csv_file' method was removed. Use 'add_csv_reader' with a CSV DictReader instead. ↓

fix Replace: generator.add_csv_file(path) -> reader = csv.DictReader(open(path)); generator.add_csv_reader(reader)

Imports

NVSGenerator

from esp_idf_nvs_partition_gen import NVSGenerator

Exact import path from the package

Quickstart

Generate a binary NVS partition from a CSV. Adjust flash_size and page_size to match your ESP-IDF configuration.

from esp_idf_nvs_partition_gen import NVSGenerator
import csv
import io

# Create a sample CSV in memory
csv_data = """key,type,encoding,value
my_string,namespace,,app
my_key,data,string,hello"""

csv_file = io.StringIO(csv_data)
reader = csv.DictReader(csv_file)

# Generate the NVS partition binary
output_path = "partition.bin"
generator = NVSGenerator(flash_size=0x400000, page_size=0x1000)
generator.add_csv_reader(reader)
generator.generate(output_path)
print(f"Generated NVS partition at {output_path}")