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 saving variables in non-volatile memory (NVS), which persist across ESP32 restarts.
The preferences.h library optimizes the use of flash memory and allows for fast and efficient access to 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 storage space for the preferences. You can do this as follows:
Preferences preferences;Initializing and opening the storage space
Before accessing the preferences, you must 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 open in read/write mode.
partition_label: name of the NVS partition in which the namespace will be opened.
If omitted, the namespace will open 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, respectively, 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 float value
preferences.putFloat("float_value", 3.14);
// Retrieve a float value
float myFloat = preferences.getFloat("float_value", 0.0);Removing 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, WiFi connection, etc.
}Additional functions
Some additional useful functions that appear 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();