NVS APIs

NVS

The NVS component provides a simple class representing an NVS controller.

NVSHandle

The NVSHandle class manages individual NVS storage handles, allowing for scoped control over specific NVS namespaces. It simplifies operations like reading, writing, and committing key-value pairs within these namespaces.

Code examples for the NVS and NVSHandle API are provided in the nvs example folder.

NVS Example

API Reference

Header File

components/nvs/include/nvs.hpp

Classes

class Nvs : public espp::BaseComponent 

Class to interface with the NVS.

This class is used to interface with the ESP NVS system. It is used to init and erase the partition, or get and set variables

NVS Example

    std::error_code ec;
    uint8_t counter = 0;
    espp::Nvs nvs;
    nvs.init(ec);
    ec.clear();
    // note that the namespace and key strings must be <= 15 characters
    nvs.get_or_set_var("system", "reset_counter", counter, counter, ec);
    ec.clear();
    fmt::print("Reset Counter = {}\n", counter);

    bool flag = false;
    nvs.get_or_set_var("other-namespace", "flag", flag, flag, ec);
    ec.clear();
    fmt::print("Got / Set Flag = {}\n", flag);
    // now toggle the flag
    flag = !flag;
    nvs.set_var("other-namespace", "flag", flag, ec);
    ec.clear();
    fmt::print("Toggled Flag = {}\n", flag);

    // test getting a handle to one of the NVS namespaces
    espp::NvsHandle system_handle = nvs.get_handle("system", ec);
    if (ec) {
      fmt::print("Error getting handle: {}\n", ec.message());
    } else {
      fmt::print("Got handle to 'system' namespace\n");
    }
    ec.clear();
    // test getting a handle to a new (non-existent) namespace
    espp::NvsHandle new_handle = nvs.get_handle("new-namespace", ec);
    if (ec) {
      fmt::print("Error getting handle to new namespace: {}\n", ec.message());
    } else {
      fmt::print("Got handle to 'new-namespace'\n");
    }
    ec.clear();

    // test delayed initialization of nvs handle
    espp::NvsHandle test_handle;
    test_handle.init("system", ec);
    // now test getting a variable from the copied handle
    test_handle.get("reset_counter", counter, ec);
    if (ec) {
      fmt::print("Error getting variable from delay-inited handle: {}\n", ec.message());
    } else {
      fmt::print("Got reset_counter from delay-inited handle: {}\n", counter);
    }

    // test protection against really long namespace names (length > 15)
    std::string long_ns(16, 'a');
    nvs.get_or_set_var(long_ns, "flag", flag, flag, ec);
    if (ec) {
      fmt::print("Expected error: {}\n", ec.message());
    } else {
      fmt::print("Unexpected success\n");
    }
    ec.clear();

    // test getting a non-existent key
    nvs.get_var("system", "not-here", counter, ec);
    if (ec) {
      fmt::print("Expected error: {}\n", ec.message());
    } else {
      fmt::print("Unexpected success\n");
    }
    ec.clear();

    // test getting a string value
    std::string str;
    nvs.get_or_set_var("system", "string", str, std::string("default"), ec);
    if (ec) {
      fmt::print("Error: {}\n", ec.message());
    } else {
      fmt::print("String = '{}'\n", str);
    }
    ec.clear();

    // test setting a string value
    str = "hello";
    nvs.set_var("system", "string", str, ec);
    if (ec) {
      fmt::print("Error: {}\n", ec.message());
    } else {
      fmt::print("String set to '{}'\n", str);
    }
    ec.clear();

    // test getting the string value again
    nvs.get_var("system", "string", str, ec);
    if (ec) {
      fmt::print("Error: {}\n", ec.message());
    } else {
      fmt::print("String = '{}'\n", str);
    }
    ec.clear();

    // test erasing the string value
    nvs.erase("system", "string", ec);
    if (ec) {
      fmt::print("Error: {}\n", ec.message());
    } else {
      fmt::print("String erased\n");
    }
    ec.clear();

    // now test getting it again to ensure it was erased
    nvs.get_var("system", "string", str, ec);
    if (ec) {
      fmt::print("Sucess, got expected error when reading erased value: {}\n", ec.message());
    } else {
      fmt::print("Failure, got unexpected success when reading erased value\n");
    }
    ec.clear();

    counter++;

    if (counter > 10) {
      // test erasing the whole namespace
      nvs.erase("system", ec);
      if (ec) {
        fmt::print("Error: {}\n", ec.message());
      } else {
        fmt::print("Namespace erased\n");
      }
      ec.clear();

      // now erase the wole nvs partition
      nvs.erase(ec);
      nvs.init(ec);
      counter = 0;
      fmt::print("NVS erased, Reset Counter set to 0\n");
      ec.clear();
    }

    nvs.set_var("system", "reset_counter", counter, ec);
    fmt::print("Next Reset Counter will be = {}\n", counter);
    fmt::print("NVS example complete!\n");

Public Functions

inline explicit Nvs(): Construct a new NVS object.

inline void init(std::error_code &ec)

Initialize the NVS.

If the flash init fails because of no free pages or new version, it erases the NVS and re-initializes

Parameters:: ec – [out] Saves a std::error_code representing success or failure

inline bool erase(std::error_code &ec)

Erase the NVS.

Parameters:: ec – [out] Saves a std::error_code representing success or failure

inline bool erase(std::string_view ns_name, std::error_code &ec)

Erase a namespace from the NVS.

Parameters:

ns_name – [in] Namespace of the variable to erase
ec – [out] Saves a std::error_code representing success or failure

inline bool erase(std::string_view ns_name, std::string_view key, std::error_code &ec)

Erase a key from the NVS.

Parameters:

ns_name – [in] Namespace of the variable to erase
key – [in] NVS Key of the variable to erase
ec – [out] Saves a std::error_code representing success or failure

inline NvsHandle get_handle(std::string_view ns_name, std::error_code &ec)

Get a handle to the given namespace.

Parameters:

ns_name – [in] Namespace of the variable to get a handle to
ec – [out] Saves a std::error_code representing success or failure

Returns:

NvsHandle for the given namespace

template<typename T> inline void set_var(std::string_view ns_name, std::string_view key, T value, std::error_code &ec)

Save a variable in the NVS and commit.

Parameters:

ns_name – [in] Namespace of the variable to save
key – [in] NVS Key of the variable to save
value – [in] Variable to save
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void get_var(std::string_view ns_name, std::string_view key, T &value, std::error_code &ec)

Reads a variable from the NVS.

Parameters:

ns_name – [in] Namespace of the variable to read
key – [in] NVS Key of the variable to read
value – [out] Variable to read
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void get_or_set_var(std::string_view ns_name, std::string_view key, T &value, T default_value, std::error_code &ec)

Reads a variable from the NVS.

Parameters:

ns_name – [in] Namespace of the variable to read
key – [in] NVS Key of the variable to read
value – [out] Variable to read
default_value – [in] If the key isn’t found in the NVS, this value is saved to NVS
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void set_var(const char *ns_name, const char *key, T value, std::error_code &ec)

Save a variable in the NVS and commit.

Saves the key/variable pair, and commits the NVS.

Parameters:

ns_name – [in] Namespace of the variable to save
key – [in] NVS Key of the variable to save
value – [in] Variable to save
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void get_var(const char *ns_name, const char *key, T &value, std::error_code &ec)

Reads a variable from the NVS.

Read the key/variable pair

Parameters:

ns_name – [in] Namespace of the variable to read
key – [in] NVS Key of the variable to read
value – [out] Variable to read
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void get_or_set_var(const char *ns_name, const char *key, T &value, T default_value, std::error_code &ec)

Reads a variable from the NVS.

Read the key/variable pair, If the key isn’t found in the NVS, default_value is saved to NVS

Parameters:

ns_name – [in] Namespace of the variable to read
key – [in] NVS Key of the variable to read
value – [out] Variable to read
default_value – [in] If the key isn’t found in the NVS, this value is saved to NVS
ec – [out] Saves a std::error_code representing success or failure

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:: rate_limit – The rate limit to use for the logger

Header File

components/nvs/include/nvs_handle_espp.hpp

Classes

class NvsHandle : public espp::BaseComponent 

Class to manage NVS handles.

This class provides an interface for managing specific ESP NVS namespaces, enabling operations like reading, writing, and committing key-value pairs. It encapsulates all direct interactions with the NVS to ensure proper error handling and namespace management.

NvsHandle Example

    // Init NVS
    std::error_code ec;
    espp::Nvs nvs;
    nvs.init(ec);
    ec.clear();

    // Open
    fmt::print("\nOpening Non-Volatile Storage (NVS) handle... ");
    // Handle will automatically close when going out of scope or when it's reset.
    espp::NvsHandle storage("storage", ec);
    fmt::print("Done\n");
    ec.clear();

    // Read
    fmt::print("Reading restart counter from NVS ... ");
    int32_t restart_counter = 0;
    storage.get("restart_counter", restart_counter, ec);
    if (ec) {
      if (ec.value() == static_cast<int>(NvsErrc::Key_Not_Found)) {
        fmt::print("The value is not initialized yet!\n");
      } else if (ec.value() == static_cast<int>(NvsErrc::Read_NVS_Failed)) {
        fmt::print("Failed to read from NVS: {}\n", ec.message().c_str());
      } else {
        fmt::print("An error occurred: {}\n", ec.message().c_str());
      }
    } else {
      fmt::print("Done\n");
      fmt::print("Restart counter = {}\n", restart_counter);
    }
    ec.clear();

    // Write
    fmt::print("Updating restart counter in NVS ... ");
    restart_counter++;
    storage.set("restart_counter", restart_counter, ec);
    fmt::print("Done\n");
    ec.clear();

    // 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.
    fmt::print("Committing updates in NVS ... ");
    storage.commit(ec);
    fmt::print("Done\n");
    ec.clear();

    fmt::print("\n");
    fflush(stdout);

Public Functions

inline NvsHandle()

Default constructor for NvsHandle.

Initializes the NvsHandle without a specific namespace.

inline explicit NvsHandle(const char *ns_name, std::error_code &ec)

Construct a new NvsHandle object.

Create an NvsHandle object for the key-value pairs in the ns_name namespace

Parameters:

ns_name – [in] Namespace for NVS
ec – [out] Saves a std::error_code representing success or failure

inline explicit NvsHandle(std::string_view ns_name, std::error_code &ec)

Construct a new NvsHandle object.

Create an NvsHandle object for the key-value pairs in the ns_name namespace

Parameters:

ns_name – [in] Namespace for NVS
ec – [out] Saves a std::error_code representing success or failure

inline bool init(const char *ns_name, std::error_code &ec)

Initializes the NvsHandle with a namespace.

Initializes the NvsHandle object for the key-value pairs in the ns_name namespace

Parameters:

ns_name – [in] Namespace for NVS
ec – [out] Saves a std::error_code representing success or failure

Returns:

true if successful, false otherwise

inline bool init(std::string_view ns_name, std::error_code &ec)

Initializes the NvsHandle with a namespace.

Initializes the NvsHandle object for the key-value pairs in the ns_name namespace

Parameters:

ns_name – [in] Namespace for NVS
ec – [out] Saves a std::error_code representing success or failure

Returns:

true if successful, false otherwise

template<typename T> inline void get(const char *key, T &value, std::error_code &ec)

Reads a variable from the NVS.

Reads the value of key into value, if key exists

Parameters:

key – [in] NVS Key of the variable to read
value – [out] Variable to read
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void get(std::string_view key, T &value, std::error_code &ec)

Reads a variable from the NVS.

Parameters:

key – [in] NVS Key of the variable to read
value – [out] Variable to read
ec – [out] Saves a std::error_code representing success or failure

inline void get(const char *key, bool &value, std::error_code &ec)

Reads a bool from the NVS.

Read the key/variable pair

Parameters:

key – [in] NVS Key of the bool to read
value – [out] bool to read
ec – [out] Saves a std::error_code representing success or failure

inline void get(std::string_view key, bool &value, std::error_code &ec)

Reads a bool from the NVS.

Parameters:

key – [in] NVS Key of the bool to read
value – [out] bool to read
ec – [out] Saves a std::error_code representing success or failure

inline void get(const char *key, float &value, std::error_code &ec)

Reads a float from the NVS.

Parameters:

key – [in] NVS Key of the variable to read
value – [out] Float variable to read
ec – [out] Saves a std::error_code representing success or failure

inline void get(std::string_view key, float &value, std::error_code &ec)

Reads a float from the NVS.

Parameters:

key – [in] NVS Key of the variable to read
value – [out] Float variable to read
ec – [out] Saves a std::error_code representing success or failure

inline void get(std::string_view key, std::string &value, std::error_code &ec)

Reads a string from the NVS.

Parameters:

key – [in] NVS Key of the string to read
value – [inout] string to read
ec – [out] Saves a std::error_code representing success or failure

inline void get(const char *key, std::string &value, std::error_code &ec)

Reads a string from the NVS.

Parameters:

key – [in] NVS Key of the string to read
value – [out] string to read
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void get(const char *key, T &value, const T default_value, std::error_code &ec)

Reads a variable from the NVS.

Reads the value of key into value, if key exists

Parameters:

key – [in] NVS Key of the variable to read
value – [out] Variable to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void get(std::string_view key, T &value, const T default_value, std::error_code &ec)

Reads a variable from the NVS.

Parameters:

key – [in] NVS Key of the variable to read
value – [out] Variable to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

inline void get(const char *key, bool &value, const bool default_value, std::error_code &ec)

Reads a bool from the NVS.

Read the key/variable pair

Parameters:

key – [in] NVS Key of the bool to read
value – [out] bool to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

inline void get(std::string_view key, bool &value, const bool default_value, std::error_code &ec)

Reads a bool from the NVS.

Parameters:

key – [in] NVS Key of the bool to read
value – [out] bool to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

inline void get(const char *key, float &value, const float default_value, std::error_code &ec)

Reads a float from the NVS.

Read the key/variable pair

Parameters:

key – [in] NVS Key of the bool to read
value – [out] float to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

inline void get(std::string_view key, float &value, const float default_value, std::error_code &ec)

Reads a float from the NVS.

Parameters:

key – [in] NVS Key of the float to read
value – [out] float to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

inline void get(std::string_view key, std::string &value, const std::string &default_value, std::error_code &ec)

Reads a string from the NVS.

Parameters:

key – [in] NVS Key of the string to read
value – [out] string to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

inline void get(const char *key, std::string &value, const std::string &default_value, std::error_code &ec)

Reads a string from the NVS.

Parameters:

key – [in] NVS Key of the string to read
value – [out] string to read
default_value – [in] Default value to return if key is not found
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void set(const char *key, T value, std::error_code &ec)

Save a variable in the NVS.

Saves the key/variable pair without committing the NVS.

Parameters:

key – [in] NVS Key of the variable to read
value – [in] Variable to read
ec – [out] Saves a std::error_code representing success or failure

template<typename T> inline void set(std::string_view key, T value, std::error_code &ec)

Save a variable in the NVS.

Parameters:

key – [in] NVS Key of the variable to save
value – [in] Variable to save
ec – [out] Saves a std::error_code representing success or failure

inline void set(std::string_view key, bool value, std::error_code &ec)

Set a bool in the NVS.

Parameters:

key – [in] NVS Key of the bool to set
value – [in] bool to set
ec – [out] Saves a std::error_code representing success or failure

inline void set(const char *key, bool value, std::error_code &ec)

Set a bool in the NVS.

Parameters:

key – [in] NVS Key of the bool to set
value – [in] bool to set
ec – [out] Saves a std::error_code representing success or failure

inline void set(std::string_view key, float value, std::error_code &ec)

Set a float in the NVS.

Parameters:

key – [in] NVS Key of the float to set
value – [in] float to set
ec – [out] Saves a std::error_code representing success or failure

inline void set(const char *key, float value, std::error_code &ec)

Set a float in the NVS.

Parameters:

key – [in] NVS Key of the float to set
value – [in] float to set
ec – [out] Saves a std::error_code representing success or failure

inline void set(std::string_view key, const std::string &value, std::error_code &ec)

Set a string in the NVS.

Parameters:

key – [in] NVS Key of the string to set
value – [in] string to set
ec – [out] Saves a std::error_code representing success or failure

inline void set(const char *key, const std::string &value, std::error_code &ec)

Set a string in the NVS.

Parameters:

key – [in] NVS Key of the string to set
value – [in] string to set
ec – [out] Saves a std::error_code representing success or failure

inline void commit(std::error_code &ec)

Commit changes.

Commits changes to the NVS

Parameters:: ec – [out] Saves a std::error_code representing success or failure

inline bool erase(std::string_view key, std::error_code &ec)

Erase a key from the NVS.

Parameters:

key – [in] NVS Key to erase
ec – [out] Saves a std::error_code representing success or failure

Returns:

true if successful, false otherwise

inline bool erase(const char *key, std::error_code &ec)

Erase a key from the NVS.

Parameters:

key – [in] NVS Key to erase
ec – [out] Saves a std::error_code representing success or failure

Returns:

true if successful, false otherwise

inline bool erase(std::error_code &ec)

Erase all keys from the NVS associated with the namespace / handle.

Parameters:: ec – [out] Saves a std::error_code representing success or failure
Returns:: true if successful, false otherwise

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:: rate_limit – The rate limit to use for the logger