ESP_EEPROM
Public Member Functions | List of all members
EEPROMClass Class Reference

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...
 

Detailed Description

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.

Calling the library

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.

Why ESP_EEPROM

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.

Layout

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.

When to use

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.

Constructor & Destructor Documentation

◆ EEPROMClass()

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.

  • EEPROM.begin(50);
  • EEPROM.put(4, myVariable);
  • EEPROM.get(4, myOtherVariable);
  • EEPROM.commit();

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'.

Member Function Documentation

◆ begin()

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.

Parameters
size

◆ commit()

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.

Returns
True if successful (or if no write was needed); false if the write was unsuccessful.

◆ commitReset()

bool EEPROMClass::commitReset ( )

Perform an erase of the flash sector before committing the data.

Returns
True is all OK; false if there was a problem.

◆ get()

template<typename T >
T& EEPROMClass::get ( int const  address,
T &  v 
)
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.

Parameters
addressThe offset of the variable with the EEPROM data
vThe variable to hold the retrieved data
Returns
The value of the retrieved variable

◆ length()

size_t EEPROMClass::length ( )
inline

Get the size of the EEPROM buffer.

Returns
The size of hte buffer

◆ percentUsed()

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)

Returns
The percentage used (0-100) or -1 if the flash does not hold any copies of the data.

◆ put()

template<typename T >
const T& EEPROMClass::put ( int const  address,
const T &  v 
)
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).

See also
commit()
Parameters
addressRelative address to which to write the data within the EEPROM buffer.
vThe variable to write to the buffer
Returns
The variable written to the buffer

◆ read()

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.

See also
get()
Parameters
addressThe offset in the data buffer to read from
Returns
The byte at the specified address.

◆ wipe()

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.

Returns
True is success; false if the erase operation failed.

◆ write()

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.

Parameters
addressThe offset with the EEPROM to which to write the data
valueThe byte of data to write to the address

The documentation for this class was generated from the following files: