Preferences (community library)

Summary

Preferences library for Arduino, ESP8266 and Particle Gen3 devices

Example Build Testing

Library Read Me

This content is provided by the library maintainer and has not been validated or approved.

Preferences

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

• ESP8266 using LittleFS
• RP2040 boards with Pico core
• Realtek boards with Ameba Arduino SDK
• Arduino Nano 33 IoT, MKR1010, MKR VIDOR using WiFiNINA storage
• Particle: Argon, Boron, Xenon, Tracker, BSOM, P2 (Photon 2)

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.
• Arduino Nano and MKR devices use the storage of the U-blox NINA module.

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)
• put*() and get*() operations don't fail if the existing value has a different type

[!IMPORTANT] Keys are ASCII strings. The maximum key length is 15 characters

Known issues

• clear() is not working on Arduino Nano 33 IoT, MKR1010, MKR VIDOR. This cannot be implemented, as WiFiNINA storage doesn't provide any API to remove or enumerate directories (along with other bugs). If you need to clear a namespace on these devices, you'll have to erase each key individually using remove().

Browse Library Files