first commit

libraries/ESPFlash/README.md

@@ -0,0 +1,87 @@
+# ESPFlash
+An abstraction layer that simplifies the storing of vectorised data in the filesystem on the ESP8266 and ESP32.
+
+ESPFlash is a lightweight library that was created to make SPIFFS usage simple and easy to understand on the ESP8266 and ESP32. 
+
+## Features
+- Simple template based interface to store and retrieve generic vectorised data in flash memory using SPIFFS with ESPFlash.
+- Implementation of simple SPIFFS based integer counter with ESPFlashCounter.
+- Implementation of simple SPIFFS based string storer using ESPFlashString.
+
+## Why Would I Want This?
+- ESPFlash enables the storage of generic data in a persistant matter. This is data that will exist through multiple power cycles or software resets.
+- ESPFlash takes care of a lot of the nastiness that exists when using SPIFFS using the concept of vectorised data. This includes the following functionailty:
+  - Automatically starts SPIFFS if it has not already been started.
+  - Automatically truncates filenames that are over 32 characters in length.
+  - Calculates the number of generic "elements" stored in a file.
+  - Overwrites elements.
+  - Appends elements.
+  - Gets elements.
+  - Clears elements.
+  
+## One Thing to Keep In Mind
+SPIFFS is not particularly fast. It is not designed to be used in a manner that requires high-throughput data input/output. ESPFlash does not significantly increase the performance issues of SPIFFS, but you should consider if SPIFFS usage is suitable for your application. 
+  
+## Installation
+Download this file as a zip, and extract the resulting folder into your Arduino Libraries folder. See [Installing Additional Arduino Libraries](https://www.arduino.cc/en/Guide/Libraries). Alternatively, use the Arduino IDE and library manager to find and install ESPFlash.
+
+## Examples
+The blog post [ESPFlash: An Arduino Library for Storing Data in the ESP Filesystem](https://dalegi.com/2020/04/22/espflash-an-arduino-library-for-storing-data-in-the-esp-filesystem/) contains some useful comparisons between ESPFlash usage and SPIFFS usage. In addition, here are some basic ESPFlash example:
+- Simple ESPFlash integer example - Create ESPFlash instance with file name of "exampleInteger". Set a single elements value, and get it back.
+```c++
+SPIFFS.begin()
+ESPFlash<int> espFlashInteger("/exampleInteger");
+espFlashInteger.set(10);
+int testInteger = espFlashInteger.get();
+```
+- Simple ESPFlash vector example - Create ESPFlash instance with file name of "exampleInteger". Append 10 randomly generated elements. Get the elements back.
+
+```c++
+SPIFFS.begin()
+ESPFlash<int> espFlashInteger("/exampleArray");
+for(int ii = 0; ii < 10; ii++)
+{
+  espFlashInteger.append(random(100));
+}
+int testGet[10];
+espFlashInteger.getFrontElements(testGet, sizeof(testGet));
+```
+- Simple ESPFlash vector example - Create ESPFlash instance with file name of "exampleInteger". Append 50 randomly generated elements. Get the last 10 elements back.
+
+```c++
+SPIFFS.begin()
+ESPFlash<int> espFlashInteger("/exampleArray");
+for(int ii = 0; ii < 50; ii++)
+{
+  espFlashInteger.append(random(100));
+}
+int testGet[10];
+espFlashInteger.getBackElements(testGet, sizeof(testGet));
+```
+
+- Simple ESPFlashCounter example - Create ESPFlashCounter instance with file name of "exampleCounter". Increment the counter. Get the Counter
+
+```c++
+SPIFFS.begin()
+ESPFlashCounter exampleCounter("/exampleCounter");
+exampleCounter.increment();
+int testGet = exampleCounter.get();
+```
+
+- Simple ESPFlashString example - Create ESPFlashString instance with file name of "exampleString". Set a string. Get the string.
+
+```c++
+SPIFFS.begin()
+ESPFlashCounter exampleString("/exampleString");
+exampleString.set("Hello!");
+String string = exampleString.get();
+```
+
+## Further Examples  
+[millisArray.ino](examples/millisArray/millisArray.ino)
+
+[powerCycleCounter.ino](examples/powerCycleCounter/powerCycleCounter.ino)
+
+[ssidStorage.ino](examples/ssidStorage/ssidStorage.ino)
+
+