Chapter 2. API Reference
wear levelling library.
Keys and values NVS operates on key-value pairs. Keys are ASCII strings; the maximum key length is currently
15 characters. Values can have one of the following types:
• integer types: uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t,
int64_t
• zero-terminated string
• variable length binary data (blob)
Note: String values are currently limited to 4000 bytes. This includes the null terminator. Blob values are limited
to 508,000 bytes or 97.6% of the partition size - 4000 bytes, whichever is lower.
Additional types, such as float and double might be added later.
Keys are required to be unique. Assigning a new value to an existing key works as follows:
• If the new value is of the same type as the old one, value is updated.
• If the new value has a different data type, an error is returned.
Data type check is also performed when reading a value. An error is returned if the data type of the read operation
does not match the data type of the value.
Namespaces To mitigate potential conflicts in key names between different components, NVS assigns each key-
value pair to one of namespaces. Namespace names follow the same rules as key names, i.e., the maximum length
is 15 characters. Namespace name is specified in the nvs_open() or nvs_open_from_partition call.
This call returns an opaque handle, which is used in subsequent calls to the nvs_get_*, nvs_set_*, and
nvs_commit() functions. This way, a handle is associated with a namespace, and key names will not collide
with same names in other namespaces. Please note that the namespaces with the same name in different NVS parti-
tions are considered as separate namespaces.
NVS iterators Iterators allow to list key-value pairs stored in NVS, based on specified partition name, namespace,
and data type.
There are the following functions available:
• nvs_entry_find() returns an opaque handle, which is used in subsequent calls to the
nvs_entry_next() and nvs_entry_info() functions.
• nvs_entry_next() returns iterator to the next key-value pair.
• nvs_entry_info() returns information about each key-value pair
If none or no other key-value pair was found for given criteria, nvs_entry_find() and nvs_entry_next()
return NULL. In that case, the iterator does not have to be released. If the iterator is no longer needed, you can
release it by using the function nvs_release_iterator().
Security, tampering, and robustness NVS is not directly compatible with the ESP32-S2 flash encryption sys-
tem. However, data can still be stored in encrypted form if NVS encryption is used together with ESP32-S2 flash
encryption. Please refer to NVS Encryption for more details.
If NVS encryption is not used, it is possible for anyone with physical access to the flash chip to alter, erase, or add
key-value pairs. With NVS encryption enabled, it is not possible to alter or add a key-value pair and get recognized
as a valid pair without knowing corresponding NVS encryption keys. However, there is no tamper-resistance against
the erase operation.
The library does try to recover from conditions when flash memory is in an inconsistent state. In particular, one
should be able to power off the device at any point and time and then power it back on. This should not result in loss
of data, except for the new key-value pair if it was being written at the moment of powering off. The library should
also be able to initialize properly with any random data present in flash memory.
Espressif Systems 706
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General