smallin/my_nvs

readme

# ESP32 NVS 管理库

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

## 主要特性

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

## 使用示例

### 基本读写操作

```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中配置最大命名空间数量：
```
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. 读写操作自动加锁

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

## 依赖
- ESP-IDF 5.4+
- C++ 11标准

## 许可
- 暂未确定