Enhanced EEPROM library (ESP_EEPROM)

libraries/ESP_EEPROM/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

libraries/ESP_EEPROM/.gitignore

@@ -0,0 +1 @@
+.DS_Store

libraries/ESP_EEPROM/README.md

@@ -0,0 +1,6 @@
+# ESP_EEPROM
+An improved EEPROM emulation Arduino library for ESP8266
+
+The ESP8266 family doesn't have genuine EEPROM memory so for Arduino it is normally emulated by using a section of flash memory.
+
+With the standard ESP8266 EEPROM library, the sector needs to be re-flashed every time the changed EEPROM data needs to be saved.  For small amounts of EEPROM data this is very slow and will wear out the flash memory more quickly.  This library writes a new copy of your data when you save (commit) it and keeps track of where in the sector the most recent copy is kept using a bitmap. The flash sector only needs to be erased when there is no more space for copies in the flash sector.  You can keep track of this yourself to do a time-consuming erase when most convenient or the library will do it for you when there is no more space for the data when you commit it.

libraries/ESP_EEPROM/examples/ESP_EEPROM_CommitReset/ESP_EEPROM_CommitReset.ino

@@ -0,0 +1,79 @@
+// Example use of ESP_EEPROM library for ESP8266
+//
+// Normally writing to the 'emulated' EEPROM on ESP8266 requires an erase of the flash page used to hold
+// the EEPROM data followed by a re-write of the changed data.
+// The erasure takes a significant amount of time (10s of ms) and during this time
+// interrupts must be blocked.
+// In some cases this interferes with the sketch operation (e.g. it produces a noticeable
+// blackout/flash for any PWM controlled lights as ESP8266 PWM relies on interrupts)
+//
+// The ESP_EEPROM library writes each new version of the EEPROM data to a new area until flash
+// is full and so avoids wiping flash until necessary
+//
+// It's best for use when there are only a few things to save in EEPROM
+// (i.e. total the size of the saved info is much smaller than the available flash size)
+//
+
+#include <ESP_EEPROM.h>
+
+const int BLUE_LED_PIN = 2;
+
+// The neatest way to access variables stored in EEPROM is using a structure
+struct MyEEPROMStruct {
+  int     anInteger;
+  float   aFloating;
+  int     anotherInteger;
+  byte    someBytes[12];
+  boolean state;
+} eepromVar1, eepromVar2;
+
+void setup() {
+  // Remember to set your serial monitor to 74880 baud
+  // This odd speed will show ESP8266 boot diagnostics too
+  Serial.begin(74880);
+  Serial.println();
+
+  // Set up the initial (default) values for what is to be stored in EEPROM
+  eepromVar1.anInteger = 99;
+  eepromVar1.aFloating = 99.99;
+  eepromVar1.anotherInteger = 42;
+  eepromVar1.state = true;
+
+  // All the library functions are accessed via the EEPROM object created when
+  // you include the library header ESP_EEPROM.h
+
+  // The library needs to know what size you need for your EEPROM variables
+  // Using a structure makes this easy.
+
+  // The begin() call is required to initialise the EEPROM library
+  EEPROM.begin(sizeof(MyEEPROMStruct));
+
+  //
+  // (some code that might change the EEPROM data)
+  //
+
+  // set the EEPROM data ready for writing
+  EEPROM.put(0, eepromVar1);
+
+  // write the data to EEPROM - ignoring anything that might be there already (re-flash is guaranteed)
+  boolean ok1 = EEPROM.commitReset();
+  Serial.println((ok1) ? "Commit (Reset) OK" : "Commit failed");
+
+  //
+  // (some code that might change the EEPROM data some more)
+  //
+  eepromVar1.anInteger++;   // Change some data
+
+  // set the EEPROM data ready for writing
+  EEPROM.put(0, eepromVar1);
+
+  // write the data to EEPROM
+  boolean ok2 = EEPROM.commit();
+  Serial.println((ok2) ? "Commit OK" : "Commit failed");
+
+}
+
+
+void loop() {
+  // do nothing
+}

libraries/ESP_EEPROM/examples/ESP_EEPROM_Simple/ESP_EEPROM_Simple.ino

@@ -0,0 +1,71 @@
+// Example use of ESP_EEPROM library for ESP8266
+//
+// Normally writing to the 'emulated' EEPROM on ESP8266 requires an erase of the flash page used to hold
+// the EEPROM data followed by a re-write of the changed data.
+// The erasure takes a significant amount of time (10s of ms) and during this time
+// interrupts must be blocked.
+// In some cases this interferes with the sketch operation (e.g. it produces a noticeable
+// blackout/flash for any PWM controlled lights as ESP8266 PWM relies on interrupts)
+//
+// The ESP_EEPROM library writes each new version of the EEPROM data to a new area until flash
+// is full and so avoids wiping flash until necessary
+//
+// It's best for use when there are only a few things to save in EEPROM
+// (i.e. total the size of the saved info is much smaller than the available flash size)
+//
+
+#include <ESP_EEPROM.h>
+
+int eepromVar1 = 0;
+long eepromVar2 = 1234;
+
+void setup() {
+  // Remember to set your serial monitor to 74880 baud
+  // This odd speed will show ESP8266 boot diagnostics too
+  Serial.begin(74880);
+  Serial.println();
+
+  // All the library functions are accessed via the EEPROM object created when
+  // you include the library header ESP_EEPROM.h
+
+  // The library needs to know what size you need for your EEPROM variables
+  // The minimum size is 16
+
+  // The begin() call is required to initialise the EEPROM library
+  EEPROM.begin(16);
+
+  // put some data into eeprom
+  EEPROM.put(0, eepromVar1);  // int - so 4 bytes (next address is '4')
+  EEPROM.put(4, eepromVar2);  // long - so 8 bytes (next address would be '12')
+
+  // write the data to EEPROM
+  boolean ok1 = EEPROM.commit();
+  Serial.println((ok1) ? "First commit OK" : "Commit failed");
+
+  // The eeprom data gets changed
+  eepromVar1 = 1;   // Change some data
+
+  // set the EEPROM data ready for writing
+  EEPROM.put(0, eepromVar1);
+
+  // commit (write) the data to EEPROM - only actually writes if there has been a change
+  boolean ok2 = EEPROM.commit();
+  Serial.println((ok2) ? "Second commit OK" : "Commit failed");
+
+  // How to read stuff back into variables
+  // variables should be same size as originally written
+  int aNewVar1;
+  long aNewVar2;
+  EEPROM.get(0, aNewVar1);
+  EEPROM.get(4, aNewVar2);
+  Serial.print("Read back a variable 1 from EEPROM: ");
+  Serial.println(aNewVar1);
+  Serial.print("Read back a variable 2 from EEPROM: ");
+  Serial.println(aNewVar2);
+
+}
+
+
+void loop() {
+  delay(1000);
+}

libraries/ESP_EEPROM/examples/ESP_EEPROM_Use/ESP_EEPROM_Use.ino

@@ -0,0 +1,87 @@
+// Example use of ESP_EEPROM library for ESP8266
+//
+// Normally writing to the 'emulated' EEPROM on ESP8266 requires an erase of the flash page used to hold
+// the EEPROM data followed by a re-write of the changed data.
+// The erasure takes a significant amount of time (10s of ms) and during this time
+// interrupts must be blocked.
+// In some cases this interferes with the sketch operation (e.g. it produces a noticeable
+// blackout/flash for any PWM controlled lights as ESP8266 PWM relies on interrupts)
+//
+// The ESP_EEPROM library writes each new version of the EEPROM data to a new area until flash
+// is full and so avoids wiping flash until necessary
+//
+// It's best for use when there are only a few things to save in EEPROM
+// (i.e. total the size of the saved info is much smaller than the available flash size)
+//
+
+#include <ESP_EEPROM.h>
+
+const int BLUE_LED_PIN = 2;
+
+// The neatest way to access variables stored in EEPROM is using a structure
+struct MyEEPROMStruct {
+  int     anInteger;
+  float   aFloating;
+  int     anotherInteger;
+  byte    someBytes[12];
+  boolean state;
+} eepromVar1, eepromVar2;
+
+void setup() {
+  // Remember to set your serial monitor to 74880 baud
+  // This odd speed will show ESP8266 boot diagnostics too
+  Serial.begin(74880);
+  Serial.println();
+
+  // Set up the initial (default) values for what is to be stored in EEPROM
+  eepromVar1.anInteger = 99;
+  eepromVar1.aFloating = 99.99;
+  eepromVar1.anotherInteger = 42;
+  eepromVar1.state = true;
+
+  // All the library functions are accessed via the EEPROM object created when
+  // you include the library header ESP_EEPROM.h
+
+  // The library needs to know what size you need for your EEPROM variables
+  // Using a structure makes this easy.
+
+  // The begin() call will find the data previously saved in EEPROM if the same size
+  // as was previously committed. If the size is different then the EEEPROM data is cleared. 
+  // Note that this is not made permanent until you call commit();
+  EEPROM.begin(sizeof(MyEEPROMStruct));
+
+  // Check if the EEPROM contains valid data from another run
+  // If so, overwrite the 'default' values set up in our struct
+  if(EEPROM.percentUsed()!=0) {
+    EEPROM.get(0, eepromVar1);
+    eepromVar1.anInteger++;     // make a change to our copy of the EEPROM data
+    Serial.println("EEPROM has data from a previous run.");
+    Serial.print(EEPROM.percentUsed());
+    Serial.println("% of ESP flash space currently used");
+  } else {
+    Serial.println("EEPROM size changed - EEPROM data zeroed - commit() to make permanent");    
+  }
+
+  //
+  // (some code that might change the EEPROM data)
+  //
+
+  // set the EEPROM data ready for writing
+  EEPROM.put(0, eepromVar1);
+
+  // write the data to EEPROM
+  boolean ok = EEPROM.commit();
+  Serial.println((ok) ? "Commit OK" : "Commit failed");
+
+  // Get EEPROM data into our local copy
+  // For this example, a different struct variable is used 
+  EEPROM.get(0, eepromVar2);
+
+  Serial.print("EEPROM data read, anInteger=");
+  Serial.println(eepromVar2.anInteger);
+}
+
+
+void loop() {
+  // do nothing
+}

libraries/ESP_EEPROM/examples/ESP_EEPROM_Wipe/ESP_EEPROM_Wipe.ino

@@ -0,0 +1,36 @@
+// Example use of ESP_EEPROM library for ESP8266
+//
+// This simple sketch wipes (erases) the flash storage area used
+// to hold the EEPROM data.
+//
+// Useful when testing to ensure your code deals with a 'new' device
+// as well as one hilding previous EEPROM data.
+//
+
+#include <ESP_EEPROM.h>
+
+const int BLUE_LED_PIN = 2;
+
+void setup() {
+  // Remember to set your serial monitor to 74880 baud
+  // This odd speed will show ESP8266 boot diagnostics too
+  Serial.begin(74880);
+  Serial.println();
+
+  // It is still necessary to call begin
+  // or no wipe will be performed
+  EEPROM.begin(EEPROM_MIN_SIZE);
+
+
+  boolean result = EEPROM.wipe();
+  if (result) {
+    Serial.println("All EEPROM data wiped");
+  } else {
+    Serial.println("EEPROM data could not be wiped from flash store");
+  }
+}
+
+
+void loop() {
+  // do nothing
+}

libraries/ESP_EEPROM/keywords.txt

@@ -0,0 +1,31 @@
+#######################################
+# Syntax Colouring Map For ESP_EEPROM
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+ESP_EEPROM	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+
+doSomething	KEYWORD2
+begin	KEYWORD2
+read	KEYWORD2
+write	KEYWORD2
+commit	KEYWORD2
+commitReset	KEYWORD2
+wipe	KEYWORD2
+percentUsed	KEYWORD2
+end	KEYWORD2
+
+#######################################
+# Instances (KEYWORD2)
+#######################################
+
+#######################################
+# Constants (LITERAL1)
+#######################################

libraries/ESP_EEPROM/library.properties

@@ -0,0 +1,9 @@
+name=ESP_EEPROM
+version=1.0.1
+author=j-watson <[email protected]>
+maintainer=j-watson <[email protected]>
+sentence=An improved EEPROM library for ESP8266
+paragraph=The ESP8266 family doesn't have genuine EEPROM memory so it is normally emulated by using a section of flash memory.  With the standard library, the sector needs to be re-flashed every time the changed EEPROM data needs to be saved.  For small amounts of EEPROM data this is very slow and will wear out the flash memory more quickly.  This library writes a new copy of your data when you save (commit) it and keeps track of where in the sector the most recent copy is kept.  The flash sector only needs to be erased when there is no more space for copies in the flash sector.  You can keep track of this yourself to do a time-consuming erase when most convenient or the library will do it for you when there is no more space for the data when you commit it.
+category=Data Storage
+architectures=*
+url=https://github.com/jwrw/ESP_EEPROM.git