LuisLlamas Logo
esp32-preferences

Save ESP32 variables and the Preferences library

  • 4 min
  • Intermediate

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

It is designed as a replacement for the EEPROM library, serving as an alternative for saving variables in non-volatile memory (NVS), which persists across ESP32 reboots.

The preferences.h library optimizes flash memory usage and allows 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

Include the Library

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

#include <Preferences.h>
Copied!

Create a Preferences Object

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

Preferences preferences;
Copied!

Initialize and Open the Storage Namespace

Before accessing preferences, you must initialize and open the storage namespace. 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)
Copied!
  • name: Namespace name. 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 where the namespace will be opened.

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

preferences.begin("mis_variables", false);
Copied!

Store and Retrieve Values

Once the storage namespace 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("valor_entero", 42);

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

// Store a float value
preferences.putFloat("valor_flotante", 3.14);

// Retrieve a float value
float miFlotante = preferences.getFloat("valor_flotante", 0.0);
Copied!

Delete a Variable

bool remove("mi_variable");
Copied!

Close the Storage Namespace

Remember to close the storage namespace once you are done working with the preferences:

preferences.end();
Copied!

Code Example

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

const char* ssid = "nombre-de-la-red";
const char* password = "contraseña-de-la-red";

Preferences preferences;

void setup() {
  preferences.begin("mis_variables", false);
  preferences.putString("nombre_red", ssid);
  preferences.putString("password_red", password);
  preferences.end();
  
  // Rest of the initialization code, WiFi connection, etc.
}
Copied!

Additional Functions

Some useful additional functions, 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();
Copied!

On this page