📅 Tue, Sep 5, 2023 ⏲️ ~ 4 minutes

Save ESP32 variables and the Preferences library

The preferences.h library is a tool provided by the Arduino framework for the ESP32 that facilitates the storage and retrieval of configuration data in the device’s flash memory.

It is designed to be a replacement for the EEPROM library, as an alternative for storing variables in non-volatile memory (NVS), which persist between ESP32 reboots.

The preferences.h library optimizes the use of flash memory and allows fast and efficient access to the stored data. It is designed to work with many small values, rather than a few large ones.

Using `preferences.h`

Including the library

To start using preferences.h, include the library in your program:

#include <Preferences.h>

Creating a `Preferences` object

Before using preferences.h, you need to create a Preferences object that will represent the preferences storage space. You can do this as follows:

Preferences preferences;

Initializing and opening the storage space

Before accessing the preferences, you need to initialize and open the storage space. This is done by calling the begin() method of the Preferences object:

bool begin(const char* name, bool readOnly=false, const char* partition_label=NULL)

name: Name of the namespace. The maximum length is 15 characters.
readOnly:
- false will open the namespace in read/write mode.
- true will open the namespace in read-only mode. If omitted, the namespace will be opened in read/write mode.
partition_label: name of the NVS partition in which the namespace will be opened.

If omitted, the namespace will be opened in the “nvs” partition.

preferences.begin("my_variables", false);

Storing and retrieving values

Once the storage space is open, you can store and retrieve values using the putX and getX methods, where X represents the data type you want to store/retrieve (e.g., putInt, getInt, putFloat, getFloat, etc.).

// Store an integer
preferences.putInt("integer_value", 42);

// Retrieve an integer
int myInteger = preferences.getInt("integer_value", 0); // The second argument is the default value if the preference is not found

// Store a floating point value
preferences.putFloat("float_value", 3.14);

// Retrieve a floating point value
float myFloat = preferences.getFloat("float_value", 0.0);

Deleting a variable

bool remove("my_variable");

Closing the storage space

Remember to close the storage space once you have finished working with the preferences:

preferences.end();

Code example

#include <Preferences.h>
#include <WiFi.h>

const char* ssid = "network-name";
const char* password = "network-password";

Preferences preferences;

void setup() {
  preferences.begin("my_variables", false);
  preferences.putString("network_name", ssid);
  preferences.putString("network_password", password);
  preferences.end();
  
  // Rest of the initialization code, connecting to WiFi, etc.
}

Additional functions

Some useful additional functions, as found in the preferences.h file:

 bool begin(const char * name, bool readOnly=false, const char* partition_label=NULL);
void end();

bool clear();
bool remove(const char * key);

size_t putChar(const char* key, int8_t value);
size_t putUChar(const char* key, uint8_t value);
size_t putShort(const char* key, int16_t value);
size_t putUShort(const char* key, uint16_t value);
size_t putInt(const char* key, int32_t value);
size_t putUInt(const char* key, uint32_t value);
size_t putLong(const char* key, int32_t value);
size_t putULong(const char* key, uint32_t value);
size_t putLong64(const char* key, int64_t value);
size_t putULong64(const char* key, uint64_t value);
size_t putFloat(const char* key, float_t value);
size_t putDouble(const char* key, double_t value);
size_t putBool(const char* key, bool value);
size_t putString(const char* key, const char* value);
size_t putString(const char* key, String value);
size_t putBytes(const char* key, const void* value, size_t len);

bool isKey(const char* key);

PreferenceType getType(const char* key);
int8_t getChar(const char* key, int8_t defaultValue = 0);
uint8_t getUChar(const char* key, uint8_t defaultValue = 0);
int16_t getShort(const char* key, int16_t defaultValue = 0);
uint16_t getUShort(const char* key, uint16_t defaultValue = 0);
int32_t getInt(const char* key, int32_t defaultValue = 0);
uint32_t getUInt(const char* key, uint32_t defaultValue = 0);
int32_t getLong(const char* key, int32_t defaultValue = 0);
uint32_t getULong(const char* key, uint32_t defaultValue = 0);
int64_t getLong64(const char* key, int64_t defaultValue = 0);
uint64_t getULong64(const char* key, uint64_t defaultValue = 0);
float_t getFloat(const char* key, float_t defaultValue = NAN);
double_t getDouble(const char* key, double_t defaultValue = NAN);
bool getBool(const char* key, bool defaultValue = false);
size_t getString(const char* key, char* value, size_t maxLen);
String getString(const char* key, String defaultValue = String());
size_t getBytesLength(const char* key);
size_t getBytes(const char* key, void* buf, size_t maxLen);

size_t freeEntries();

Using preferences.h