Crate esp_nvs 

esp-nvs

This is an ESP-IDF compatible, bare metal, non-volatile storage (NVS) library.

Motivation

The motivation to write this library was

1. to have a backwards compatible NVS driver in case someone is upgrading existing systems from ESP-IDF.
2. to take advantage of the many people working at espressif, who probably spent a minute or two when designing the underlying, flash-friendly data structure.

Therefore, the code is based on the NVS documentation from espressif and inspired by the actual C++ implementation.

Safety

Since the data structure on the flash is based on C structs, some unsafe blocks are used to transmute the read memory to #[repr(C,packed)] structs and unions. Nevertheless, all data structures include CRC32 checksums which are checked and handled. The use of unions requires unsafe as well.

Status

This library is used in production, but nevertheless, there might be some kinks here and there.

Example

esp-nvs requires an implementation of the Platform trait to provide access to the flash as well as to the CRC32 present in the ESP32 ROM.

Example implementation of the Platform driver for an ESP32. This requires new low-level feature of the esp-storage crate:

[dependencies]
esp-storage = { version = "0.8.1", features = ["esp32c6"] }

// TODO: Update the offsets according to your partition table definition.
let partition_offset = 0x390000;
let partition_size = 0x32000;

let storage = esp_storage::FlashStorage::new(peripherals.FLASH);

let nvs =
    esp_nvs::Nvs::new(partition_offset, partition_size, storage).expect("failed to create nvs");

Re-exports

pub use raw::ENTRIES_PER_PAGE;

pub use raw::ENTRY_STATE_BITMAP_SIZE;

pub use raw::FLASH_SECTOR_SIZE;

pub use raw::ITEM_SIZE;

pub use raw::ItemType;

pub use raw::MAX_BLOB_DATA_PER_PAGE;

pub use raw::MAX_BLOB_SIZE;

pub use raw::PAGE_HEADER_SIZE;

pub use raw::PageState;

Modules

error

mem_flash

A minimal in-memory NOR flash implementation for host-side tooling and tests.

platform

raw

Structs

EntryStatistics

Key

A 16-byte key used for NVS storage (15 characters + null terminator)

Nvs

The Nvs struct keeps information about all pages in memory. Increases in size with the numer of pages in the partition.

NvsStatistics

PageStatistics

Constants

MAX_KEY_LENGTH

Maximum Key length is 15 bytes + 1 byte for the null terminator.

Traits

Get

Set