smallin/my_nvs

readme

# MyNVS 组件

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

## 主要特性

1. **命名空间管理器**：单例模式管理多个 NVS 命名空间
2. **引用计数**：自动管理命名空间的打开和关闭
3. **线程安全**：所有操作都通过互斥锁保护
4. **读写接口**：支持所生基本数据类型、字符串和二进制数据
5. **自动提交**：在适当时候自动提交更改
6. **错误处理**：read/write方法与原生API保持相同的返回值

## 使用示例

### 基本读写操作

```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);
    
    // 支持打开同一空间（根据需要升级操作模式，升级失败回退回只读模式，回退失败所有实例失效）
    MyNVS my_readonly("partition", "name_space", NVS_READONLY);
    MyNVS my_readwrite("partition", "name_space", NVS_READWRITE);   
}
```

### 二进制数据操作

```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中配置最大命名空间数量：
```
Component config -> MyNVS 组件配置 -> 
    (4) 操作名字空间数量
```

## 错误处理
- 所有函数返回标准的 esp_err_t 错误代码，并使用 ESP_LOGE 输出错误日志。

## 内存管理
- 字符串读取时动态分配内存，使用后自动释放；
- 管理器使用静态数组存储命名空间信息，用户无需保证分区、命名空间生命周期；
- 当命名空间的引用计数降为0时自动关闭；

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

## 最佳实践
1. 尽量保持NVS对象局部作用域
2. 批量操作后手动调用 commit()
3. 检查所有读写操作的返回值
4. 避免在低内存情况下操作大二进制数据
5. 使用read/write方法操作基本类型时时应当使用esp原生支持的类型；

## 依赖
- ESP-IDF 5.4+（其他版本未测试）
- C++ 11标准

## 许可
- Aapche 2.0