Improves in ESP32NVS library (#196)

* Improved ESP32NVS default value support for read* functions

Fixed uninitialized NVS flash storage. Added example code.

* Add methods for String and remove unnecessary nvs_flash_init() in ESP32NVS class

+ other minor declaration fixes

* ESP32NVS function name renaming

* read* -> get*
* write* -> set*
* erase -> clear / remove

libraries/ESP32NVS/examples/StartCounter/StartCounter.ino

+/*
+ ESP32 start counter example with Non-volatile storage
+
+ A simple example which use Non-volatile storage on ESP32 to store how many
+ times ESP32 module was started.
+
+ created for arduino-esp32 09 Feb 2017
+ by Martin Sloup (Arcao)
+*/
+
+#include <ESP32NVS.h>
+
+NVSClass keyStorage;
+
+void setup() {
+  Serial.begin(115200);
+  Serial.println();
+
+  // Open NVS key storage with my-app namespace. Each application module (library, etc.)
+  // have to use namespace name to prevent key name colisions. We will open storage in
+  // RW-mode (second parameter has to be false).
+  // Note: Namespace name is limited to 15 chars
+  keyStorage.begin("my-app", false);
+
+  // Clear an opened key storage
+  //keyStorage.clear();
+
+  // Or remove the counter key from key storage
+  //keyStorage.remove("counter");
+
+  // Get a counter value, if key is not exist return default value 0
+  // Note: Key name is limited to 15 chars too
+  unsigned int counter = keyStorage.getUInt("counter", 0);
+
+  // Increase counter
+  counter++;
+
+  // Print counter to a Serial
+  Serial.printf("Current counter value: %u\n", counter);
+
+  // Store counter to the key storage
+  keyStorage.setUInt("counter", counter);
+
+  // Close the key storage
+  keyStorage.end();
+
+  Serial.println("Restarting in 10 seconds...");
+
+  // Wait 10 seconds
+  delay(10000);
+
+  // Restart ESP
+  ESP.restart();
+}
+
+void loop() {}
\ No newline at end of file

libraries/ESP32NVS/library.properties

@@ -4,6 +4,6 @@ author=Hristo Gochkov
 maintainer=Hristo Gochkov <hristo@espressif.com>
 sentence=Provides frendly access to ESP32's Non-Volatile Storage
 paragraph=
-category=Storage
+category=Data Storage
 url=
 architectures=esp32

libraries/ESP32NVS/src/ESP32NVS.cpp

@@ -51,10 +51,10 @@ void NVSClass::end(){
 }
 
 /*
- * Erase
+ * Clear the storage
  * */
 
-bool NVSClass::erase(){
+bool NVSClass::clear(){
     if(!_started || _readOnly){
         return false;
     }
@@ -66,7 +66,11 @@ bool NVSClass::erase(){
     return true;
 }
 
-bool NVSClass::erase(const char * key){
+/*
+ * Remove the key
+ * */
+
+bool NVSClass::remove(const char * key){
     if(!_started || !key || _readOnly){
         return false;
     }
@@ -82,7 +86,7 @@ bool NVSClass::erase(const char * key){
  * Write
  * */
 
-size_t NVSClass::writeChar(const char* key, int8_t value){
+size_t NVSClass::setChar(const char* key, int8_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -99,7 +103,7 @@ size_t NVSClass::writeChar(const char* key, int8_t value){
     return 1;
 }
 
-size_t NVSClass::writeUChar(const char* key, uint8_t value){
+size_t NVSClass::setUChar(const char* key, uint8_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -116,7 +120,7 @@ size_t NVSClass::writeUChar(const char* key, uint8_t value){
     return 1;
 }
 
-size_t NVSClass::writeShort(const char* key, int16_t value){
+size_t NVSClass::setShort(const char* key, int16_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -133,7 +137,7 @@ size_t NVSClass::writeShort(const char* key, int16_t value){
     return 2;
 }
 
-size_t NVSClass::writeUShort(const char* key, uint16_t value){
+size_t NVSClass::setUShort(const char* key, uint16_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -150,7 +154,7 @@ size_t NVSClass::writeUShort(const char* key, uint16_t value){
     return 2;
 }
 
-size_t NVSClass::writeInt(const char* key, int32_t value){
+size_t NVSClass::setInt(const char* key, int32_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -167,7 +171,7 @@ size_t NVSClass::writeInt(const char* key, int32_t value){
     return 4;
 }
 
-size_t NVSClass::writeUInt(const char* key, uint32_t value){
+size_t NVSClass::setUInt(const char* key, uint32_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -184,7 +188,7 @@ size_t NVSClass::writeUInt(const char* key, uint32_t value){
     return 4;
 }
 
-size_t NVSClass::writeLong(const char* key, int64_t value){
+size_t NVSClass::setLong(const char* key, int64_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -201,7 +205,7 @@ size_t NVSClass::writeLong(const char* key, int64_t value){
     return 8;
 }
 
-size_t NVSClass::writeULong(const char* key, uint64_t value){
+size_t NVSClass::setULong(const char* key, uint64_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -218,7 +222,7 @@ size_t NVSClass::writeULong(const char* key, uint64_t value){
     return 8;
 }
 
-size_t NVSClass::writeString(const char* key, const char* value){
+size_t NVSClass::setString(const char* key, const char* value){
     if(!_started || !key || !value || _readOnly){
         return 0;
     }
@@ -235,7 +239,11 @@ size_t NVSClass::writeString(const char* key, const char* value){
     return strlen(value);
 }
 
-size_t NVSClass::writeBytes(const char* key, const void* value, size_t len){
+size_t NVSClass::setString(const char* key, const String value){
+    return setString(key, value.c_str());
+}
+
+size_t NVSClass::setBytes(const char* key, const void* value, size_t len){
     if(!_started || !key || !value || !len || _readOnly){
         return 0;
     }
@@ -256,8 +264,8 @@ size_t NVSClass::writeBytes(const char* key, const void* value, size_t len){
  * Read
  * */
 
-int8_t NVSClass::readChar(const char* key){
-    int8_t value = 0;
+int8_t NVSClass::getChar(const char* key, const int8_t defaultValue){
+    int8_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -268,8 +276,8 @@ int8_t NVSClass::readChar(const char* key){
     return value;
 }
 
-uint8_t NVSClass::readUChar(const char* key){
-    uint8_t value = 0;
+uint8_t NVSClass::getUChar(const char* key, const uint8_t defaultValue){
+    uint8_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -280,8 +288,8 @@ uint8_t NVSClass::readUChar(const char* key){
     return value;
 }
 
-int16_t NVSClass::readShort(const char* key){
-    int16_t value = 0;
+int16_t NVSClass::getShort(const char* key, const int16_t defaultValue){
+    int16_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -292,8 +300,8 @@ int16_t NVSClass::readShort(const char* key){
     return value;
 }
 
-uint16_t NVSClass::readUShort(const char* key){
-    uint16_t value = 0;
+uint16_t NVSClass::getUShort(const char* key, const uint16_t defaultValue){
+    uint16_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -304,8 +312,8 @@ uint16_t NVSClass::readUShort(const char* key){
     return value;
 }
 
-int32_t NVSClass::readInt(const char* key){
-    int32_t value = 0;
+int32_t NVSClass::getInt(const char* key, const int32_t defaultValue){
+    int32_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -316,8 +324,8 @@ int32_t NVSClass::readInt(const char* key){
     return value;
 }
 
-uint32_t NVSClass::readUInt(const char* key){
-    uint32_t value = 0;
+uint32_t NVSClass::getUInt(const char* key, const uint32_t defaultValue){
+    uint32_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -328,8 +336,8 @@ uint32_t NVSClass::readUInt(const char* key){
     return value;
 }
 
-int64_t NVSClass::readLong(const char* key){
-    int64_t value = 0;
+int64_t NVSClass::getLong(const char* key, const int64_t defaultValue){
+    int64_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -340,8 +348,8 @@ int64_t NVSClass::readLong(const char* key){
     return value;
 }
 
-uint64_t NVSClass::readULong(const char* key){
-    uint64_t value = 0;
+uint64_t NVSClass::getULong(const char* key, const uint64_t defaultValue){
+    uint64_t value = defaultValue;
     if(!_started || !key){
         return value;
     }
@@ -352,28 +360,50 @@ uint64_t NVSClass::readULong(const char* key){
     return value;
 }
 
-String NVSClass::readString(const char* key){
+size_t NVSClass::getString(const char* key, char* value, const size_t maxLen){
+    size_t len = 0;
+    if(!_started || !key || !value || !maxLen){
+        return 0;
+    }
+    esp_err_t err = nvs_get_str(_handle, key, NULL, &len);
+    if(err){
+        log_e("nvs_get_str len fail: %s %s", key, nvs_error(err));
+        return 0;
+    }
+    if(len > maxLen){
+        log_e("not enough space in value: %u < %u", maxLen, len);
+        return 0;
+    }
+    err = nvs_get_str(_handle, key, value, &len);
+    if(err){
+        log_e("nvs_get_str fail: %s %s", key, nvs_error(err));
+        return 0;
+    }
+    return len;
+}
+
+String NVSClass::getString(const char* key, const String defaultValue){
     char * value = NULL;
     size_t len = 0;
     if(!_started || !key){
-        return String();
+        return String(defaultValue);
     }
     esp_err_t err = nvs_get_str(_handle, key, value, &len);
     if(err){
         log_e("nvs_get_str len fail: %s %s", key, nvs_error(err));
-        return String();
+        return String(defaultValue);
     }
     char buf[len];
     value = buf;
     err = nvs_get_str(_handle, key, value, &len);
     if(err){
         log_e("nvs_get_str fail: %s %s", key, nvs_error(err));
-        return String();
+        return String(defaultValue);
     }
     return String(buf);
 }
 
-size_t NVSClass::readBytes(const char* key, void * buf, size_t maxLen){
+size_t NVSClass::getBytes(const char* key, void * buf, size_t maxLen){
     size_t len = 0;
     if(!_started || !key || !buf || !maxLen){
         return 0;

libraries/ESP32NVS/src/ESP32NVS.h

@@ -28,30 +28,32 @@ class NVSClass {
         bool begin(const char * name, bool readOnly=false);
         void end();
 
-        bool erase();
-        bool erase(const char * key);
-
-        size_t writeChar(const char* key, int8_t value);
-        size_t writeUChar(const char* key, uint8_t value);
-        size_t writeShort(const char* key, int16_t value);
-        size_t writeUShort(const char* key, uint16_t value);
-        size_t writeInt(const char* key, int32_t value);
-        size_t writeUInt(const char* key, uint32_t value);
-        size_t writeLong(const char* key, int64_t value);
-        size_t writeULong(const char* key, uint64_t value);
-        size_t writeString(const char* key, const char* value);
-        size_t writeBytes(const char* key, const void* value, size_t len);
-
-        int8_t readChar(const char* key);
-        uint8_t readUChar(const char* key);
-        int16_t readShort(const char* key);
-        uint16_t readUShort(const char* key);
-        int32_t readInt(const char* key);
-        uint32_t readUInt(const char* key);
-        int64_t readLong(const char* key);
-        uint64_t readULong(const char* key);
-        String readString(const char* key);
-        size_t readBytes(const char* key, void * buf, size_t maxLen);
+        bool clear();
+        bool remove(const char * key);
+
+        size_t setChar(const char* key, int8_t value);
+        size_t setUChar(const char* key, uint8_t value);
+        size_t setShort(const char* key, int16_t value);
+        size_t setUShort(const char* key, uint16_t value);
+        size_t setInt(const char* key, int32_t value);
+        size_t setUInt(const char* key, uint32_t value);
+        size_t setLong(const char* key, int64_t value);
+        size_t setULong(const char* key, uint64_t value);
+        size_t setString(const char* key, const char* value);
+        size_t setString(const char* key, String value);
+        size_t setBytes(const char* key, const void* value, size_t len);
+
+        int8_t getChar(const char* key, int8_t defaultValue = 0);
+        uint8_t getUChar(const char* key, uint8_t defaultValue = 0);
+        int16_t getShort(const char* key, int16_t defaultValue = 0);
+        uint16_t getUShort(const char* key, uint16_t defaultValue = 0);
+        int32_t getInt(const char* key, int32_t defaultValue = 0);
+        uint32_t getUInt(const char* key, uint32_t defaultValue = 0);
+        int64_t getLong(const char* key, int64_t defaultValue = 0);
+        uint64_t getULong(const char* key, uint64_t defaultValue = 0);
+        size_t getString(const char* key, char* value, size_t maxLen);
+        String getString(const char* key, String defaultValue = String());
+        size_t getBytes(const char* key, void * buf, size_t maxLen);
 };
 
 #endif