Preferences

Provides ESP32-compatible Preferences API for a wider variety of platforms:

• ESP8266 using LittleFS
• RP2040, RP2350 boards with Pico core
• Realtek boards with Ameba Arduino SDK
• Wio Terminal via SFUD
• Particle: Muon, Photon 2, Argon, Boron, Xenon, Tracker, BSOM, MSOM, P2

Available from: Arduino Library Manager, PlatformIO, Particle Build

How does it work?

#include <Preferences.h>
Preferences prefs;

void setup() {
  Serial.begin(115200);
  prefs.begin("my-app");

  int counter = prefs.getInt("counter", 1); // default to 1
  Serial.print("Reboot count: ");
  Serial.println(counter);
  counter++;
  prefs.putInt("counter", counter);
}

void loop() {}

Preferences are stored in the internal flash filesystem in a bunch of /nvs/{namespace}/{property} files.
Filesystem should handle flash wearing, bad sectors and atomic rename file operation.

• LittleFS handles all that, so this is the default FS driver for ESP8266. SPIFFS use is possible, but it is discouraged.
• Particle Gen3 devices also operate on a built-in LittleFS filesystem.
• Wio Terminal uses the first 8KB of external SPI flash, accessed via sfud. This is not a real filesystem: it's a simple append-only log that gets compacted once it runs out of space.

API

Check out ESP32 Preferences library API. Differences:

• partition_label argument is not supported in begin()
• getType() and freeEntries() methods are not supported (returning dummy values)
• putBytes() and putString() allow writing empty values (length = 0)
• get*() operations don't fail if the existing value has a different type, and a size mismatch is treated like a missing key (the provided default value is returned)

Important

Keys are ASCII strings. The maximum key length is 15 characters

Note

Arduino Nano 33 IoT, MKR1010, MKR VIDOR support was removed, because WiFiNINA library now provides WiFiPreferences.h natively