esp-nvs-partition-tool 0.1.0

ESP-IDF compatible NVS partition table parser and generator
Documentation

esp-nvs-partition-tool

ESP-IDF compatible NVS (Non-Volatile Storage) partition table parser and generator inspired by esp-idf-nvs-partition-gen.

This library and CLI tool allows you to parse and generate NVS partition binary files from CSV files, following the ESP-IDF NVS partition format specification.

TODO

  • Encryption support (planned for future release)

CSV Format

The CSV file must have exactly four columns:

key,type,encoding,value

Entry Types

  1. namespace - Defines a namespace

    • Encoding and value must be empty
    • Example: my_namespace,namespace,,

  2. data - Raw data entry

    • Valid encodings: u8, i8, u16, i16, u32, i32, u64, i64, string, hex2bin, base64
    • Example: my_key,data,u32,12345

  3. file - Read value from a file

    • Valid encodings: string, hex2bin, base64, binary
    • Value should be the file path (relative to CSV file)
    • Example: my_blob,file,binary,data.bin

Example CSV

key,type,encoding,value
namespace_one,namespace,,
example_u8,data,u8,100
example_i8,data,i8,-100
example_string,data,string,Hello World
example_blob,data,hex2bin,AABBCCDDEE
namespace_two,namespace,,
config,file,binary,config.bin

CLI Usage

Generate NVS Partition Binary

esp-nvs-partition-tool generate <input.csv> <output.bin> --size <size>

The size can be specified in decimal or hexadecimal (with 0x prefix):

# Generate 16KB partition (decimal)
esp-nvs-partition-tool generate nvs_data.csv partition.bin --size 16384

# Generate 16KB partition (hexadecimal)
esp-nvs-partition-tool generate nvs_data.csv partition.bin --size 0x4000

Parse NVS Partition Binary to CSV

esp-nvs-partition-tool parse <input.bin> <output.csv>

Example:

# Parse a partition binary back to CSV
esp-nvs-partition-tool parse partition.bin recovered_data.csv

Library Usage

Add to your Cargo.toml:

[dependencies]
esp-nvs-partition-tool = "0.1.0"

Example usage:

use esp_nvs_partition_tool::NvsPartition;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse CSV content and generate binary
    let csv_content = std::fs::read_to_string("nvs_data.csv")?;
    let partition = NvsPartition::try_from_str(csv_content)?;
    let binary = partition.generate_partition(16384)?;
    std::fs::write("output.bin", &binary)?;

    // Parse binary back to CSV
    let binary = std::fs::read("output.bin")?;
    let recovered_partition = NvsPartition::try_from_bytes(binary)?;
    let csv_output = recovered_partition.to_csv()?;
    std::fs::write("recovered.csv", &csv_output)?;

    // Auto-detect format (binary or CSV)
    let data = std::fs::read("output.bin")?;
    let auto_partition = NvsPartition::try_from(data)?;
    println!("Found {} entries", auto_partition.entries.len());

    Ok(())
}

References