ESP32 NVS 管理库

这个库提供了一个简化的接口来操作 ESP32 的非易失性存储(NVS)，并包含一个管理器来高效管理多个命名空间的访问。它封装了 ESP-IDF 的 NVS API，提供了更易用且线程安全的接口。

主要特性

命名空间管理器：单例模式管理多个 NVS 命名空间
引用计数：自动管理命名空间的打开和关闭
线程安全：所有操作都通过互斥锁保护
读写接口：支持所有基本数据类型、字符串和二进制数据
自动提交：在适当时候自动提交更改
错误处理：详细的错误日志输出

使用示例

基本读写操作

Cpp

#include "my_nvs.hpp"

void app_main() {
    // 初始化 NVS 分区
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        ret = nvs_flash_init();
    }
    ESP_ERROR_CHECK(ret);

    // 创建命名空间对象（默认使用 "nvs" 分区）
    MyNVS my_namespace("my_app_data", NVS_READWRITE);

    // 写入数据
    my_namespace.write("counter", 42);
    my_namespace.write("device_name", "ESP32_Device");
    
    // 读取数据
    int32_t counter;
    my_namespace.read("counter", &counter);
    
    std::string device_name;
    my_namespace.read("device_name", device_name);
    
    ESP_LOGI(TAG, "Counter: %d, Device: %s", counter, device_name.c_str());
}

二进制数据操作

Cpp

// 写入二进制数据
uint8_t config_data[128] = {...};
my_namespace.write("config_blob", config_data, sizeof(config_data));

// 读取二进制数据
size_t blob_size = sizeof(config_data);
uint8_t read_data[128];
my_namespace.read("config_blob", read_data, &blob_size);

其他操作

Cpp

// 检查键是否存在
if (my_namespace.find("setting") == ESP_OK) {
    // 键存在
}

// 删除键
my_namespace.erase_key("obsolete_setting");

// 清空整个命名空间
my_namespace.erase_all();

// 手动提交更改
my_namespace.commit();

配置选项

在menuconfig中配置最大命名空间数量：

Plaintext

Component config -> MyNVS Configuration -> 
    [*] Enable MyNVS Manager
    (8) Max number of namespaces

错误处理

所有函数返回标准的 esp_err_t 错误代码，并使用 ESP_LOGE 输出错误日志。常见错误包括：
- ESP_ERR_NVS_NOT_FOUND: 键不存在
- ESP_ERR_NVS_INVALID_HANDLE: 无效的命名空间句柄
- ESP_ERR_NVS_READ_ONLY: 尝试写入只读命名空间
- ESP_FAIL: 一般性失败（如初始化失败）

内存管理

字符串读取时动态分配内存，使用后自动释放
管理器使用静态数组存储命名空间信息
当命名空间的引用计数降为0时自动关闭

线程安全

所有操作都通过互斥锁保护，确保在多线程环境下的安全性
1. 命名空间管理器使用全局互斥锁
2. 每个命名空间有自己的互斥锁
3. 读写操作自动加锁

最佳实践

尽量保持命名空间对象局部作用域
批量操作后手动调用 commit()
检查所有读写操作的返回值
使用 find() 检查键是否存在后再读取
避免在低内存情况下操作大二进制数据
使用read/write方法操作基本类型时时应当使用esp原生支持的类型；

依赖

ESP-IDF 5.4+
C++ 11标准

许可

暂未确定

smallin/my_nvs

readme

ESP32 NVS 管理库

主要特性

使用示例

基本读写操作

二进制数据操作

其他操作

配置选项

错误处理

内存管理

线程安全

最佳实践

依赖

许可

Links

Supports all targets

License: Custom

Stats

Badge