Refactoring EPS32NVS library to Preferences library (#199)

* Refactoring EPS32NVS library to Preferences library

* Renaming all set* functions to put
* Added functions for float, double and bool

* Small redesign of Preferences API

* added type to put* function names
* for (u)int64_t used functions name with *(U)Long64
* added functions for long and unsigned long (same like int a unsigned int)

libraries/ESP32NVS/examples/StartCounter/StartCounter.ino

@@ -1,56 +0,0 @@
-/*
- 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() {}

libraries/ESP32NVS/keywords.txt

@@ -1,41 +0,0 @@
-#######################################
-# Syntax Coloring Map NVS
-#######################################
-
-#######################################
-# Datatypes (KEYWORD1)
-#######################################
-
-NVSClass	KEYWORD1
-
-#######################################
-# Methods and Functions (KEYWORD2)
-#######################################
-begin	KEYWORD2
-end	KEYWORD2
-writeChar	KEYWORD2
-writeUChar	KEYWORD2
-writeShort	KEYWORD2
-writeUShort	KEYWORD2
-writeInt	KEYWORD2
-writeUInt	KEYWORD2
-writeLong	KEYWORD2
-writeULong	KEYWORD2
-writeString	KEYWORD2
-writeBytes	KEYWORD2
-readChar	KEYWORD2
-readUChar	KEYWORD2
-readShort	KEYWORD2
-readUShort	KEYWORD2
-readInt	KEYWORD2
-readUInt	KEYWORD2
-readLong	KEYWORD2
-readULong	KEYWORD2
-readString	KEYWORD2
-readBytes	KEYWORD2
-erase	KEYWORD2
-
-
-#######################################
-# Constants (LITERAL1)
-#######################################

libraries/Preferences/examples/StartCounter/StartCounter.ino

@@ -0,0 +1,56 @@
+/*
+ ESP32 start counter example with Preferences library
+
+ This simple example demonstrate using Preferences library to store how many times
+ was ESP32 module started. Preferences library is wrapper around Non-volatile
+ storage on ESP32 processor.
+
+ created for arduino-esp32 09 Feb 2017
+ by Martin Sloup (Arcao)
+*/
+
+#include <Preferences.h>
+
+Preferences preferences;
+
+void setup() {
+  Serial.begin(115200);
+  Serial.println();
+
+  // Open Preferences with my-app namespace. Each application module, library, etc.
+  // has to use namespace name to prevent key name collisions. We will open storage in
+  // RW-mode (second parameter has to be false).
+  // Note: Namespace name is limited to 15 chars
+  preferences.begin("my-app", false);
+
+  // Remove all preferences under opened namespace
+  //preferences.clear();
+
+  // Or remove the counter key only
+  //preferences.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 = preferences.getUInt("counter", 0);
+
+  // Increase counter
+  counter++;
+
+  // Print counter to a Serial
+  Serial.printf("Current counter value: %u\n", counter);
+
+  // Store counter to the Preferences
+  preferences.putUInt("counter", counter);
+
+  // Close the Preferences
+  preferences.end();
+
+  // Wait 10 seconds
+  Serial.println("Restarting in 10 seconds...");
+  delay(10000);
+
+  // Restart ESP
+  ESP.restart();
+}
+
+void loop() {}

libraries/Preferences/keywords.txt

@@ -0,0 +1,54 @@
+#######################################
+# Syntax Coloring Map NVS
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+Preferences	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+begin	KEYWORD2
+end	KEYWORD2
+
+clear	KEYWORD2
+delete	KEYWORD2
+
+putChar	KEYWORD2
+putUChar	KEYWORD2
+putShort	KEYWORD2
+putUShort	KEYWORD2
+putInt	KEYWORD2
+putUInt	KEYWORD2
+putLong	KEYWORD2
+putULong	KEYWORD2
+putLong64	KEYWORD2
+putULong64	KEYWORD2
+putFloat	KEYWORD2
+putDouble	KEYWORD2
+putBool	KEYWORD2
+putString	KEYWORD2
+putBytes	KEYWORD2
+
+getChar	KEYWORD2
+getUChar	KEYWORD2
+getShort	KEYWORD2
+getUShort	KEYWORD2
+getInt	KEYWORD2
+getUInt	KEYWORD2
+getLong	KEYWORD2
+getULong	KEYWORD2
+getLong64	KEYWORD2
+getULong64	KEYWORD2
+getFloat	KEYWORD2
+getDouble	KEYWORD2
+getBool	KEYWORD2
+getString	KEYWORD2
+getBytes	KEYWORD2
+
+#######################################
+# Constants (LITERAL1)
+#######################################

libraries/Preferences/library.properties

@@ -1,8 +1,8 @@
-name=ESP32NVS
+name=Preferences
 version=1.0
 author=Hristo Gochkov
 maintainer=Hristo Gochkov <hristo@espressif.com>
-sentence=Provides frendly access to ESP32's Non-Volatile Storage
+sentence=Provides friendly access to ESP32's Non-Volatile Storage
 paragraph=
 category=Data Storage
 url=

libraries/Preferences/src/Preferences.cpp

@@ -11,24 +11,24 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#include "ESP32NVS.h"
+#include "Preferences.h"
 
 #include "nvs.h"
 
 const char * nvs_errors[] = { "OTHER", "NOT_INITIALIZED", "NOT_FOUND", "TYPE_MISMATCH", "READ_ONLY", "NOT_ENOUGH_SPACE", "INVALID_NAME", "INVALID_HANDLE", "REMOVE_FAILED", "KEY_TOO_LONG", "PAGE_FULL", "INVALID_STATE", "INVALID_LENGHT"};
 #define nvs_error(e) (((e)>ESP_ERR_NVS_BASE)?nvs_errors[(e)&~(ESP_ERR_NVS_BASE)]:nvs_errors[0])
 
-NVSClass::NVSClass()
+Preferences::Preferences()
     :_handle(0)
     ,_started(false)
     ,_readOnly(false)
 {}
 
-NVSClass::~NVSClass(){
+Preferences::~Preferences(){
     end();
 }
 
-bool NVSClass::begin(const char * name, bool readOnly){
+bool Preferences::begin(const char * name, bool readOnly){
     if(_started){
         return false;
     }
@@ -42,7 +42,7 @@ bool NVSClass::begin(const char * name, bool readOnly){
     return true;
 }
 
-void NVSClass::end(){
+void Preferences::end(){
     if(!_started){
         return;
     }
@@ -51,10 +51,10 @@ void NVSClass::end(){
 }
 
 /*
- * Clear the storage
+ * Clear all keys in opened preferences
  * */
 
-bool NVSClass::clear(){
+bool Preferences::clear(){
     if(!_started || _readOnly){
         return false;
     }
@@ -67,10 +67,10 @@ bool NVSClass::clear(){
 }
 
 /*
- * Remove the key
+ * Remove a key
  * */
 
-bool NVSClass::remove(const char * key){
+bool Preferences::remove(const char * key){
     if(!_started || !key || _readOnly){
         return false;
     }
@@ -83,10 +83,10 @@ bool NVSClass::remove(const char * key){
 }
 
 /*
- * Write
+ * Put a key value
  * */
 
-size_t NVSClass::setChar(const char* key, int8_t value){
+size_t Preferences::putChar(const char* key, int8_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -103,7 +103,7 @@ size_t NVSClass::setChar(const char* key, int8_t value){
     return 1;
 }
 
-size_t NVSClass::setUChar(const char* key, uint8_t value){
+size_t Preferences::putUChar(const char* key, uint8_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -120,7 +120,7 @@ size_t NVSClass::setUChar(const char* key, uint8_t value){
     return 1;
 }
 
-size_t NVSClass::setShort(const char* key, int16_t value){
+size_t Preferences::putShort(const char* key, int16_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -137,7 +137,7 @@ size_t NVSClass::setShort(const char* key, int16_t value){
     return 2;
 }
 
-size_t NVSClass::setUShort(const char* key, uint16_t value){
+size_t Preferences::putUShort(const char* key, uint16_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -154,7 +154,7 @@ size_t NVSClass::setUShort(const char* key, uint16_t value){
     return 2;
 }
 
-size_t NVSClass::setInt(const char* key, int32_t value){
+size_t Preferences::putInt(const char* key, int32_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -171,7 +171,7 @@ size_t NVSClass::setInt(const char* key, int32_t value){
     return 4;
 }
 
-size_t NVSClass::setUInt(const char* key, uint32_t value){
+size_t Preferences::putUInt(const char* key, uint32_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -188,7 +188,15 @@ size_t NVSClass::setUInt(const char* key, uint32_t value){
     return 4;
 }
 
-size_t NVSClass::setLong(const char* key, int64_t value){
+size_t Preferences::putLong(const char* key, int32_t value){
+    return putInt(key, value);
+}
+
+size_t Preferences::putULong(const char* key, uint32_t value){
+    return putUInt(key, value);
+}
+
+size_t Preferences::putLong64(const char* key, int64_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -205,7 +213,7 @@ size_t NVSClass::setLong(const char* key, int64_t value){
     return 8;
 }
 
-size_t NVSClass::setULong(const char* key, uint64_t value){
+size_t Preferences::putULong64(const char* key, uint64_t value){
     if(!_started || !key || _readOnly){
         return 0;
     }
@@ -222,7 +230,19 @@ size_t NVSClass::setULong(const char* key, uint64_t value){
     return 8;
 }
 
-size_t NVSClass::setString(const char* key, const char* value){
+size_t Preferences::putFloat(const char* key, const float_t value){
+    return putBytes(key, (void*)&value, sizeof(float_t));
+}
+
+size_t Preferences::putDouble(const char* key, const double_t value){
+    return putBytes(key, (void*)&value, sizeof(double_t));
+}
+
+size_t Preferences::putBool(const char* key, const bool value){
+    return putUChar(key, (uint8_t) (value ? 1 : 0));
+}
+
+size_t Preferences::putString(const char* key, const char* value){
     if(!_started || !key || !value || _readOnly){
         return 0;
     }
@@ -239,11 +259,11 @@ size_t NVSClass::setString(const char* key, const char* value){
     return strlen(value);
 }
 
-size_t NVSClass::setString(const char* key, const String value){
+size_t Preferences::putString(const char* key, const String value){
-    return setString(key, value.c_str());
+    return putString(key, value.c_str());
 }
 
-size_t NVSClass::setBytes(const char* key, const void* value, size_t len){
+size_t Preferences::putBytes(const char* key, const void* value, size_t len){
     if(!_started || !key || !value || !len || _readOnly){
         return 0;
     }
@@ -261,10 +281,10 @@ size_t NVSClass::setBytes(const char* key, const void* value, size_t len){
 }
 
 /*
- * Read
+ * Get a key value
  * */
 
-int8_t NVSClass::getChar(const char* key, const int8_t defaultValue){
+int8_t Preferences::getChar(const char* key, const int8_t defaultValue){
     int8_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -276,7 +296,7 @@ int8_t NVSClass::getChar(const char* key, const int8_t defaultValue){
     return value;
 }
 
-uint8_t NVSClass::getUChar(const char* key, const uint8_t defaultValue){
+uint8_t Preferences::getUChar(const char* key, const uint8_t defaultValue){
     uint8_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -288,7 +308,7 @@ uint8_t NVSClass::getUChar(const char* key, const uint8_t defaultValue){
     return value;
 }
 
-int16_t NVSClass::getShort(const char* key, const int16_t defaultValue){
+int16_t Preferences::getShort(const char* key, const int16_t defaultValue){
     int16_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -300,7 +320,7 @@ int16_t NVSClass::getShort(const char* key, const int16_t defaultValue){
     return value;
 }
 
-uint16_t NVSClass::getUShort(const char* key, const uint16_t defaultValue){
+uint16_t Preferences::getUShort(const char* key, const uint16_t defaultValue){
     uint16_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -312,7 +332,7 @@ uint16_t NVSClass::getUShort(const char* key, const uint16_t defaultValue){
     return value;
 }
 
-int32_t NVSClass::getInt(const char* key, const int32_t defaultValue){
+int32_t Preferences::getInt(const char* key, const int32_t defaultValue){
     int32_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -324,7 +344,7 @@ int32_t NVSClass::getInt(const char* key, const int32_t defaultValue){
     return value;
 }
 
-uint32_t NVSClass::getUInt(const char* key, const uint32_t defaultValue){
+uint32_t Preferences::getUInt(const char* key, const uint32_t defaultValue){
     uint32_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -336,7 +356,15 @@ uint32_t NVSClass::getUInt(const char* key, const uint32_t defaultValue){
     return value;
 }
 
-int64_t NVSClass::getLong(const char* key, const int64_t defaultValue){
+int32_t Preferences::getLong(const char* key, const int32_t defaultValue){
+    return getInt(key, defaultValue);
+}
+
+uint32_t Preferences::getULong(const char* key, const uint32_t defaultValue){
+    return getUInt(key, defaultValue);
+}
+
+int64_t Preferences::getLong64(const char* key, const int64_t defaultValue){
     int64_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -348,7 +376,7 @@ int64_t NVSClass::getLong(const char* key, const int64_t defaultValue){
     return value;
 }
 
-uint64_t NVSClass::getULong(const char* key, const uint64_t defaultValue){
+uint64_t Preferences::getULong64(const char* key, const uint64_t defaultValue){
     uint64_t value = defaultValue;
     if(!_started || !key){
         return value;
@@ -360,7 +388,23 @@ uint64_t NVSClass::getULong(const char* key, const uint64_t defaultValue){
     return value;
 }
 
-size_t NVSClass::getString(const char* key, char* value, const size_t maxLen){
+float_t Preferences::getFloat(const char* key, const float_t defaultValue) {
+    float_t value = defaultValue;
+    getBytes(key, (void*) &value, sizeof(float_t));
+    return value;
+}
+
+double_t Preferences::getDouble(const char* key, const double_t defaultValue) {
+    double_t value = defaultValue;
+    getBytes(key, (void*) &value, sizeof(double_t));
+    return value;
+}
+
+bool Preferences::getBool(const char* key, const bool defaultValue) {
+    return getUChar(key, defaultValue ? 1 : 0) == 1;
+}
+
+size_t Preferences::getString(const char* key, char* value, const size_t maxLen){
     size_t len = 0;
     if(!_started || !key || !value || !maxLen){
         return 0;
@@ -382,7 +426,7 @@ size_t NVSClass::getString(const char* key, char* value, const size_t maxLen){
     return len;
 }
 
-String NVSClass::getString(const char* key, const String defaultValue){
+String Preferences::getString(const char* key, const String defaultValue){
     char * value = NULL;
     size_t len = 0;
     if(!_started || !key){
@@ -403,7 +447,7 @@ String NVSClass::getString(const char* key, const String defaultValue){
     return String(buf);
 }
 
-size_t NVSClass::getBytes(const char* key, void * buf, size_t maxLen){
+size_t Preferences::getBytes(const char* key, void * buf, size_t maxLen){
     size_t len = 0;
     if(!_started || !key || !buf || !maxLen){
         return 0;
@@ -424,4 +468,3 @@ size_t NVSClass::getBytes(const char* key, void * buf, size_t maxLen){
     }
     return len;
 }
-

libraries/Preferences/src/Preferences.h

@@ -11,19 +11,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#ifndef _ESP32NVS_H_
+#ifndef _PREFERENCES_H_
-#define _ESP32NVS_H_
+#define _PREFERENCES_H_
 
 #include "Arduino.h"
 
-class NVSClass {
+class Preferences {
     protected:
         uint32_t _handle;
         bool _started;
         bool _readOnly;
     public:
-        NVSClass();
+        Preferences();
-        ~NVSClass();
+        ~Preferences();
 
         bool begin(const char * name, bool readOnly=false);
         void end();
@@ -31,17 +31,22 @@ class NVSClass {
         bool clear();
         bool remove(const char * key);
 
-        size_t setChar(const char* key, int8_t value);
+        size_t putChar(const char* key, int8_t value);
-        size_t setUChar(const char* key, uint8_t value);
+        size_t putUChar(const char* key, uint8_t value);
-        size_t setShort(const char* key, int16_t value);
+        size_t putShort(const char* key, int16_t value);
-        size_t setUShort(const char* key, uint16_t value);
+        size_t putUShort(const char* key, uint16_t value);
-        size_t setInt(const char* key, int32_t value);
+        size_t putInt(const char* key, int32_t value);
-        size_t setUInt(const char* key, uint32_t value);
+        size_t putUInt(const char* key, uint32_t value);
-        size_t setLong(const char* key, int64_t value);
+        size_t putLong(const char* key, int32_t value);
-        size_t setULong(const char* key, uint64_t value);
+        size_t putULong(const char* key, uint32_t value);
-        size_t setString(const char* key, const char* value);
+        size_t putLong64(const char* key, int64_t value);
-        size_t setString(const char* key, String value);
+        size_t putULong64(const char* key, uint64_t value);
-        size_t setBytes(const char* key, const void* value, size_t len);
+        size_t putFloat(const char* key, float_t value);
+        size_t putDouble(const char* key, double_t value);
+        size_t putBool(const char* key, bool value);
+        size_t putString(const char* key, const char* value);
+        size_t putString(const char* key, String value);
+        size_t putBytes(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);
@@ -49,8 +54,13 @@ class NVSClass {
         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);
+        int32_t getLong(const char* key, int32_t defaultValue = 0);
-        uint64_t getULong(const char* key, uint64_t defaultValue = 0);
+        uint32_t getULong(const char* key, uint32_t defaultValue = 0);
+        int64_t getLong64(const char* key, int64_t defaultValue = 0);
+        uint64_t getULong64(const char* key, uint64_t defaultValue = 0);
+        float_t getFloat(const char* key, float_t defaultValue = NAN);
+        double_t getDouble(const char* key, double_t defaultValue = NAN);
+        bool getBool(const char* key, bool defaultValue = false);
         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);