Arduino library 路 Core

The Arduino EEPROM library: memory that keeps its value

The ATmega chips on most Arduinos have a small EEPROM next to their flash: 1 KB on the Uno, Nano and Leonardo, 4 KB on the Mega, 512 bytes on an ATtiny85. Unlike RAM it keeps what was written when the power goes, so it is where a sketch keeps a high score, a calibration value or the last setting a user picked. EEPROM.h reads and writes it a byte at a time, or a whole variable at once.

Built in on Mokxi: #include <EEPROM.h> and it builds, with nothing to install. Free, and no account needed.

What EEPROM does

Each byte of EEPROM survives about 100,000 writes, which sounds like a lot until a sketch writes the same address in loop() a hundred times a second and wears it out in a quarter of an hour. That is why update() exists: it reads the byte first and only writes when the value changes. put() uses update() for every byte of the variable.

A fresh chip reads 255 (0xFF) at every address. ESP32 and ESP8266 boards have no real EEPROM; their cores emulate it in flash, and need EEPROM.begin(size) before use and EEPROM.commit() after writing. On the ESP32 the Preferences library is the better choice for new code.

Library Manager nameEEPROM
AuthorArduino
Include#include <EEPROM.h>
Boardsevery board Mokxi compiles for
In the simulatorRuns, with a gap the note below names.

Install it

It builds on every board Mokxi compiles for.

In Mokxi it is built in: #include <EEPROM.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board it comes with the board package (Arduino), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.

ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 ATtiny85 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi

The calls you will use

In the order a sketch meets them.

EEPROM.read(address)

Returns the byte at an address from 0 to EEPROM.length() - 1. An address never written returns 255.

EEPROM.write(address, value)

Writes one byte, 0 to 255. It always writes, even when the value is already there, and takes about 3.3 ms on an AVR.

EEPROM.update(address, value)

Writes the byte only if it differs from what is stored, which saves the chip鈥檚 limited write cycles.

EEPROM.put(address, data)

Writes any variable or struct, byte by byte with update(). The next free address is address + sizeof(data).

struct Settings { int threshold; float gain; };
Settings s = {512, 1.5};
EEPROM.put(0, s);

EEPROM.get(address, data)

Reads a variable or struct back into data, the same size put() wrote.

EEPROM.length()

The size of the EEPROM in bytes, so a loop can clear or dump all of it.

EEPROM.begin(512)

The ESP32 and ESP8266 call: sets aside that many bytes of emulated EEPROM in RAM. Other boards accept it and ignore it.

EEPROM.commit()

On the ESP boards, copies the RAM buffer to flash. Without it, writes are lost at the next reset.

Example: EEPROM: memory that survives a reset

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino 路 Arduino Uno R3
// EEPROM: a few bytes the Uno keeps when it is switched off.
//
// The ATmega328P has 1024 bytes of EEPROM beside its RAM. RAM forgets
// everything at reset; EEPROM does not. Each byte can be written about
// 100,000 times, so it is for settings and counts, not for things that change
// every millisecond.
//
// EEPROM.put(address, value) writes a value of any type, taking as many bytes
// as it needs; EEPROM.get(address, variable) reads it back. Here address 0
// holds an int (2 bytes), address 2 a long (4 bytes), and address 6 a count
// of how many times the sketch has started.
//
// Press the board's reset (or Stop and Run again) and the count goes up.

#include <EEPROM.h>

const int INT_ADDRESS = 0;
const int LONG_ADDRESS = 2;
const int COUNT_ADDRESS = 6;

void setup() {
  Serial.begin(9600);
  Serial.println("Mokxi Uno: EEPROM");

  int smallIn = 2000;
  long bigIn = 65539;
  EEPROM.put(INT_ADDRESS, smallIn);
  EEPROM.put(LONG_ADDRESS, bigIn);

  int smallOut = 0;
  long bigOut = 0;
  EEPROM.get(INT_ADDRESS, smallOut);
  EEPROM.get(LONG_ADDRESS, bigOut);
  Serial.print("int read back: ");
  Serial.println(smallOut);
  Serial.print("long read back: ");
  Serial.println(bigOut);

  byte starts = EEPROM.read(COUNT_ADDRESS);
  if (starts == 255) starts = 0;  // a blank EEPROM reads 255 everywhere
  starts++;
  EEPROM.update(COUNT_ADDRESS, starts);
  Serial.print("this sketch has started ");
  Serial.print(starts);
  Serial.println(starts == 1 ? " time" : " times");
}

void loop() {
}

Open it in the editor, wired and ready to run 路 EEPROM: memory that survives a reset: the project page

Common errors and how to fix them

The value comes back as 255, or as -1 from an int

Nothing has been written there yet: an erased EEPROM byte is 0xFF, and two of them read into an int is -1. Write a known value first, or keep a magic number at address 0 to tell a fresh chip from a saved one.

Writes are lost after a reset on an ESP32 or ESP8266

On those boards EEPROM is a copy in RAM. Call EEPROM.begin(size) in setup() and EEPROM.commit() after writing, or move to the Preferences library on the ESP32.

A float or long saved with write() reads back wrong

write() and read() handle one byte, so a multi-byte value is cut down to its lowest byte. Use put() and get(), which store and load every byte of the variable.

The saved value stopped changing after weeks of use

That address has probably worn out from being written in loop(). Write only when the value really changes (update() or put() help), and if you must log often, move to a new address each time.

Try EEPROM without installing anything

Open the example, change the sketch, and keep your version in a free account.