ESP32 Preferences: keep settings by name across resets
Preferences is the ESP32 core鈥檚 replacement for EEPROM.h. Instead of picking byte addresses, you store values under a key inside a namespace, and the core keeps them in the NVS partition of the flash, which spreads writes around so the flash wears evenly. A WiFi password, a calibration offset or a boot counter all fit.
Built in on Mokxi: #include <Preferences.h> and it builds, with nothing to install. Free, and no account needed.
What Preferences (ESP32 core) does
Every use is begin(), the gets and puts, then end(). begin("my-app", false) opens a namespace read-write (true opens it read-only). Each get takes a default that comes back when the key has never been written, which is what makes a first boot work without special code.
Keys and namespace names are at most 15 characters, and the type you read must match the type you wrote: a value stored with putInt() does not come back from getUInt(). NVS also has a fixed size, around 20 KB on the default partition table, so it is for settings, not for logging data.
| Library Manager name | Preferences (ESP32 core) |
|---|---|
| Author | Espressif |
| Include | #include <Preferences.h> |
| Boards | ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32 |
| In the simulator | Runs, with a gap the note below names. |
Install it
It builds on ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32.
In Mokxi it is built in: #include <Preferences.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board it comes with the board package (Espressif), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.
ESP32-C3 路 ESP32-C6 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32 DevKit 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 ESP32-S3-DevKitC-1 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32
The calls you will use
In the order a sketch meets them.
Preferences preferences
The object, usually a global so setup() and loop() can both use it.
preferences.begin("my-app", false)
Opens a namespace, creating it if needed. false means read-write. Returns false if it could not be opened.
preferences.getUInt("counter", 0)
Reads an unsigned int, or the default 0 when the key is not there. There is a get for every type: getInt, getFloat, getBool, getString, getBytes.
unsigned int counter = preferences.getUInt("counter", 0);
counter++;
preferences.putUInt("counter", counter);preferences.putUInt("counter", counter)
Writes the value under the key and returns the number of bytes stored, 0 on failure.
preferences.putString("ssid", ssid)
Stores a String or a C string. getString("ssid", "") reads it back.
preferences.isKey("ssid")
True when the key exists, for telling "never set" apart from a stored default.
preferences.remove("counter")
Deletes one key. preferences.clear() deletes every key in the open namespace.
preferences.end()
Closes the namespace. Open another with begin() to switch.
Example: Keep settings by name
On the ESP32-C3-DevKitM-1. It runs in the browser exactly as printed.
#include <Preferences.h>
Preferences preferences;
void setup() {
Serial.begin(115200);
preferences.begin("my-app", false);
// On a real ESP32 this survives a reset. Here it lives in RAM, so a
// reset (or a new run) starts it again at 0.
unsigned int counter = preferences.getUInt("counter", 0);
Serial.print("Boot count: ");
Serial.println(counter + 1);
preferences.putUInt("counter", counter + 1);
preferences.putString("name", "Mokxi");
preferences.end();
}
void loop() {
preferences.begin("my-app", true);
Serial.print("name ");
Serial.print(preferences.getString("name", "none"));
Serial.print(", counter ");
Serial.println(preferences.getUInt("counter", 0));
preferences.end();
delay(1000);
}Common errors and how to fix them
A value always reads back as the default
Usually the key is longer than 15 characters and the write failed, or the read uses a different type than the write (putInt then getUInt). Check the number putUInt() returns, and read with the matching get.
nvs_open failed: NOT_FOUND
The namespace was opened read-only, begin("name", true), before anything was ever written to it. Open it read-write the first time, or ignore the message: the gets still return their defaults.
The boot counter in Mokxi always says 1
Mokxi鈥檚 ESP32 models have no flash behind Preferences, so values are kept in RAM for the run and gone after a reset. On a real board the same sketch counts up, since NVS survives power cycles.
Try Preferences (ESP32 core) without installing anything
Open the example, change the sketch, and keep your version in a free account.