hdw-nvs.h File Reference

Detailed Description

Design Philosophy

The hdw-nvs component is a convenience wrapper for the IDF's Non-volatile Storage Library. Non-volatile storage (NVS) library is designed to store key-value pairs in flash.

The goal is to make reading and writing integer and blob values easy and simple for Swadge modes. The component takes care of opening and closing handles and error checking.

There are no checks for key collisions between Swadge modes, so it's wise to use a mode-specific prefix for that mode's keys.

Usage

You don't need to call initNvs() or deinitNvs(). The system does this the appropriate time.

readNvs32() and writeNvs32() can be used to read and write 32 bit integer values.

readNvsBlob() and writeNvsBlob() can be used to read and write binary blobs.

eraseNvsKey() can be used to erase a key, both 32 bit integer or blob. eraseNvs() can be used to erase all keys. It's dangerous to use, so be careful.

readNvsStats() and readAllNvsEntryInfos() can be used to read metadata about NVS.

Example

const char demoKey[] = "demo_high_score";
int32_t highScoreToWrite = 99999;
if(true == writeNvs32(demoKey, highScoreToWrite))
{
    int32_t highScoreToRead;
    if(true == readNvs32(demoKey, &highScoreToRead))
    {
        printf("High score in NVS is %ld\n", highScoreToRead);
    }
}

Go to the source code of this file.

Macros
#define	NVS_PART_NAME_MAX_SIZE   16
#define	NVS_KEY_NAME_MAX_SIZE   16
#define	NVS_NAMESPACE_NAME   "storage"

Functions
bool	initNvs (bool firstTry)
	Initialize the nonvolatile storage.
bool	deinitNvs (void)
	Deinitialize NVS.
bool	eraseNvs (void)
	Erase and re-initialize the nonvolatile storage.
bool	readNvs32 (const char *key, int32_t *outVal)
	Read a 32 bit value from NVS with a given string key.
bool	writeNvs32 (const char *key, int32_t val)
	Write a 32 bit value to NVS with a given string key.
bool	readNamespaceNvs32 (const char *namespace, const char *key, int32_t *outVal)
	Read a 32 bit value from NVS with a given string key.
bool	writeNamespaceNvs32 (const char *namespace, const char *key, int32_t val)
	Write a 32 bit value to NVS with a given string key.
bool	readNvsBlob (const char *key, void *out_value, size_t *length)
	Read a blob from NVS with a given string key. Typically, this should be called once with NULL passed for out_value, to get the value for length, then memory for out_value should be allocated, then this should be called again.
bool	writeNvsBlob (const char *key, const void *value, size_t length)
	Write a blob to NVS with a given string key.
bool	readNamespaceNvsBlob (const char *namespace, const char *key, void *out_value, size_t *length)
	Read a blob from NVS with a given string key. Typically, this should be called once with NULL passed for out_value, to get the value for length, then memory for out_value should be allocated, then this should be called again.
bool	writeNamespaceNvsBlob (const char *namespace, const char *key, const void *value, size_t length)
	Write a blob to NVS with a given string key.
bool	eraseNvsKey (const char *key)
	Delete the value with the given key from NVS.
bool	eraseNamespaceNvsKey (const char *namespace, const char *key)
	Delete the value with the given key from NVS.
bool	readNvsStats (nvs_stats_t *outStats)
	Read info about used memory in NVS.
bool	readAllNvsEntryInfos (nvs_stats_t *outStats, nvs_entry_info_t *outEntryInfos, size_t *numEntryInfos)
	Read info about each used entry in the default NVS namespace. Typically, this should be called once with NULL passed for outEntryInfos, to get the value for numEntryInfos, then memory for outEntryInfos should be allocated, then this should be called again.
bool	readNamespaceNvsEntryInfos (const char *namespace, nvs_stats_t *outStats, nvs_entry_info_t *outEntryInfos, size_t *numEntryInfos)
	Read info about each used entry in a specific NVS namespace. Typically, this should be called once with NULL passed for outEntryInfos, to get the value for numEntryInfos, then memory for outEntryInfos should be allocated, then this should be called again.
bool	nvsNamespaceInUse (const char *namespace)
	Quickly return whether or not any entries exist in a given NVS namespace.

Macro Definition Documentation

NVS_PART_NAME_MAX_SIZE

#define NVS_PART_NAME_MAX_SIZE   16

maximum length of partition name (excluding null terminator)

NVS_KEY_NAME_MAX_SIZE

#define NVS_KEY_NAME_MAX_SIZE   16

Maximal length of NVS key name (including null terminator)

NVS_NAMESPACE_NAME

#define NVS_NAMESPACE_NAME   "storage"

The default namespace used for NVS

Function Documentation

initNvs()

bool initNvs

(

bool

firstTry

)

Initialize the nonvolatile storage.

Parameters

firstTry

true if this is the first time NVS is initialized this boot, false otherwise

Returns

true if NVS was initialized and can be used, false if it failed

deinitNvs()

bool deinitNvs

(

void

)

Deinitialize NVS.

Returns

true if NVS was deinitialized, false if it failed

eraseNvs()

bool eraseNvs

(

void

)

Erase and re-initialize the nonvolatile storage.

Returns

true if NVS was erased and re-initialized and can be used, false if it failed

readNvs32()

bool readNvs32	(	const char *	key,
		int32_t *	outVal )

Read a 32 bit value from NVS with a given string key.

Parameters

key	The key for the value to read
outVal	The value that was read

Returns

true if the value was read, false if it was not

writeNvs32()

bool writeNvs32	(	const char *	key,
		int32_t	val )

Write a 32 bit value to NVS with a given string key.

Parameters

key	The key for the value to write
val	The value to write

Returns

true if the value was written, false if it was not

readNamespaceNvs32()

bool readNamespaceNvs32	(	const char *	namespace,
		const char *	key,
		int32_t *	outVal )

Read a 32 bit value from NVS with a given string key.

Parameters

namespace	The NVS namespace to use
key	The key for the value to read
outVal	The value that was read

Returns

true if the value was read, false if it was not

writeNamespaceNvs32()

bool writeNamespaceNvs32	(	const char *	namespace,
		const char *	key,
		int32_t	val )

Write a 32 bit value to NVS with a given string key.

Parameters

namespace	The NVS namespace to use
key	The key for the value to write
val	The value to write

Returns

true if the value was written, false if it was not

readNvsBlob()

bool readNvsBlob	(	const char *	key,
		void *	out_value,
		size_t *	length )

Read a blob from NVS with a given string key. Typically, this should be called once with NULL passed for out_value, to get the value for length, then memory for out_value should be allocated, then this should be called again.

Parameters

key	The key for the value to read
out_value	The value will be written to this memory. It must be allocated before calling readNvsBlob()
length	If out_value is NULL, this will be set to the length of the given key. Otherwise, it is the length of the blob to read.

Returns

true if the value was read, false if it was not

writeNvsBlob()

bool writeNvsBlob	(	const char *	key,
		const void *	value,
		size_t	length )

Write a blob to NVS with a given string key.

Parameters

key	The key for the value to write
value	The blob value to write
length	The length of the blob

Returns

true if the value was written, false if it was not

readNamespaceNvsBlob()

bool readNamespaceNvsBlob	(	const char *	namespace,
		const char *	key,
		void *	out_value,
		size_t *	length )

Read a blob from NVS with a given string key. Typically, this should be called once with NULL passed for out_value, to get the value for length, then memory for out_value should be allocated, then this should be called again.

Parameters

namespace	The NVS namespace to use
key	The key for the value to read
out_value	The value will be written to this memory. It must be allocated before calling readNvsBlob()
length	If out_value is NULL, this will be set to the length of the given key. Otherwise, it is the length of the blob to read.

Returns

true if the value was read, false if it was not

writeNamespaceNvsBlob()

bool writeNamespaceNvsBlob	(	const char *	namespace,
		const char *	key,
		const void *	value,
		size_t	length )

Write a blob to NVS with a given string key.

Parameters

namespace	The NVS namespace to use
key	The key for the value to write
value	The blob value to write
length	The length of the blob

Returns

true if the value was written, false if it was not

eraseNvsKey()

bool eraseNvsKey

(

const char *

key

)

Delete the value with the given key from NVS.

Parameters

key	The NVS key to be deleted

Returns

true if the value was deleted, false if it was not

eraseNamespaceNvsKey()

bool eraseNamespaceNvsKey	(	const char *	namespace,
		const char *	key )

Delete the value with the given key from NVS.

Parameters

namespace	The NVS namespace to use
key	The NVS key to be deleted

Returns

true if the value was deleted, false if it was not

readNvsStats()

bool readNvsStats

(

nvs_stats_t *

outStats

)

Read info about used memory in NVS.

Parameters

outStats

The NVS stats struct will be written to this memory. It must be allocated before calling readNvsStats()

Returns

true if the stats were read, false if it was not

readAllNvsEntryInfos()

bool readAllNvsEntryInfos	(	nvs_stats_t *	outStats,
		nvs_entry_info_t *	outEntryInfos,
		size_t *	numEntryInfos )

Read info about each used entry in the default NVS namespace. Typically, this should be called once with NULL passed for outEntryInfos, to get the value for numEntryInfos, then memory for outEntryInfos should be allocated, then this should be called again.

Parameters

outStats	If not NULL, the NVS stats struct will be written to this memory. It must be allocated before calling readAllNvsEntryInfos()
outEntryInfos	A pointer to an array of NVS entry info structs will be written to this memory
numEntryInfos	If outEntryInfos is NULL, this will be set to the length of the given key. Otherwise, it is the number of entry infos to read

Returns

true if the entry infos were read, false if they were not

readNamespaceNvsEntryInfos()

bool readNamespaceNvsEntryInfos	(	const char *	namespace,
		nvs_stats_t *	outStats,
		nvs_entry_info_t *	outEntryInfos,
		size_t *	numEntryInfos )

Read info about each used entry in a specific NVS namespace. Typically, this should be called once with NULL passed for outEntryInfos, to get the value for numEntryInfos, then memory for outEntryInfos should be allocated, then this should be called again.

Parameters

namespace	The name of the NVS namespace to use
outStats	If not NULL, the NVS stats struct will be written to this memory. It must be allocated before calling readAllNvsEntryInfos()
outEntryInfos	A pointer to an array of NVS entry info structs will be written to this memory
numEntryInfos	If outEntryInfos is NULL, this will be set to the length of the given key. Otherwise, it is the number of entry infos to read

Returns

true if the entry infos were read, false if they were not

nvsNamespaceInUse()

bool nvsNamespaceInUse

(

const char *

namespace

)

Quickly return whether or not any entries exist in a given NVS namespace.

Parameters

namespace

The namespace to check for any entries

Returns

true If there is one or more entry in the namespace

false If there are no entries in the namespace