Table of Contents

The API for Preferences is simple and easy to use. Here’s a breakdown of the typical operations:

1. Include the Preferences Library:

#include <Preferences.h>

2. Create a Preferences Object:

  • You can create a Preferences object with a specific namespace. The namespace is used to group preferences together.
Preferences preferences;

3. Begin the Preferences Object (Open the Namespace):

  • Before accessing any stored data, you need to open a namespace with begin().
preferences.begin("myAppNamespace", false);  // false = Read/Write mode
  • The second parameter (false in this case) indicates whether you want to open the namespace in read-write mode. If you only need read access, use true.

4. Set (Write) Data:

  • You can store data using the put methods. Here’s how to store an integer, float, and string.
preferences.putInt("userAge", 30);        // Store an integer
preferences.putFloat("userHeight", 5.9);  // Store a float
preferences.putString("userName", "John");  // Store a string

5. Get Data:

  • To retrieve the data, you use the get methods corresponding to the type you want to retrieve.
int userAge = preferences.getInt("userAge", 0);        // Default value: 0
float userHeight = preferences.getFloat("userHeight", 0.0);  // Default value: 0.0
String userName = preferences.getString("userName", "Guest");  // Default value: "Guest"

6. Remove Data:

  • You can delete a specific key from storage using the remove method.
preferences.remove("userAge");

7. End the Preferences Object (Close the Namespace):

  • After you’re done, close the namespace with end() to release resources.
preferences.end();

Example Code:

Here’s a simple example demonstrating how to store and retrieve data using the Preferences library:

#include <Preferences.h>

Preferences preferences;

void setup() {
  Serial.begin(115200);

  // Open Preferences with "myApp" namespace
  preferences.begin("myApp", false);  // Open in read-write mode

  // Write some data
  preferences.putInt("deviceID", 12345);
  preferences.putString("userName", "Alice");

  // Retrieve the data
  int deviceID = preferences.getInt("deviceID", -1);  // Default: -1 if not found
  String userName = preferences.getString("userName", "Unknown");

  Serial.println("Device ID: " + String(deviceID));
  Serial.println("User Name: " + userName);

  // Optionally, remove data
  preferences.remove("deviceID");

  // Close Preferences
  preferences.end();
}

void loop() {
  // Nothing to do here
}

Advantages of Preferences:

  • Simplicity: The API is very straightforward and easy to use for simple key-value data.
  • Efficient: Designed for small data storage with minimal overhead.
  • Persistence: Data remains even after reboots, as it is stored in non-volatile storage.
  • No Need for File Management: Unlike file systems (like LittleFS), Preferences handles only key-value data, so there’s no need to deal with files or directories.

Limitations:

  • Limited Storage: The NVS partition on the ESP32 is limited to around 64 KB, so it’s not suitable for large files or complex data structures.
  • No File Operations: It’s only for key-value storage; you cannot use it to store large files, organize data into directories, or do file-based operations.

Summary:

The Preferences library is ideal for storing small, persistent pieces of data like settings, flags, or counters on the ESP32. It is a lightweight, efficient solution for scenarios where you need quick access to small amounts of data that must persist across reboots. If you need to store larger files or complex data structures, LittleFS or an SD card would be better options.

Categorized in:

Storage,

Tagged in: