非易失性存储库¶

简介¶

非易失性存储 (NVS) 库主要用于在 flash 中存储键值格式的数据。本文档将详细介绍 NVS 常用的一些概念。

底层存储¶

NVS 库通过调用 esp_partition API 使用主 flash 的部分空间，包括 data 类型和 nvs 子类型的所有分区。应用程序可调用 nvs_open() API 选择使用带有 nvs 标签的分区，也可以通过调用 nvs_open_from_partition() API 选择使用指定名称的任意分区。

NVS 库后续版本可能会增加其他存储器后端，来将数据保存至其他 flash 芯片（SPI 或 I2C 接口）、RTC 或 FRAM 中。

注解

如果 NVS 分区被截断（例如，更改分区表布局时），则应擦除分区内容。可以使用 ESP-IDF 构建系统中的 idf.py erase-flash 命令擦除 flash 上的所有内容。

注解

NVS 最适合存储一些较小的数据，而非字符串或二进制大对象 (BLOB) 等较大的数据。如需存储较大的 BLOB 或者字符串，请考虑使用基于磨损均衡库的 FAT 文件系统。

键值对¶

NVS 的操作对象为键值对，其中键是 ASCII 字符串，当前支持的最大键长为 15 个字符。值可以为以下几种类型：

整数型：uint8_t、int8_t、uint16_t、int16_t、uint32_t、int32_t、uint64_t 和 int64_t；
以 0 结尾的字符串；
可变长度的二进制数据 (BLOB)

注解

字符串值当前上限为 4000 字节，其中包括空终止符。BLOB 值上限为 508,000 字节或分区大小的 97.6% 减去 4000 字节，以较低值为准。

后续可能会增加对 float 和 double 等其他类型数据的支持。

键必须唯一。为现有的键写入新的值可能产生如下结果：

如果新旧值数据类型相同，则更新值；
如果新旧值数据类型不同，则返回错误。

读取值时也会执行数据类型检查。如果读取操作的数据类型与该值的数据类型不匹配，则返回错误。

命名空间¶

为了减少不同组件之间键名的潜在冲突，NVS 将每个键值对分配给一个命名空间。命名空间的命名规则遵循键名的命名规则，例如，最多可占 15 个字符。命名空间的名称在调用 nvs_open() 或 nvs_open_from_partition 中指定，调用后将返回一个不透明句柄，用于后续调用 nvs_get_*、nvs_set_* 和 nvs_commit 函数。这样，一个句柄关联一个命名空间，键名便不会与其他命名空间中相同键名冲突。请注意，不同 NVS 分区中具有相同名称的命名空间将被视为不同的命名空间。

NVS 迭代器¶

迭代器允许根据指定的分区名称、命名空间和数据类型轮询 NVS 中存储的键值对。

您可以使用以下函数，执行相关操作：

nvs_entry_find：返回一个不透明句柄，用于后续调用 nvs_entry_next 和 nvs_entry_info 函数；
nvs_entry_next：返回指向下一个键值对的迭代器；
nvs_entry_info：返回每个键值对的信息。

如果未找到符合标准的键值对，nvs_entry_find 和 nvs_entry_next 将返回 NULL，此时不必释放迭代器。若不再需要迭代器，可使用 nvs_release_iterator 释放迭代器。

安全性、篡改性及鲁棒性¶

NVS 与 ESP32-S3 flash 加密系统不直接兼容。但如果 NVS 加密与 ESP32-S3 flash 加密一起使用时，数据仍可以加密形式存储。详情请参阅 NVS 加密。

如果未启用 NVS 加密，任何对 flash 芯片有物理访问权限的用户都可以修改、擦除或添加键值对。NVS 加密启用后，如果不知道相应的 NVS 加密密钥，则无法修改或添加键值对并将其识别为有效键值对。但是，针对擦除操作没有相应的防篡改功能。

当 flash 处于不一致状态时，NVS 库会尝试恢复。在任何时间点关闭设备电源，然后重新打开电源，不会导致数据丢失；但如果关闭设备电源时正在写入新的键值对，这一键值对可能会丢失。该库还应当能对 flash 中的任意数据进行正确初始化。

NVS 加密¶

NVS 分区内存储的数据可使用 AES-XTS 进行加密，类似于 IEEE P1619 磁盘加密标准中提到的加密方式。为了实现加密，每个条目被均视为一个扇区，并将条目相对地址（相对于分区开头）传递给加密算法，用作扇区号。可通过 CONFIG_NVS_ENCRYPTION 启用 NVS 加密。NVS 加密所需的密钥存储于其他分区，并进行了 Flash 加密。因此，在使用 NVS 加密前应先启用 Flash 加密。

启用 Flash 加密时，默认启用 NVS 加密。这是因为 Wi-Fi 驱动在默认的 NVS 分区中存储了凭证（如 SSID 和口令）。启用平台级加密后，仍需将它们作为默认选项进行加密。

使用 NVS 加密，分区表必须包含 NVS 密钥分区。在分区表选项 (menuconfig->Partition Table) 下，为 NVS 加密提供了两个包含 NVS 密钥分区的分区表，您可以通过工程配置菜单 (idf.py menuconfig) 进行选择。请参考 security/flash_encryption 中的例子，了解如何配置和使用 NVS 加密功能。

NVS 密钥分区¶

应用程序如果想使用 NVS 加密，则需要编译进一个类型为 data，子类型为 key 的密钥分区。该分区应标记为已加密且最小为 4096 字节。如需了解更多详细信息，请参考分区表。在分区表选项 (menuconfig->Partition Table) 下提供了两个包含 NVS 密钥分区的额外分区表，可以直接用于 NVS 加密。这些分区的具体结构见下表：

+-----------+--------------+-------------+----+
|              XTS encryption key (32)        |
+---------------------------------------------+
|              XTS tweak key (32)             |
+---------------------------------------------+
|                  CRC32 (4)                  |
+---------------------------------------------+

可以通过以下两种方式生成 NVS 密钥分区中的 XTS 加密密钥：

在 ESP 芯片上生成密钥：

启用 NVS 加密时，可用 nvs_flash_init() API 函数来初始化加密的默认 NVS 分区，在内部生成 ESP 芯片上的 XTS 加密密钥。在找到 NVS 密钥分区后，API 函数利用 nvs_flash/include/nvs_flash.h 提供的 nvs_flash_generate_keys() 函数，自动生成并存储该分区中的 NVS 密钥。只有当各自的密钥分区为空时，才会生成并存储新的密钥。可以借助 nvs_flash_secure_init_partition() 用同一个密钥分区来读取安全配置，以初始化一个定制的加密 NVS 分区。

API 函数 nvs_flash_secure_init() 和 nvs_flash_secure_init_partition() 不在内部产生密钥。当这些 API 函数用于初始化加密的 NVS 分区时，可以在启动后使用 nvs_flash.h 提供的 nvs_flash_generate_keys() API 函数生成密钥，以加密的形式把密钥写到密钥分区上。
使用预先生成的密钥分区：
若 NVS 密钥分区中的密钥不是由应用程序生成，则需要使用预先生成的密钥分区。可以使用 NVS 分区生成工具生成包含 XTS 加密密钥的 NVS 密钥分区。用户可以借助以下两个命令，将预先生成的密钥分区储存在 flash 上：

i) 建立并烧录分区表
idf.py partition_table partition_table-flash
1. 调用 parttool.py，将密钥存储在 flash 上的 NVS 密钥分区中。详见 :doc:` 分区表 </api-guides/partition-tables>` 的分区工具部分。
  
  parttool.py –port /dev/ttyUSB0 –partition-table-offset “nvs_key partition offset” write_partition –partition-name=”name of nvs_key partition” –input “nvs_key partition”

由于分区已标记为已加密，而且启用了 Flash 加密，引导程序在首次启动时将使用 flash 加密对密钥分区进行加密。

应用程序可以使用不同的密钥对不同的 NVS 分区进行加密，这样就会需要多个加密密钥分区。应用程序应为加解密操作提供正确的密钥或密钥分区。

加密读取/写入¶

nvs_get_* 和 nvs_set_* 等 NVS API 函数同样可以对 NVS 加密分区执行读写操作。

加密默认的 NVS 分区： 无需额外步骤即可启用默认 NVS 分区的加密。启用 CONFIG_NVS_ENCRYPTION 时， nvs_flash_init() API 函数会在内部使用找到的第一个 NVS 密钥分区执行额外步骤，以启用默认 NVS 分区的加密（详情请参考 API 文档）。另外，nvs_flash_secure_init() API 函数也可以用来启用默认 NVS 分区的加密。

加密一个自定义的 NVS 分区： 使用 nvs_flash_secure_init_partition() API 函数启用自定义 NVS 分区的加密，而非 nvs_flash_init_partition()。

使用 nvs_flash_secure_init() 和 nvs_flash_secure_init_partition() API 函数时，应用程序如需在加密状态下执行 NVS 读写操作，应遵循以下步骤：

使用 esp_partition_find* API 查找密钥分区和 NVS 数据分区；

使用 nvs_flash_read_security_cfg 或 nvs_flash_generate_keys API 填充 nvs_sec_cfg_t 结构；

使用 nvs_flash_secure_init 或 nvs_flash_secure_init_partition API 初始化 NVS flash 分区；

使用 nvs_open 或 nvs_open_from_partition API 打开命名空间；

使用 nvs_get_* 或 nvs_set_* API 执行 NVS 读取/写入操作；

使用 nvs_flash_deinit API 释放已初始化的 NVS 分区。

NVS 分区生成程序¶

NVS 分区生成程序帮助生成 NVS 分区二进制文件，可使用烧录程序将二进制文件单独烧录至特定分区。烧录至分区上的键值对由 CSV 文件提供，详情请参考 NVS 分区生成程序。

应用示例¶

ESP-IDF storage 目录下提供了数个代码示例：

storage/nvs_rw_value

演示如何读取及写入 NVS 单个整数值。

此示例中的值表示 ESP32-S3 模组重启次数。NVS 中数据不会因为模组重启而丢失，因此只有将这一值存储于 NVS 中，才能起到重启次数计数器的作用。

该示例也演示了如何检测读取/写入操作是否成功，以及某个特定值是否在 NVS 中尚未初始化。诊断程序以纯文本形式提供，帮助您追踪程序流程，及时发现问题。

storage/nvs_rw_blob

演示如何读取及写入 NVS 单个整数值和 Blob（二进制大对象），并在 NVS 中存储这一数值，即便 ESP32-S3 模组重启也不会消失。

value - 记录 ESP32-S3 模组软重启次数和硬重启次数。

blob - 内含记录模组运行次数的表格。此表格将被从 NVS 读取至动态分配的 RAM 上。每次手动软重启后，表格内运行次数即增加一次，新加的运行次数被写入 NVS。下拉 GPIO0 即可手动软重启。

该示例也演示了如何执行诊断程序以检测读取/写入操作是否成功。

storage/nvs_rw_value_cxx

这个例子与 storage/nvs_rw_value 完全一样，只是使用了 C++ 的 NVS 处理类。

内部实现¶

键值对日志¶

NVS 按顺序存储键值对，新的键值对添加在最后。因此，如需更新某一键值对，实际是在日志最后增加一对新的键值对，同时将旧的键值对标记为已擦除。

页面和条目¶

NVS 库在其操作中主要使用两个实体：页面和条目。页面是一个逻辑结构，用于存储部分的整体日志。逻辑页面对应 flash 的一个物理扇区，正在使用中的页面具有与之相关联的 序列号。序列号赋予了页面顺序，较高的序列号对应较晚创建的页面。页面有以下几种状态：

空或未初始化: 页面对应的 flash 扇区为空白状态（所有字节均为 0xff）。此时，页面未存储任何数据且没有关联的序列号。
活跃状态: 此时 flash 已完成初始化，页头部写入 flash，页面已具备有效序列号。页面中存在一些空条目，可写入数据。任意时刻，至多有一个页面处于活跃状态。
写满状态: Flash 已写满键值对，状态不再改变。用户无法向写满状态下的页面写入新键值对，但仍可将一些键值对标记为已擦除。
擦除状态: 未擦除的键值对将移至其他页面，以便擦除当前页面。这一状态仅为暂时性状态，即 API 调用返回时，页面应脱离这一状态。如果设备突然断电，下次开机时，设备将继续把未擦除的键值对移至其他页面，并继续擦除当前页面。
损坏状态: 页头部包含无效数据，无法进一步解析该页面中的数据，因此之前写入该页面的所有条目均无法访问。相应的 flash 扇区并不会被立即擦除，而是与其他处于未初始化状态的扇区一起等待后续使用。这一状态可能对调试有用。

Flash 扇区映射至逻辑页面并没有特定的顺序，NVS 库会检查存储在 flash 扇区的页面序列号，并根据序列号组织页面。

+--------+     +--------+     +--------+     +--------+
| Page 1 |     | Page 2 |     | Page 3 |     | Page 4 |
| Full   +---> | Full   +---> | Active |     | Empty  |   <- 状态
| #11    |     | #12    |     | #14    |     |        |   <- 序列号
+---+----+     +----+---+     +----+---+     +---+----+
    |               |              |             |
    |               |              |             |
    |               |              |             |
+---v------+  +-----v----+  +------v---+  +------v---+
| Sector 3 |  | Sector 0 |  | Sector 2 |  | Sector 1 |    <- 物理扇区
+----------+  +----------+  +----------+  +----------+

页面结构¶

当前，我们假设 flash 扇区大小为 4096 字节，并且 ESP32-S3 flash 加密硬件在 32 字节块上运行。未来有可能引入一些编译时可配置项（可通过 menuconfig 进行配置），以适配具有不同扇区大小的 flash 芯片。但目前尚不清楚 SPI flash 驱动和 SPI flash cache 之类的系统组件是否支持其他扇区大小。

页面由头部、条目状态位图和条目三部分组成。为了实现与 ESP32-S3 flash 加密功能兼容，条目大小设置为 32 字节。如果键值为整数型，条目则保存一个键值对；如果键值为字符串或 BLOB 类型，则条目仅保存一个键值对的部分内容（更多信息详见条目结构描述）。

页面结构如下图所示，括号内数字表示该部分的大小（以字节为单位）。

+-----------+--------------+-------------+-------------------------+
| State (4) | Seq. no. (4) | version (1) | Unused (19) | CRC32 (4) |   页头部 (32)
+-----------+--------------+-------------+-------------------------+
|                Entry state bitmap (32)                           |
+------------------------------------------------------------------+
|                       Entry 0 (32)                               |
+------------------------------------------------------------------+
|                       Entry 1 (32)                               |
+------------------------------------------------------------------+
/                                                                  /
/                                                                  /
+------------------------------------------------------------------+
|                       Entry 125 (32)                             |
+------------------------------------------------------------------+

头部和条目状态位图写入 flash 时不加密。如果启用了 ESP32-S3 flash 加密功能，则条目写入 flash 时将会加密。

通过将 0 写入某些位可以定义页面状态值，表示状态改变。因此，如果需要变更页面状态，并不一定要擦除页面，除非要将其变更为擦除状态。

头部中的 version 字段反映了所用的 NVS 格式版本。为实现向后兼容，版本升级从 0xff 开始依次递减（例如，version-1 为 0xff，version-2 为 0xfe，以此类推）。

头部中 CRC32 值是由不包含状态值的条目计算所得（4 到 28 字节）。当前未使用的条目用 0xff 字节填充。

条目结构和条目状态位图的详细信息见下文描述。

条目和条目状态位图¶

每个条目可处于以下三种状态之一，每个状态在条目状态位图中用两位表示。位图中的最后四位 (256 - 2 * 126) 未使用。

空 (2’b11): 条目还未写入任何内容，处于未初始化状态（全部字节为 0xff）。
写入（2’b10）: 一个键值对（或跨多个条目的键值对的部分内容）已写入条目中。
擦除（2’b00）: 条目中的键值对已丢弃，条目内容不再解析。

条目结构¶

如果键值类型为基础类型，即 1 - 8 个字节长度的整数型，条目将保存一个键值对；如果键值类型为字符串或 BLOB 类型，条目将保存整个键值对的部分内容。另外，如果键值为字符串类型且跨多个条目，则键值所跨的所有条目均保存在同一页面。BLOB 则可以切分为多个块，实现跨多个页面。BLOB 索引是一个附加的固定长度元数据条目，用于追踪 BLOB 块。目前条目仍支持早期 BLOB 格式（可读取可修改），但这些 BLOB 一经修改，即以新格式储存至条目。

+--------+----------+----------+----------------+-----------+---------------+----------+
| NS (1) | Type (1) | Span (1) | ChunkIndex (1) | CRC32 (4) |    Key (16)   | Data (8) |
+--------+----------+----------+----------------+-----------+---------------+----------+

                                         Primitive  +--------------------------------+
                                        +-------->  |     Data (8)                   |
                                        | Types     +--------------------------------+
                   +-> Fixed length --
                   |                    |           +---------+--------------+---------------+-------+
                   |                    +-------->  | Size(4) | ChunkCount(1)| ChunkStart(1) | Rsv(2)|
    Data format ---+                    BLOB Index  +---------+--------------+---------------+-------+
                   |
                   |                             +----------+---------+-----------+
                   +->   Variable length   -->   | Size (2) | Rsv (2) | CRC32 (4) |
                        (Strings, BLOB Data)     +----------+---------+-----------+

条目结构中各个字段含义如下：

命名空间 (NS, NameSpace)

该条目的命名空间索引，详细信息参见命名空间实现章节。

类型 (Type)

一个字节表示的值的数据类型，nvs_flash/include/nvs_handle.hpp 下的 ItemType 枚举了可能的类型。

跨度 (Span)

该键值对所用的条目数量。如果键值为整数型，条目数量即为 1。如果键值为字符串或 BLOB，则条目数量取决于值的长度。

块索引 (ChunkIndex)

用于存储 BLOB 类型数据块的索引。如果键值为其他数据类型，则此处索引应写入 0xff。

CRC32

对条目下所有字节进行校验后，所得的校验和（CRC32 字段不计算在内）。

键 (Key)

即以零结尾的 ASCII 字符串，字符串最长为 15 字节，不包含最后一个字节的零终止符。

数据 (Data)

如果键值类型为整数型，则数据字段仅包含键值。如果键值小于八个字节，使用 0xff 填充未使用的部分（右侧）。

如果键值类型为 BLOB 索引条目，则该字段的八个字节将保存以下数据块信息：

块大小
整个 BLOB 数据的大小（以字节为单位）。该字段仅用于 BLOB 索引类型条目。
ChunkCount
存储过程中 BLOB 分成的数据块总量。该字段仅用于 BLOB 索引类型条目。
ChunkStart
BLOB 第一个数据块的块索引，后续数据块索引依次递增，步长为 1。该字段仅用于 BLOB 索引类型条目。

如果键值类型为字符串或 BLOB 数据块，数据字段的这八个字节将保存该键值的一些附加信息，如下所示：

数据大小
实际数据的大小（以字节为单位）。如果键值类型为字符串，此字段也应将零终止符包含在内。此字段仅用于字符串和 BLOB 类型条目。
CRC32
数据所有字节的校验和，该字段仅用于字符串和 BLOB 类型条目。

可变长度值（字符串和 BLOB）写入后续条目，每个条目 32 字节。第一个条目的 Span 字段将指明使用了多少条目。

命名空间¶

如上所述，每个键值对属于一个命名空间。命名空间标识符（字符串）也作为键值对的键，存储在索引为 0 的命名空间中。与这些键对应的值就是这些命名空间的索引。

+-------------------------------------------+
| NS=0 Type=uint8_t Key="wifi" Value=1      |   Entry describing namespace "wifi"
+-------------------------------------------+
| NS=1 Type=uint32_t Key="channel" Value=6  |   Key "channel" in namespace "wifi"
+-------------------------------------------+
| NS=0 Type=uint8_t Key="pwm" Value=2       |   Entry describing namespace "pwm"
+-------------------------------------------+
| NS=2 Type=uint16_t Key="channel" Value=20 |   Key "channel" in namespace "pwm"
+-------------------------------------------+

条目哈希列表¶

为了减少对 flash 执行的读操作次数，Page 类对象均设有一个列表，包含一对数据：条目索引和条目哈希值。该列表可大大提高检索速度，而无需迭代所有条目并逐个从 flash 中读取。Page::findItem 首先从哈希列表中检索条目哈希值，如果条目存在，则在页面内给出条目索引。由于哈希冲突，在哈希列表中检索条目哈希值可能会得到不同的条目，对 flash 中条目再次迭代可解决这一冲突。

哈希列表中每个节点均包含一个 24 位哈希值和 8 位条目索引。哈希值根据条目命名空间、键名和块索引由 CRC32 计算所得，计算结果保留 24 位。为减少将 32 位条目存储在链表中的开销，链表采用了数组的双向链表。每个数组占用 128 个字节，包含 29 个条目、两个链表指针和一个 32 位计数字段。因此，每页额外需要的 RAM 最少为 128 字节，最多为 640 字节。

API 参考¶

Header File¶

components/nvs_flash/include/nvs_flash.h

Functions¶

esp_err_t nvs_flash_init(void)¶

Initialize the default NVS partition.

This API initialises the default NVS partition. The default NVS partition is the one that is labeled “nvs” in the partition table.

When “NVS_ENCRYPTION” is enabled in the menuconfig, this API enables the NVS encryption for the default NVS partition as follows

Read security configurations from the first NVS key partition listed in the partition table. (NVS key partition is any “data” type partition which has the subtype value set to “nvs_keys”)
If the NVS key partiton obtained in the previous step is empty, generate and store new keys in that NVS key partiton.
Internally call “nvs_flash_secure_init()” with the security configurations obtained/generated in the previous steps.

Post initialization NVS read/write APIs remain the same irrespective of NVS encryption.

Return

ESP_OK if storage was successfully initialized.
ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated)
ESP_ERR_NOT_FOUND if no partition with label “nvs” is found in the partition table
ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
one of the error codes from the underlying flash storage driver
error codes from nvs_flash_read_security_cfg API (when “NVS_ENCRYPTION” is enabled).
error codes from nvs_flash_generate_keys API (when “NVS_ENCRYPTION” is enabled).
error codes from nvs_flash_secure_init_partition API (when “NVS_ENCRYPTION” is enabled) .

esp_err_t nvs_flash_init_partition(const char *partition_label)¶

Initialize NVS flash storage for the specified partition.

Return

ESP_OK if storage was successfully initialized.
ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated)
ESP_ERR_NOT_FOUND if specified partition is not found in the partition table
ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
one of the error codes from the underlying flash storage driver

Parameters

[in] partition_label: Label of the partition. Must be no longer than 16 characters.

esp_err_t nvs_flash_init_partition_ptr(const esp_partition_t *partition)¶

Initialize NVS flash storage for the partition specified by partition pointer.

Return

ESP_OK if storage was successfully initialized
ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated)
ESP_ERR_INVALID_ARG in case partition is NULL
ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
one of the error codes from the underlying flash storage driver

Parameters

[in] partition: pointer to a partition obtained by the ESP partition API.

esp_err_t nvs_flash_deinit(void)¶

Deinitialize NVS storage for the default NVS partition.

Default NVS partition is the partition with “nvs” label in the partition table.

Return

ESP_OK on success (storage was deinitialized)
ESP_ERR_NVS_NOT_INITIALIZED if the storage was not initialized prior to this call

esp_err_t nvs_flash_deinit_partition(const char *partition_label)¶

Deinitialize NVS storage for the given NVS partition.

Return

ESP_OK on success
ESP_ERR_NVS_NOT_INITIALIZED if the storage for given partition was not initialized prior to this call

Parameters

[in] partition_label: Label of the partition

esp_err_t nvs_flash_erase(void)¶

Erase the default NVS partition.

Erases all contents of the default NVS partition (one with label “nvs”).

Note

If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to be initialized again to be used.

Return

ESP_OK on success
ESP_ERR_NOT_FOUND if there is no NVS partition labeled “nvs” in the partition table
different error in case de-initialization fails (shouldn’t happen)

esp_err_t nvs_flash_erase_partition(const char *part_name)¶

Erase specified NVS partition.

Erase all content of a specified NVS partition

Note

If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to be initialized again to be used.

Return

ESP_OK on success
ESP_ERR_NOT_FOUND if there is no NVS partition with the specified name in the partition table
different error in case de-initialization fails (shouldn’t happen)

Parameters

[in] part_name: Name (label) of the partition which should be erased

esp_err_t nvs_flash_erase_partition_ptr(const esp_partition_t *partition)¶

Erase custom partition.

Erase all content of specified custom partition.

Note

If the partition is initialized, this function first de-initializes it. Afterwards, the partition has to be initialized again to be used.

Return

ESP_OK on success
ESP_ERR_NOT_FOUND if there is no partition with the specified parameters in the partition table
ESP_ERR_INVALID_ARG in case partition is NULL
one of the error codes from the underlying flash storage driver

Parameters

[in] partition: pointer to a partition obtained by the ESP partition API.

esp_err_t nvs_flash_secure_init(nvs_sec_cfg_t *cfg)¶

Initialize the default NVS partition.

This API initialises the default NVS partition. The default NVS partition is the one that is labeled “nvs” in the partition table.

Return

ESP_OK if storage has been initialized successfully.
ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated)
ESP_ERR_NOT_FOUND if no partition with label “nvs” is found in the partition table
ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
one of the error codes from the underlying flash storage driver

Parameters

[in] cfg: Security configuration (keys) to be used for NVS encryption/decryption. If cfg is NULL, no encryption is used.

esp_err_t nvs_flash_secure_init_partition(const char *partition_label, nvs_sec_cfg_t *cfg)¶

Initialize NVS flash storage for the specified partition.

Return

ESP_OK if storage has been initialized successfully.
ESP_ERR_NVS_NO_FREE_PAGES if the NVS storage contains no empty pages (which may happen if NVS partition was truncated)
ESP_ERR_NOT_FOUND if specified partition is not found in the partition table
ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
one of the error codes from the underlying flash storage driver

Parameters

[in] partition_label: Label of the partition. Note that internally, a reference to passed value is kept and it should be accessible for future operations
[in] cfg: Security configuration (keys) to be used for NVS encryption/decryption. If cfg is null, no encryption/decryption is used.

esp_err_t nvs_flash_generate_keys(const esp_partition_t *partition, nvs_sec_cfg_t *cfg)¶

Generate and store NVS keys in the provided esp partition.

Return

-ESP_OK, if cfg was read successfully; -ESP_INVALID_ARG, if partition or cfg; -or error codes from esp_partition_write/erase APIs.

Parameters

[in] partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
[out] cfg: Pointer to nvs security configuration structure. Pointer must be non-NULL. Generated keys will be populated in this structure.

esp_err_t nvs_flash_read_security_cfg(const esp_partition_t *partition, nvs_sec_cfg_t *cfg)¶

Read NVS security configuration from a partition.

Note

Provided partition is assumed to be marked ‘encrypted’.

Return

-ESP_OK, if cfg was read successfully; -ESP_INVALID_ARG, if partition or cfg; -ESP_ERR_NVS_KEYS_NOT_INITIALIZED, if the partition is not yet written with keys. -ESP_ERR_NVS_CORRUPT_KEY_PART, if the partition containing keys is found to be corrupt -or error codes from esp_partition_read API.

Parameters

[in] partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
[out] cfg: Pointer to nvs security configuration structure. Pointer must be non-NULL.

Structures¶

struct nvs_sec_cfg_t¶

Key for encryption and decryption.

Public Members

uint8_t eky[NVS_KEY_SIZE]¶: XTS encryption and decryption key

uint8_t tky[NVS_KEY_SIZE]¶: XTS tweak key

Macros¶

NVS_KEY_SIZE¶

Header File¶

components/nvs_flash/include/nvs.h

Functions¶

esp_err_t nvs_set_i8(nvs_handle_t handle, const char *key, int8_t value)¶

set int8_t value for given key

Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is called.

Return

ESP_OK if value was set successfully
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
ESP_ERR_NVS_INVALID_NAME if key name doesn’t satisfy constraints
ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage to save the value
ESP_ERR_NVS_REMOVE_FAILED if the value wasn’t updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesn’t fail again.

Parameters

[in] handle: Handle obtained from nvs_open function. Handles that were opened read only cannot be used.
[in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn’t be empty.
[in] value: The value to set.

esp_err_t nvs_set_u8(nvs_handle_t handle, const char *key, uint8_t value)¶

set uint8_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_i16(nvs_handle_t handle, const char *key, int16_t value)¶

set int16_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_u16(nvs_handle_t handle, const char *key, uint16_t value)¶

set uint16_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_i32(nvs_handle_t handle, const char *key, int32_t value)¶

set int32_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_u32(nvs_handle_t handle, const char *key, uint32_t value)¶

set uint32_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_i64(nvs_handle_t handle, const char *key, int64_t value)¶

set int64_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_u64(nvs_handle_t handle, const char *key, uint64_t value)¶

set uint64_t value for given key

This function is the same as nvs_set_i8 except for the data type.

esp_err_t nvs_set_str(nvs_handle_t handle, const char *key, const char *value)¶

set string for given key

Set value for the key, given its name. Note that the actual storage will not be updated until nvs_commit is called.

Return

ESP_OK if value was set successfully
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
ESP_ERR_NVS_INVALID_NAME if key name doesn’t satisfy constraints
ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the underlying storage to save the value
ESP_ERR_NVS_REMOVE_FAILED if the value wasn’t updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesn’t fail again.
ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long

Parameters

[in] handle: Handle obtained from nvs_open function. Handles that were opened read only cannot be used.
[in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn’t be empty.
[in] value: The value to set. For strings, the maximum length (including null character) is 4000 bytes, if there is one complete page free for writing. This decreases, however, if the free space is fragmented.

esp_err_t nvs_get_i8(nvs_handle_t handle, const char *key, int8_t *out_value)¶

get int8_t value for given key

These functions retrieve value for the key, given its name. If key does not exist, or the requested variable type doesn’t match the type which was used when setting a value, an error is returned.

In case of any error, out_value is not modified.

out_value has to be a pointer to an already allocated variable of the given type.

// 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.

Return

ESP_OK if the value was retrieved successfully
ESP_ERR_NVS_NOT_FOUND if the requested key doesn’t exist
ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
ESP_ERR_NVS_INVALID_NAME if key name doesn’t satisfy constraints
ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data

Parameters

[in] handle: Handle obtained from nvs_open function.
[in] key: Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn’t be empty.
out_value: Pointer to the output value. May be NULL for nvs_get_str and nvs_get_blob, in this case required length will be returned in length argument.

esp_err_t nvs_get_u8(nvs_handle_t handle, const char *key, uint8_t *out_value)¶

get uint8_t value for given key