前言:
分区表(Partition Table)和 NVS(Non-Volatile Storage)是 ESP-IDF 中用于存储数据的两种不同机制。
-
分区表(Partition Table):
- 分区表定义了将 Flash 存储器划分为不同逻辑分区的方式。每个分区都具有特定的大小、起始地址和类型,可以用于存储不同类型的数据,例如应用程序、文件系统、配置数据等。
- 分区表是在编译时定义的,通常由
partitions.csv
或partitions_singleapp.csv
文件指定。这些文件描述了每个分区的信息,如分区名称、大小、起始地址等。 - 分区表在 ESP32 系统启动时被加载到内存中,ESP-IDF 使用分区表来确定各个分区的位置和属性。通过分区表,可以访问和管理不同分区中的数据。
-
NVS(Non-Volatile Storage):
- NVS 是一种轻量级的键值对存储系统,用于在 Flash 存储器中保存和检索数据。它提供了一种简单的方式来存储应用程序的配置数据、状态信息等。
- NVS 使用了一个称为 "nvs" 的特定分区,该分区被用作存储键值对数据的容器。每个键值对由一个唯一的键和相应的值组成。
- 与其他分区不同,NVS 分区不需要在分区表中显式声明。它是 ESP-IDF 自动创建和管理的特殊分区。
- 通过 NVS API(如
nvs_get()
、nvs_set()
等),应用程序可以对 NVS 进行读写操作,方便地存储和检索数据。
总结:
- 分区表定义了 Flash 存储器中不同分区的划分和属性,用于存储各种类型的数据。
- NVS 是一种简单的键值对存储系统,用于在 Flash 存储器中存储和检索数据,它使用一个特定的分区。
- 分区表和 NVS 是 ESP-IDF 中不同的存储机制,用于不同的数据存储需求。分区表用于管理整个 Flash 存储器的划分,而 NVS 则提供了一种简单的方式来存储和检索数据。
partition table 示例代码:
#include <string.h>
#include <assert.h>
#include "esp_partition.h"
#include "esp_log.h"static const char *TAG = "partition_table--->";void app_main(void)
{/** This example uses the partition table from ../partitions_example.csv. For reference, its contents are as follows:** nvs, data, nvs, 0x9000, 0x6000,* phy_init, data, phy, 0xf000, 0x1000,* factory, app, factory, 0x10000, 1M,* storage, data, , , 0x40000,*/
/*typedef struct {esp_flash_t* flash_chip; !< SPI flash chip on which the partition residesesp_partition_type_t type; !< partition type (app/data)esp_partition_subtype_t subtype; !< partition subtypeuint32_t address; !< starting address of the partition in flashuint32_t size; !< size of the partition, in byteschar label[17]; !< partition label, zero-terminated ASCII stringbool encrypted; !< flag is set to true if partition is encrypted} esp_partition_t;
*/// Find the partition map in the partition tableconst esp_partition_t *partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage"); //三个参数:分区类型、分区子类型和分区标签.在分区表中找到名为 "storage" 的分区assert(partition != NULL);static char store_data[] = "ESP-IDF Partition Operations Example (Read, Erase, Write)"; //写入分区的数据static char read_data[sizeof(store_data)]; //存储从分区读取的数据。// Erase entire partitionmemset(read_data, 0xFF, sizeof(read_data));ESP_ERROR_CHECK(esp_partition_erase_range(partition, 0, partition->size)); //擦除整个分区。这里使用 memset() 函数将 read_data 数组填充为 0xFF,表示将整个分区内容擦除。// Write the data, starting from the beginning of the partitionESP_ERROR_CHECK(esp_partition_write(partition, 0, store_data, sizeof(store_data))); //将 store_data 写入分区。这里将数据写入分区的起始位置,大小为 sizeof(store_data),即存储数据的长度。ESP_LOGI(TAG, "Written data: %s", store_data);// Read back the data, checking that read data and written data matchESP_ERROR_CHECK(esp_partition_read(partition, 0, read_data, sizeof(read_data))); //从分区中读取数据,并通过 memcmp() 函数比较读取的数据和写入的数据是否相同。如果比较结果为 0,则说明读取的数据与写入的数据一致assert(memcmp(store_data, read_data, sizeof(read_data)) == 0);ESP_LOGI(TAG, "Read data: %s", read_data);// Erase the area where the data was written. Erase size shoud be a multiple of SPI_FLASH_SEC_SIZE// and also be SPI_FLASH_SEC_SIZE alignedESP_ERROR_CHECK(esp_partition_erase_range(partition, 0, SPI_FLASH_SEC_SIZE)); //擦除之前写入的数据所占据的区域。这里擦除的大小为 SPI_FLASH_SEC_SIZE,它需要是 SPI_FLASH_SEC_SIZE 的倍数,并且与 SPI_FLASH_SEC_SIZE 对齐。// Read back the data (should all now be 0xFF's)memset(store_data, 0xFF, sizeof(read_data));ESP_ERROR_CHECK(esp_partition_read(partition, 0, read_data, sizeof(read_data))); //读取分区中的数据,并通过比较来验证数据是否已被擦除(全为 0xFF)。assert(memcmp(store_data, read_data, sizeof(read_data)) == 0);ESP_LOGI(TAG, "Erased data");ESP_LOGI(TAG, "Example end");
}
partition table 运行结果:
NVS库的使用
1.概述
非易失性存储(Non-volatile storage) 简称 NVS, 乐鑫使用一套 NVS 库将键值对保存在 SPI flash 中。NVS 库可以使用 read、 write、 erase 的 API 操作 flash 的一部分, 该库使用 data 类型和 nvs 子类型的所有分区。 应用程序可以使用 nvs_openAPI 选用 nvs 表中的分区或通过nvs_open_from_part API 指定其名称后使用其他分区。
2.NVS 可以保存的类型
无符号整型: uint8_t,uint16_t,uint32_t,uint64_t
有符号整型: int8_t, int16_t,int32_t,int64_t
字符串: 必须以 0 结尾, 因为需要知道字符串的长度, 以便保存。
二进制数据: 可变长。
暂不支持浮点数保存
字符串和二进制数据目前仅限于 1984 字节。 对于字符串, 这包括空终止符.
3. NVS 的命名空间
为了缓解不同组件之间的密钥名称之间的潜在冲突, NVS 将每个键值对分配给一个名称空间, 类似数据库中的表。 名称空间名称遵循与键名相同的规则, 即最多 15 个字符。 命名空间名 称 在 nvs_open 或 nvs_open_from_part 调 用 中 指 定 。 随 后 调 用 的 nvs_read_* ,nvs_write_*和 nvs_commit 将返回不透明句柄。 这样, 句柄与名称空间相关联, 并且键名不会与其他名称空间中的相同名称相冲突。
在不同 NVS 分区中具有相同名称的名称空间被视为单独的名称空间。
4.NVS 优势
接口更加安全
相比较于 spi_flash_read 和 spi_flash_write 等接口, NVS 不直接操作 address. 对于终端用户而已, 更加安全.
例如: 应用复杂一点, 容易 spi_flash_write(address, src, size) 不小心写到同一个地址, 或地址写覆盖, 而导致长时间 debug
接口使用接近用户习惯
NVS 接口类似于电脑上操作文件一样:
打开文件(nvs_open), 写文件(nvs_set_xxx), 保存文件(nvs_commit), 关闭文件(nvs_close)
打开文件(nvs_open), 读取文件(nvs_get_xxx), 关闭文件(nvs_close)
擦写均衡, 使 flash 寿命更长
NVS 在操作少量数据上, NVS 分区更大时, 擦写均衡表现的更为明显.
例如: flash 一个 sector 为 4KB, NVS 分配大小为一个 sector, 写同一个 64 Bytes 数据到 flash, 分别比较 spi_flash_xxx 和 nvs 写 64 次
spi_flash_write: 每次写 flash 前, 需擦除 flash. 对应: 64 次擦除 flash, 64 次写 flash
nvs: nvs 内部有擦写均衡, 有标志位记录当前有效存储. 如第一次擦除 sector, 再写 sector 0-63 Byte, 第二次写 sector 64-127 Bytes, 第 64 次(4KB/64Bytes) 写完 sector 最后一个 64 Byte. 对应: 1 次擦除 flash, 64 次写 flash
这样 NVS 减少 64 倍擦除操作, 对 flash 寿命有较大提升.
在 NVS 分区更大, 存储信息少时, 表现的更为明显.
注意事项:
ESP32_学习笔记(一)NVS的操作(存储和读取大数组)(为什么存入数据成功,读取却为零的原因)_arduino esp32 定义最大数组-CSDN博客
5.api函数
esp_err_t nvs_flash_init( void )
初始化默认的NVS分区。
该API初始化默认的NVS分区。默认的NVS分区是在分区表中标记为“ nvs”的分区。
返回
- 如果存储已成功初始化,则为ESP_OK。
- ESP_ERR_NVS_NO_FREE_PAGES如果NVS存储器不包含空页(如果NVS分区被截断,则可能发生)
- 如果在分区表中找不到带有标签“ nvs”的分区,则为ESP_ERR_NOT_FOUND
- 来自基础闪存存储驱动程序的错误代码之一
esp_err_t nvs_flash_init_partition(const char *partition_label)
初始化指定分区的NVS闪存。
返回
- 如果存储已成功初始化,则为ESP_OK。
- ESP_ERR_NVS_NO_FREE_PAGES如果NVS存储器不包含空页(如果NVS分区被截断,则可能发生)
- 如果在分区表中找不到指定的分区,则为ESP_ERR_NOT_FOUND
- 来自基础闪存存储驱动程序的错误代码之一
参量
- [in] partition_label:分区的标签。不得超过16个字符。
esp_err_t nvs_flash_erase( void )
擦除默认的NVS分区。
擦除默认NVS分区(带有标签“ nvs”的分区)的所有内容。
注意
如果分区已初始化,则此函数首先将其初始化。之后,必须再次初始化分区才能使用。
返回
- ESP_OK成功
- 如果分区表中没有标记为“ nvs”的NVS分区,则为ESP_ERR_NOT_FOUND
- 万一取消初始化失败(不应发生),则会出现其他错误
esp_err_t nvs_set_i8(nvs_handle_thandle, const char *key, int8_t value)
给定键的设定值
给定其名称,该功能家族为键设置值。请注意,直到调用nvs_commit函数,才会更新实际存储。
返回
- ESP_OK,如果值设置成功
- 如果句柄已关闭或为NULL,则为ESP_ERR_NVS_INVALID_HANDLE
- ESP_ERR_NVS_READ_ONLY如果存储句柄被打开为只读
- 如果键名不满足约束,则为ESP_ERR_NVS_INVALID_NAME
- ESP_ERR_NVS_NOT_ENOUGH_SPACE,如果基础存储中没有足够的空间来保存该值
- ESP_ERR_NVS_REMOVE_FAILED如果由于闪存写入操作失败而未更新该值。但是,已写入该值,并且只要闪存操作不会再次失败,更新将在nvs重新初始化后完成。
- 如果字符串值太长,则为ESP_ERR_NVS_VALUE_TOO_LONG
参量
- [in] handle:从nvs_open函数获得的句柄。以只读方式打开的句柄不能使用。
- [in] key:密钥名称。最大长度为(NVS_KEY_NAME_MAX_SIZE-1)个字符。不应该是空的。
- [in] value:要设置的值。对于字符串,最大长度(包括空字符)为4000字节。
esp_err_tnvs_set_u8(nvs_handle_thandle, const char *key, uint8_t value)
esp_err_tnvs_set_i16(nvs_handle_thandle, const char *key, int16_t value)
esp_err_tnvs_set_u16(nvs_handle_thandle, const char *key, uint16_t value)
esp_err_tnvs_set_i32(nvs_handle_thandle, const char *key, int32_t value)
esp_err_tnvs_set_u32(nvs_handle_thandle, const char *key, uint32_t value)
esp_err_tnvs_set_i64(nvs_handle_thandle, const char *key, int64_t value)
esp_err_tnvs_set_u64(nvs_handle_thandle, const char *key, uint64_t value)
esp_err_tnvs_set_str(nvs_handle_thandle, const char *key, const char *value)
esp_err_tnvs_get_i8(nvs_handle_thandle, const char *key, int8_t *out_value)
获得给定密钥的价值
这些函数在给定键名的情况下检索键的值。如果键不存在,或者请求的变量类型与设置值时使用的类型不匹配,则返回错误。
发生任何错误时,不会修改out_value。
所有函数都希望out_value是指向给定类型的已分配变量的指针。
// Example of using nvs_get_i32:
int32_t max_buffer_size = 4096; // default value
esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
// if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
// have its default value.
返回
- ESP_OK,如果成功检索到值
- ESP_ERR_NVS_NOT_FOUND如果请求的密钥不存在
- 如果句柄已关闭或为NULL,则为ESP_ERR_NVS_INVALID_HANDLE
- 如果键名不满足约束,则为ESP_ERR_NVS_INVALID_NAME
- 如果长度不足以存储数据,则输入ESP_ERR_NVS_INVALID_LENGTH
参量
- [in] handle:从nvs_open函数获得的句柄。
- [in] key:密钥名称。最大长度为(NVS_KEY_NAME_MAX_SIZE-1)个字符。不应该是空的。
- out_value:指向输出值的指针。对于nvs_get_str和nvs_get_blob可能为NULL,在这种情况下,将在length参数中返回所需的长度。
esp_err_t nvs_get_u8(nvs_handle_t句柄,constchar * key,uint8_t * out_value )
esp_err_t nvs_get_i16(nvs_handle_t句柄,constchar * key,int16_t * out_value )
esp_err_t nvs_get_u16(nvs_handle_t句柄,constchar * key,uint16_t * out_value )
esp_err_t nvs_get_i32(nvs_handle_t句柄,constchar * key,int32_t * out_value )
esp_err_t nvs_get_u32(nvs_handle_t句柄,constchar * key,uint32_t * out_value )
esp_err_t nvs_get_i64(nvs_handle_t句柄,constchar * key,int64_t * out_value )
esp_err_t nvs_get_u64(nvs_handle_t句柄,constchar * key,uint64_t * out_value )
esp_err_tnvs_get_str(nvs_handle_thandle, const char *key, char *out_value, size_t *length)
获得给定密钥的价值
这些函数在给定键的情况下检索条目的数据。如果键不存在,或者请求的变量类型与设置值时使用的类型不匹配,则返回错误。
发生任何错误时,不会修改out_value。
所有函数都希望out_value是指向给定类型的已分配变量的指针。
nvs_get_str和nvs_get_blob函数支持WinAPI样式的长度查询。要获取存储值所需的大小,请使用零out_value和非零长度指针来调用nvs_get_str或nvs_get_blob。length参数指向的变量将设置为所需的长度。对于nvs_get_str,此长度包括零终止符。当使用非零out_value调用nvs_get_str和nvs_get_blob时,length必须非零,并且必须指向out_value中可用的长度。建议将nvs_get / set_str用于零终止的C字符串,将nvs_get / set_blob用于任意数据结构。
// Example (without error checking) of using nvs_get_str to get a string into dynamic array:
size_t required_size;
nvs_get_str(my_handle, "server_name", NULL, &required_size);
char* server_name = malloc(required_size);
nvs_get_str(my_handle, "server_name", server_name, &required_size);
// Example (without error checking) of using nvs_get_blob to get a binary data
into a static array:
uint8_t mac_addr[6];
size_t size = sizeof(mac_addr);
nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size);
返回
- ESP_OK,如果成功检索到值
- ESP_ERR_NVS_NOT_FOUND如果请求的密钥不存在
- 如果句柄已关闭或为NULL,则为ESP_ERR_NVS_INVALID_HANDLE
- 如果键名不满足约束,则为ESP_ERR_NVS_INVALID_NAME
- 如果长度不足以存储数据,则输入ESP_ERR_NVS_INVALID_LENGTH
参量
- [in] handle:从nvs_open函数获得的句柄。
- [in] key:密钥名称。最大长度为(NVS_KEY_NAME_MAX_SIZE-1)个字符。不应该是空的。
- out_value:指向输出值的指针。对于nvs_get_str和nvs_get_blob可能为NULL,在这种情况下,将在length参数中返回所需的长度。
- [inout] length:指向保存out_value长度的变量的非零指针。如果out_value为零,则将其设置为保持该值所需的长度。如果out_value不为零,则将其设置为写入值的实际长度。对于nvs_get_str,它包括零终止符。
esp_err_t nvs_open(constchar * name,nvs_open_mode_t open_mode,nvs_handle_t * out_handle )
从默认NVS分区打开具有给定名称空间的非易失性存储。
多个内部ESP-IDF和第三方应用程序模块可以将其键值对存储在NVS模块中。为了减少键名上的可能冲突,每个模块可以使用其自己的名称空间。默认的NVS分区是在分区表中标记为“ nvs”的分区。
返回
- ESP_OK,如果存储句柄已成功打开
- 如果未初始化存储驱动程序,则为ESP_ERR_NVS_NOT_INITIALIZED
- 如果找不到带有标签“ nvs”的分区,则为ESP_ERR_NVS_PART_NOT_FOUND
- ESP_ERR_NVS_NOT_FOUND id名称空间尚不存在,且模式为NVS_READONLY
- 如果名称空间名称不满足约束条件,则为ESP_ERR_NVS_INVALID_NAME
- 基础存储驱动程序中的其他错误代码
参量
- [in] name:命名空间名称。最大长度为(NVS_KEY_NAME_MAX_SIZE-1)个字符。不应该是空的。
- [in] open_mode:NVS_READWRITE或NVS_READONLY。如果为NVS_READONLY,将打开一个只读句柄。该句柄将拒绝所有写请求。
- [out] out_handle:如果成功(返回码为零),则将在此参数中返回handle。
esp_err_t nvs_commit(nvs_handle_t handle )
将所有未决的更改写入非易失性存储。
设置任何值后,必须调用nvs_commit()以确保将更改写入非易失性存储。各个实现可以在其他时间写入存储,但这不能保证。
返回
- ESP_OK,如果更改已成功写入
- 如果句柄已关闭或为NULL,则为ESP_ERR_NVS_INVALID_HANDLE
- 基础存储驱动程序中的其他错误代码
参量
- [in] handle:通过nvs_open获得的存储句柄。以只读方式打开的句柄不能使用。
void nvs_close(nvs_handle_thandle)
关闭存储句柄并释放所有分配的资源。
一旦不再使用nvs_open打开的每个句柄,应调用该函数。关闭句柄可能不会自动将更改写入非易失性存储。必须使用nvs_commit函数明确地完成此操作。在句柄上调用此函数后,将不再使用该句柄。
参量
- [in] handle:要关闭的存储句柄
NVS 示例代码:
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "nvs_flash.h"
#include "nvs.h"void app_main(void)
{// Initialize NVSesp_err_t err = nvs_flash_init();if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {// NVS partition was truncated and needs to be erased// Retry nvs_flash_initESP_ERROR_CHECK(nvs_flash_erase());err = nvs_flash_init();}ESP_ERROR_CHECK( err );// Openprintf("\n");printf("Opening Non-Volatile Storage (NVS) handle... ");nvs_handle_t my_handle;err = nvs_open("storage", NVS_READWRITE, &my_handle); //打开NVS存储,并将句柄保存在my_handle变量中。STORAGE_NAMESPACE是NVS存储的命名空间if (err != ESP_OK) {printf("Error (%s) opening NVS handle!\n", esp_err_to_name(err));} else {printf("Done\n");// Readprintf("Reading restart counter from NVS ... ");int32_t restart_counter = 0; // value will default to 0, if not set yet in NVSerr = nvs_get_i32(my_handle, "restart_counter", &restart_counter); //从NVS中读取键为"restart_counter"的整数值,并将结果保存在restart_counter变量中。
// err = nvs_get_i32(my_handle, "132", &restart_counter);switch (err) {case ESP_OK:printf("Done\n");printf("Restart counter = %d\n", restart_counter);break;case ESP_ERR_NVS_NOT_FOUND:printf("The value is not initialized yet!\n");break;default :printf("Error (%s) reading!\n", esp_err_to_name(err));}// Writeprintf("Updating restart counter in NVS ... ");restart_counter++;err = nvs_set_i32(my_handle, "restart_counter", restart_counter); //将更新后的二进制数据写入 NVS 中。printf((err != ESP_OK) ? "Failed!\n" : "Done\n");// Commit written value.// After setting any values, nvs_commit() must be called to ensure changes are written// to flash storage. Implementations may write to storage at other times,// but this is not guaranteed.printf("Committing updates in NVS ... ");err = nvs_commit(my_handle); //提交已写入的值到 NVS 中。printf((err != ESP_OK) ? "Failed!\n" : "Done\n");// Closenvs_close(my_handle); //关闭 NVS 句柄。}printf("\n");// Restart modulefor (int i = 10; i >= 0; i--) {printf("Restarting in %d seconds...\n", i);vTaskDelay(1000 / portTICK_PERIOD_MS);}printf("Restarting now.\n");fflush(stdout);esp_restart();
}
NVS 运行结果: