Extended EEPROM library for Arduino

For my ongoing clock project, I want to persistently store some data. That is, store data that is retained after turning off the Arduino. The processor on the Arduino board comes with on-board EEPROM. In the case of the Arduino Uno, the processor is the Atmega328, equipped with 1 glorious KByte of EEPROM memory.

The AVR libraries that come with the ATmega implements a relatively broad set of functions for reading, writing and management of the EEPROM (for a description see the AVR user manual). However, the Arduino standard EEPROM library exposes only functionality for reading and writing a single byte, as described here.

This is why I wrote the EEPROMex library, an extension of the standard Arduino EEPROM library. It writes and reads basic types like bytes, longs, ints, floats & doubles. It can also read/write single bits, arbitrary data-formats and arrays. It adds debug functionality to identify and stop writing outside of the EEPROM memory size and excessive writing to prevent memory wear.

The library

First of all, the library can be downloaded here:

A zipped tarball of this version can be found here.

The library starts by implementing the functions as present in the default EEPROM library, so it is fully compatible. You only need to change #include <EEPROM.h> to #include <EEPROMex.h>. The following example will work with both the standard and extended EEPROM library:

Writing different data formats

The aim of the library is to also support other standard data types: it currently implements writing and reading to int, long, float and double.

For reading:
uint8_t read(int address);
uint8_t readByte(int address);
uint16_t readInt(int address);
uint32_t readLong(int address);
float readFloat(int address);
double readDouble(int address);

Where address is the starting position in EEPROM, and the return value the value read from EEPROM. For writing:
bool write(int address, uint8_t value);
bool writeByte(int address, uint8_t value);
bool writeInt(int address, uint16_t value);
bool writeLong(int address, uint32_t value);
bool writeFloat(int address, float value);
bool writeDouble(int address, double value);


Where the return value indicates if the write has been successful. Note that readByte and writeByte are the same as read and write and have only been added for naming consistency. So let us now try the following example :

Update data

The write function of the AVR library that we are using will always overwrite the existing EEPROM value, even if it is equal to the one already present. Overwriting this cell has no practical use, but will increase EEPROM wear. To solve this, I added update functionality. The update functions are different from the write functions, in that they will check per byte if the current value differs and only update the the cell with a different value. This will not only reduce wear, and can also significantly reduce write time.

bool update(int address, uint8_t value);
bool updateByte(int address, uint8_t value);
bool updateInt(int address, uint16_t value);
bool updateLong(int address, uint32_t value);
bool updateFloat(int address, float value);
bool updateDouble(int address, double);

Efficient storage, writing single bits

Depending on your requirements, you may want to be more efficient in the way you store certain values. This is particularly relevant if you want to store Boolean values: As you need only one bit to store Boolean, you can store 8 Booleans in a single byte.

The following functions implements reading and writing single bits:
bool readBit(int address, byte bit)
Where bit is the write position in the byte, ranging from [0..7], with bit 0 being the right-most. The return value is the read bit.
bool writeBit(int address, uint8_t bit, bool value)
bool updateBit(int address, uint8_t bit, bool value)


Writing data blocks

We can generalize our writing and reading functions so that they can handle any kind of data structure :

int readBlock(int address, const T& value)
int writeBlock(int address, const T& value)
int updateBlock(int address, const T& value)

where T is the type of the data to read/write/update. This can be a basic type, but also a more complex type like a struct. The return value gives the number of bytes that have been read, written or updated.

The library also supports reading and writing of arrays of a any kind of data structure. We can, for exampe, write an arrays of chars (a string), but we can also read/write, for example, arrays of structs.

int readBlock(int address, const T[]; value, int items)
int writeBlock(int address, const T[]; value, int items)
int updateBlock(int address, const T[]; value, int items)

Let’s have a look at the following example:

Address allocation

Typically, we write and store data to the EEPROM using fixed addresses, and it often proves to be a hassle to maintain them properly, such that there are not overwrites nor gaps. To simplify bookkeeping of addresses you can use the following function.

int getAddress(int noOfBytes);

The input noOfBytes indicates how many bytes your data structure are needed, the output is the first address available for writing in EEPROM. As long as you use this function to assign addresses to your variables, there will be no overlap between variables. This function is not much more than an every increasing counter and it differs from a malloc call in that there is no way to free memory. It is, however completely deterministic, which means that if acquire your address at the start of your applications, before any loops or conditional statements, every memory pointer will be the same after each reboot of the board.

Debugging options

The processor documentation (which can be found here , section 8.4) says the following about EEPROM:

The ATmega48A/PA/88A/PA/168A/PA/328/P contains 256/512/512/1Kbytes of data EEPROM memory. It is organized as a separate data space, in which single bytes can be read and written. The EEPROM has an endurance of at least 100,000 write/erase cycles.

This is may sound like a large number, but in theory you could burn out a memory cell in a few minutes: a write/erase cycle takes approximately 4 ms, so writing 100.000 times to a single cell takes 6 1/2 min. While there are some tests show much more writes before failure, they do not take into account reduction of retention time (see this article on EEPROM failure in space).

Notice how the documentation talks about write/erase rather than write. EEPROM programming consists of erasing a block (in our case a block of 8 bits, 1 byte), which means setting all bits to 0, and subsequently writing the bits that should become 1. It is the erase step that causes wear to the memory. This means that in theory we can separate the two, and overwriting an EEPROM value from 170, in bit format 10101010 to 235, in bit format 11101011 would only require writing the 2 specific bits, without erasing and causing wear. While this is possible (see the manual, section 8.6.3) it has not been implemented in the AVR function underpinning this library. (This library does not implement it either, but delivers similar functionality on byte scale using the update functions).

As said, it is easy to burn out a memory cell in few minutes, so while debugging your application it would be very useful to limit the number of allowed writes. It is easy to put a bracket at the wrong location, and placing an EEPROM write inside of a loop, rather than outside, and introduce extensive writing causing wear. The following function helps limit the number of writes.

setMaxAllowedWrites(int allowedWrites);

More writes than allowed will be refused and result in an error message. You can also set the address range used by the library:

setMemPool(int base, int memSize);

The lower value is used by the getAddress function, the upper value is used for setting the EEPROM size. Writing outside the maximum size will result in an error message. The following EEPROM sizes are predefined

Based on processor:

• EEPROMSizeATmega168
• EEPROMSizeATmega328
• EEPROMSizeATmega1280

Based on board:

• EEPROMSizeUno
• EEPROMSizeUnoSMD
• EEPROMSizeLilypad
• EEPROMSizeDuemilanove
• EEPROMSizeMega
• EEPROMSizeDiecimila
• EEPROMSizeNano

Note that these errors will only occur when _EEPROMex_DEBUG is enabled in EEPROMex.cpp. if not enabled, the checks will be optimized away during compilation. This reduced the performance overhead and memory usage of the library, so it is encouraged to disable the function after debugging.

EEPROM performance

All of the read/write functions first make sure the EEPROM is ready to be accessed. Since this may cause long delays if a write operation is still pending, time-critical applications should first poll the EEPROM e. g. using the isReady function before attempting any actual I/O:

bool isReady();

Let’s end with a slightly more extensive example that implements this and combines it with a few other functions. This example demonstrates the write speed and read speeds of the EEPROM memory:

The output of this sketch shows us a few things:

• Writing one byte does not cost time (at least less than 1 ms), but it takes the EEPROM 4 to be ready for next write).
• As a result, writing more than one byte will take more time. I would have expected writing a 4 bytes Long to take 3*4=12 ms, with a 4 ms recovery time.
• Reading data from EEPROM does not cost significant time, and it does not take time for the EEPROM to recover.
• When writing with the updateBlock instead of the writeBlock function the updateBlock is comparable when all bytes need to be changed and faster if less bytes need updating.

So, that’s it for now. Good luck using the library and let me know what you find!