Swadge 2024 2.0.0
APIs to develop games for the Magfest Swadge
Loading...
Searching...
No Matches
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);
}
}
bool writeNvs32(const char *key, int32_t val)
Write a 32 bit value to NVS with a given string key.
Definition hdw-nvs.c:145
bool readNvs32(const char *key, int32_t *outVal)
Read a 32 bit value from NVS with a given string key.
Definition hdw-nvs.c:133

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
firstTrytrue 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
keyThe key for the value to read
outValThe 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
keyThe key for the value to write
valThe 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
namespaceThe NVS namespace to use
keyThe key for the value to read
outValThe 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
namespaceThe NVS namespace to use
keyThe key for the value to write
valThe 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
keyThe key for the value to read
out_valueThe value will be written to this memory. It must be allocated before calling readNvsBlob()
lengthIf 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
keyThe key for the value to write
valueThe blob value to write
lengthThe 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
namespaceThe NVS namespace to use
keyThe key for the value to read
out_valueThe value will be written to this memory. It must be allocated before calling readNvsBlob()
lengthIf 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
namespaceThe NVS namespace to use
keyThe key for the value to write
valueThe blob value to write
lengthThe 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
keyThe 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
namespaceThe NVS namespace to use
keyThe 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
outStatsThe 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
outStatsIf not NULL, the NVS stats struct will be written to this memory. It must be allocated before calling readAllNvsEntryInfos()
outEntryInfosA pointer to an array of NVS entry info structs will be written to this memory
numEntryInfosIf 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
namespaceThe name of the NVS namespace to use
outStatsIf not NULL, the NVS stats struct will be written to this memory. It must be allocated before calling readAllNvsEntryInfos()
outEntryInfosA pointer to an array of NVS entry info structs will be written to this memory
numEntryInfosIf 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
namespaceThe 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