ESP_EEPROM
|
The ESP does not have a genuine EEPROM memory so this needs to be emulated using a segment of flash memory; this library improves upon the the standard library by avoiding excessive re-flashing of the flash memory. More...
Public Member Functions | |
EEPROMClass (void) | |
Create an instance of the EEPROM class based on the default EEPROM flash sector. More... | |
void | begin (size_t size) |
Initialise the EEPROM system, reading from flash if there appears to be suitable data already there. More... | |
uint8_t | read (int const address) |
Read a byte of data from an offset in the buffered EEPROM data. More... | |
void | write (int const address, uint8_t const val) |
Write a byte of data to an address within the the library's EEPROM data buffer. More... | |
bool | commit () |
Write the EEPROM data to the flash memory. More... | |
bool | commitReset () |
Perform an erase of the flash sector before committing the data. More... | |
bool | wipe () |
Force an immediate erase of the flash sector - but nothing is written. More... | |
int | percentUsed () |
Returns the percentage of EEPROM flash memory area that has been used by copies of our EEPROM data. More... | |
void | end () |
Free up storage used by the library. | |
template<typename T > | |
T & | get (int const address, T &v) |
Obtain EEPROM data for a variable stored at the address. More... | |
template<typename T > | |
const T & | put (int const address, const T &v) |
Write data to the EEPROM buffer. More... | |
size_t | length () |
Get the size of the EEPROM buffer. More... | |
The ESP does not have a genuine EEPROM memory so this needs to be emulated using a segment of flash memory; this library improves upon the the standard library by avoiding excessive re-flashing of the flash memory.
The library maintains a copy of your 'EEPROM' data in normal RAM which you read() and write() to. To ensure this buffered data gets saved when you power-off or reset the system you must call commit() to write the buffer to flash memory that will survive the reset. When you call begin() the library will check the flash memory and read the data there into the buffer so it is available to be read() by your program.
Including this library will create a variable call 'EEPROM' in your program which you use to access the EEPROM functions, such as EEPROM.begin(), EEPROM.read(), etc.
It is not possible to rewrite flash memory without first erasing it back to a known state. With the normal library, each commit() of the data to flash requires an erase of the flash sector. With this revised library the sector in flash memory is used to hold multiple copies of the EEPROM data. Each time you commit() data, it is written to a new area of flash until the sector is full. Only then does the library erase the sector to allow the next copy to be written.
The main drawback of erasing the flash is that it is quite slow (several 10s of ms) and during all operations on flash memory the interrupts have to be halted. Stopping interrupts will disrupt an PWM (analogWrite) outputs which can produce a noticeable disturbance in any lights attached to these. Flash memory can also only accommodate a limited number of re-flashes before it fails. This library helps extend the life of the flash memory by reducing the number of times it needs to be erased.
This implementation detail is hidden from you by the library but it may be helpful to understand what is happening 'under the hood'.
The structure held in the flash segment varies in size depending on the size requested in the call to begin().
During the begin() call, the library checks if the requested size matches the size of blocks held in the flash. If so, the bitmap is used to find the most recently written block and this is copied to the buffer held by the library. When data is written to flash using commit(), then the library updates the bitmap and writes the data to the next available area in the flash segment. If there isn't room for a new copy then the sector is erased, the size and new bitmap are written, followed by the data.
Most of the time we need a small amount to EEPROM memory to retain settings between re-boots of the system. If your application uses a lot of EEPROM, e.g. more than half a flash segment, then you will get no benefit from using this library. Normally the sector size is 4096 bytes so don't bther with this library if your EEPROM requirement is over ~2000 bytes.
EEPROMClass::EEPROMClass | ( | void | ) |
Create an instance of the EEPROM class based on the default EEPROM flash sector.
This constructor is not normally used, as including the library instantiates the required 'EEPROM' variable.
The EEPROM variable is then used to access the functions of this library.
e.g.
There should not be any reason for creating a second instance of the ESP_EEPROM class and as the library assumes there is only one instance and only one EEPROM sector results may be 'unpredictable'.
void EEPROMClass::begin | ( | size_t | size | ) |
Initialise the EEPROM system, reading from flash if there appears to be suitable data already there.
To correctly initialise the library, you need to specify the size of the EEPROM area your program will need.
This function checks the flash sector to verify if it contains correct size data. If the size is good and the bitmap is valid then the data buffer in the library is initialised from the flash memory. This is a simplistic check and you may wish to include some check value or version number within your EEPROM data to provide additional confidence that the data is really good.
If the size is wrong or the bitmap appear broken then the data buffer is zeroed. Nothing is written to the flash until you call the commit() function, which will erase the sector and write the new data.
size |
bool EEPROMClass::commit | ( | ) |
Write the EEPROM data to the flash memory.
The flash segment for EEPROM data is erased if necessary before performing the write. The library maintains a record of whether the buffer has been changed and the write to flash is only performed if the flash does not yet have a copy of the data or if the data in the buffer has changed from what is stored in the flash memory.
bool EEPROMClass::commitReset | ( | ) |
Perform an erase of the flash sector before committing the data.
|
inline |
Obtain EEPROM data for a variable stored at the address.
The variable type will determine the size of the data read from the buffer. For example the variable can be an entire struct which allows for a convenient way to maintain and access the EEPROM data.
The actual flash data is read in the begin() call and so this function only reads from the buffered data which makes it relatively fast.
address | The offset of the variable with the EEPROM data |
v | The variable to hold the retrieved data |
|
inline |
Get the size of the EEPROM buffer.
int EEPROMClass::percentUsed | ( | ) |
Returns the percentage of EEPROM flash memory area that has been used by copies of our EEPROM data.
Each commit() will write a new copy to the next free area of the segment of flash memory given over to EEPROM. This routine allows you to keep track of how much has been used to anticipate when the library will next need to do a flash erase of the EEPROM sector.
Since version 2 the return value of -1 is used to indicate that no erase/write has been done to the flash with the current sized EEPROM data. It is important to distinguish this from the case where 1 or 2 copies of a small sized EEPROM data has been written but still might amount to 0% used (when rounded to an integer)
|
inline |
Write data to the EEPROM buffer.
The function checks if the data is different from that already in the buffer.
The data is written to the internal buffer but is only written to the flash memory in the commit() function. The commit() function only writes to flash if there have been changes to the buffered data (or if the buffered data has never been written to the flash previously).
address | Relative address to which to write the data within the EEPROM buffer. |
v | The variable to write to the buffer |
uint8_t EEPROMClass::read | ( | int const | address | ) |
Read a byte of data from an offset in the buffered EEPROM data.
The data is actually read from the flash during the call to begin() so this call just read from that buffered copy and so is pretty fast.
address | The offset in the data buffer to read from |
bool EEPROMClass::wipe | ( | ) |
Force an immediate erase of the flash sector - but nothing is written.
The internal library variables & data are initialised (zeroed) but the commit() function must be called to write structure (size and bitmap etc.) and any new data to the flash.
void EEPROMClass::write | ( | int const | address, |
uint8_t const | value | ||
) |
Write a byte of data to an address within the the library's EEPROM data buffer.
This call just updates the internal data buffer. You must call commit() to actual write your data to flash so that it can be retained between restarts.
address | The offset with the EEPROM to which to write the data |
value | The byte of data to write to the address |