88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# 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)
|
|
|
|
|