EEPROM Library
Documentation for usage of the EEPROM library. EEPROM is a memory whose values are kept when the board is powered off.
The microcontroller on the Arduino and Genuino AVR based board has EEPROM: memory whose values are kept when the board is turned off (like a tiny hard drive). This library enables you to read and write those bytes.
The supported micro-controllers on the various Arduino and Genuino boards have different amounts of EEPROM: 1024 bytes on the ATmega328P, 512 bytes on the ATmega168 and ATmega8, 4 KB (4096 bytes) on the ATmega1280 and ATmega2560. The Arduino and Genuino 101 boards have an emulated EEPROM space of 1024 bytes.
To use this library
1#include <EEPROM.h>
Examples
To see a list of examples for the EEPROM library, click the link below:
Functions
read()
read()
Description
Reads a byte from the EEPROM. Locations that have never been written to have the value of 255.
Syntax
1EEPROM.read(address)
Parameters
address: the location to read from, starting from 0 (int)
Returns
the value stored in that location (byte)
Example
1#include <EEPROM.h>2
3int a = 0;4int value;5
6void setup()7{8 Serial.begin(9600);9}10
11void loop()12{13 value = EEPROM.read(a);14
15 Serial.print(a);16 Serial.print("\t");17 Serial.print(value);18 Serial.println();19
20 a = a + 1;21
22 if (a == 512)23 a = 0;24
25 delay(500);26}
write()
write()
Description
Write a byte to the EEPROM.
Syntax
1EEPROM.write(address, value)
Parameters
address: the location to write to, starting from 0 (int)
value: the value to write, from 0 to 255 (byte)
Returns
none
Note: An EEPROM write takes 3.3 ms to complete. The EEPROM memory has a specified life of 100,000 write/erase cycles, so you may need to be careful about how often you write to it.
Example
1#include <EEPROM.h>2
3void setup()4{5 for (int i = 0; i < 255; i++)6 EEPROM.write(i, i);7}8
9void loop()10{11}
update()
update()
Description
Write a byte to the EEPROM. The value is written only if differs from the one already saved at the same address.
Syntax
1EEPROM.update(address, value)
Parameters
address: the location to write to, starting from 0 (int)
value: the value to write, from 0 to 255 (byte)
Returns
none
Note: An EEPROM write takes 3.3 ms to complete. The EEPROM memory has a specified life of 100,000 write/erase cycles, so using this function instead of write() can save cycles if the written data does not change often
Example
1#include <EEPROM.h>2
3void setup()4{5 for (int i = 0; i < 255; i++) {6 // this performs as EEPROM.write(i, i)7 EEPROM.update(i, i);8 }9 for (int i = 0; i < 255; i++) {10 // write value "12" to cell 3 only the first time11 // will not write the cell the remaining 254 times12 EEPROM.update(3, 12);13 }14}15
16void loop()17{18}
get()
get()
Description
Read any data type or object from the EEPROM.
Syntax
1EEPROM.get(address, data)
Parameters
address: the location to read from, starting from 0 (int)
data: the data to read, can be a primitive type (eg. float) or a custom struct
Returns
A reference to the data passed in
Example
1#include <EEPROM.h>2
3struct MyObject{4 float field1;5 byte field2;6 char name[10];7};8
9void setup(){10
11 float f = 0.00f; //Variable to store data read from EEPROM.12 int eeAddress = 0; //EEPROM address to start reading from13
14 Serial.begin( 9600 );15 while (!Serial) {16 ; // wait for serial port to connect. Needed for Leonardo only17 }18 Serial.print( "Read float from EEPROM: " );19
20 //Get the float data from the EEPROM at position 'eeAddress'21 EEPROM.get( eeAddress, f );22 Serial.println( f, 3 ); //This may print 'ovf, nan' if the data inside the EEPROM is not a valid float.23
24 // get() can be used with custom structures too.25 eeAddress = sizeof(float); //Move address to the next byte after float 'f'.26 MyObject customVar; //Variable to store custom object read from EEPROM.27 EEPROM.get( eeAddress, customVar );28
29 Serial.println( "Read custom object from EEPROM: " );30 Serial.println( customVar.field1 );31 Serial.println( customVar.field2 );32 Serial.println( customVar.name );33}34
35void loop(){ /* Empty loop */ }
put()
put()
Description
Write any data type or object to the EEPROM.
Syntax
1EEPROM.put(address, data)
Parameters
address: the location to write to, starting from 0 (int)
data: the data to write, can be a primitive type (eg. float) or a custom struct
Returns
A reference to the data passed in
Note: This function uses EEPROM.update() to perform the write, so does not rewrites the value if it didn't change.
Example
1#include <EEPROM.h>2
3struct MyObject {4 float field1;5 byte field2;6 char name[10];7};8
9void setup() {10
11 Serial.begin(9600);12 while (!Serial) {13 ; // wait for serial port to connect. Needed for native USB port only14 }15
16 float f = 123.456f; //Variable to store in EEPROM.17 int eeAddress = 0; //Location we want the data to be put.18
19
20 //One simple call, with the address first and the object second.21 EEPROM.put(eeAddress, f);22
23 Serial.println("Written float data type!");24
25 /** Put is designed for use with custom structures also. **/26
27 //Data to store.28 MyObject customVar = {29 3.14f,30 65,31 "Working!"32 };33
34 eeAddress += sizeof(float); //Move address to the next byte after float 'f'.35
36 EEPROM.put(eeAddress, customVar);37 Serial.print("Written custom data type! \n\nView the example sketch eeprom_get to see how you can retrieve the values!");38}39
40void loop() { /* Empty loop */ }
EEPROM[]
EEPROM[]
Description
This operator allows using the identifier
EEPROM
like an array. EEPROM cells can be read and written directly using this method.Syntax
1EEPROM[address]
Parameters
address: the location to read/write from, starting from 0 (int)
Returns
A reference to the EEPROM cell
Example
1#include <EEPROM.h>2
3void setup(){4
5 unsigned char val;6
7 //Read first EEPROM cell.8 val = EEPROM[ 0 ];9
10 //Write first EEPROM cell.11 EEPROM[ 0 ] = val;12
13 //Compare contents14 if( val == EEPROM[ 0 ] ){15 //Do something...16 }17}18
19void loop(){ /* Empty loop */ }
length()
length()
This function returns an unsigned int containing the number of cells in the EEPROM.
Description
This function returns an
unsigned int
containing the number of cells in the EEPROM.Syntax
1EEPROM.length()
Returns
Number of cells in the EEPROM as an
unsigned int
.Suggest changes
The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.
License
The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.