Written by: Xabier Garmendia - EA2EGA. - Ingran Engineering S.L..
Based on the work of: David A. Mellis and Christopher Andrews
The EEPROM library provides an easy to use interface to interact with the internal non-volatile storage found in Indsutruino D21G based devices
This library is included in your IDE download. To add its functionality to your sketch you'll need to reference the library header file. You do this by adding an include directive to the top of your sketch.
#include <EEPROM.h>
void setup(){
EEPROM.start();
}
void loop(){
}
The library provides a global variable named EEPROM, you use this variable to access the library functions. The methods provided in the EEPROM class are listed below.
You can view all the examples here.
This function initializes the EEPROM access library. Must be called before other commands.
EEPROM.read( address ) [example]
This function allows you to read a single byte of data from the eeprom.
Its only parameter is an int which should be set to the address you wish to read.
The function returns an unsigned char containing the value read.
EEPROM.write( address, value ) [example]
The write() method allows you to write a single byte of data to the EEPROM.
Two parameters are needed. The first is an int containing the address that is to be written, and the second is a the data to be written (unsigned char).
This function does not return any value.
EEPROM.update( address, value ) [example]
This function is similar to EEPROM.write() however this method will only write data if the cell contents pointed to by address is different to value. This method can help prevent unnecessary wear on the EEPROM cells.
This function does not return any value.
EEPROM.readBit( address, bit ) [example]
This function allows you to read a single bit value from the EEPROM.
It requires two inputs: an int addressing the EEPROM cell, and an unsigned char specifiying the bit to read (in a range 0 - 7).
The function returns a bool containing the value of the bit read.
EEPROM.writeBit( address, bit, value ) [example]
The writeBit() method allows you to write a single bit of data to the EEPROM.
Three parameters are needed. The first is an int containing the address that is to be written, and the second is the index of the bit to access. The Last parameter is the data to be written (unsigned char).
This function does not return any value.
EEPROM.get( address, object ) [example]
This function will retrieve any object from the EEPROM.
Two parameters are needed to call this function. The first is an int containing the address that is to be read, and the second is the object you would like to read.
This function returns a reference to the object passed in. It does not need to be used and is only returned for conveience.
EEPROM.put( address, object ) [example]
This function will write any object to the EEPROM.
Two parameters are needed to call this function. The first is an int containing the address that is to be written, and the second is the object you would like to write.
This function uses the update method to write its data, and therefore only rewrites changed cells.
This function returns a reference to the object passed in. It does not need to be used and is only returned for conveience.
Subscript operator: EEPROM[address] [example]
This operator allows using the identifier EEPROM like an array.
EEPROM cells can be read and written directly using this method.
This operator returns a reference to the EEPROM cell.
unsigned char val;
//Read first EEPROM cell.
val = EEPROM[ 0 ];
//Write first EEPROM cell.
EEPROM[ 0 ] = val;
//Compare contents
if( val == EEPROM[ 0 ] ){
//Do something...
}This function returns an unsigned int containing the number of cells in the EEPROM.
EEPROM access takes longer than a single cycle. This function will return false if there is an operation still pending, if so, any future operations will have to wait until its completed. This may be useful for time critical applications, as all EEPROM methods wait until ready.
This function returns a bool, with the value true if the EEPROM is accessible without delay.
Note: Recapping what is said above, you do not need to call this function to use the EEPROM library, it is provided as a convenience only.
This library uses a component based approach to provide its functionality. This means you can also use these components to design a customized approach. Three background classes are available for use: EERef, EEPtr and EEBit. The three classes are implicitly used by the EEPROM object and it is essentially just a wrapper of their functionality.
This object references an EEPROM cell. Its purpose is to mimic a typical byte of RAM, however its storage is the EEPROM.
EERef ref = EEPROM[ 10 ]; //Create a reference to 11th cell.
ref = 4; //write to EEPROM cell.
unsigned char val = ref; //Read referenced cell.This object is a bidirectional pointer to EEPROM cells represented by EERef objects.
Just like a standard pointer type, this pointer can be dereferenced, repositioned and modified.
EEPtr ptr = 10; //Create a pointer to 11th cell.
*ptr = 4; //dereference and write to EEPROM cell.
unsigned char val = *ptr; //dereference and read.
val = ptr[ 4 ]; //dereference using subscript.
ptr++; //Move pointer to next EEPROM cell.
This object is a reference object similar to EERef, however it references only a single bit of data in the EEPROM. It is a background element available through all other EEPROM interfaces.
It essentially can be viewed as a boolean stored in the EEPROM.
/***
Create a reference to 11th cell, and its third bit.
Take care to note, both the cell and bit indices are
zero based.
***/
EEBit mySetting( 10, 2 );
mySetting = true; //Write a single bit to the EEPROM.
bool val = mySetting; //Read a single bit form the EEPROM.
if( mySetting ){ //Use directly in comparisons, branching.
//Do something.
}This function returns an EEPtr pointing to the first cell in the EEPROM.
This is useful for STL objects, custom iteration and C++11 style ranged for loops.
This function returns an EEPtr pointing at the location after the last EEPROM cell.
Used with begin() to provide custom iteration.
Note: The EEPtr returned is invalid as it is out of range. Infact the hardware causes wrapping of the address (overflow) and EEPROM.end() actually references the first EEPROM cell.