Aprender

Guardar configuraciones en un ESP32 con Preferences

O mira todas las lecciones.

  • 526componentes en el banco de trabajo
  • 46placas funcionando ahora
  • 1.00xtiempo real, en todas las placas
ESP32 DevKit: el monitor serieen vivo0.000 s 0.00x
Haz clic para abrirlo en el editor
Pega un sketch de Preferences de los de abajo en el editor y presiona Ejecutar.

La biblioteca Preferences es la forma en que un sketch de ESP32 recuerda un número o una cadena después de que se corta la energía: una contraseña de WiFi, un valor de calibración, un contador. Viene con el núcleo ESP32, así que no hay nada que instalar. Abres un espacio de nombres con begin(), guardas y lees valores por clave con llamadas put y get del tipo correcto, y lo cierras con end(). Por debajo, los valores viven en NVS, un pequeño almacén de pares clave-valor en la flash.

El circuito de arriba es un ESP32 DevKit por sí solo; el monitor serie es toda la interfaz. Abajo está el clásico contador de arranques, cadenas con valores por omisión, las reglas que hacen que un put devuelva 0, y cómo se compara con EEPROM.

Un contador de arranques

Este es el ejemplo con el que empiezan la mayoría de los tutoriales. begin("my-app", false) abre el espacio de nombres "my-app" para escritura, creándolo la primera vez. getUInt("counter", 0) lee la clave, o 0 si todavía no existe. El sketch suma uno, lo imprime, lo guarda con putUInt() y cierra el espacio de nombres.

En una placa, cada reset y cada ciclo de energía imprime el siguiente número. Aquí la primera ejecución imprimió "Boot count: 1", y con ESP.restart() después de cada cuenta imprimió "Boot count: 2" y luego "Boot count: 3", porque un reinicio conserva los valores guardados. El ESP32 de Mokxi no tiene flash detrás, así que Preferences vive en RAM: sobrevive a ESP.restart(), y una nueva ejecución o el botón EN empieza de nuevo desde 1. Las llamadas y sus respuestas son las del núcleo; solo la vida es más corta.

Un contador de arranques con Preferences
#include <Preferences.h>

Preferences prefs;

void setup() {
  Serial.begin(115200);
  prefs.begin("my-app", false);
  unsigned int count = prefs.getUInt("counter", 0);
  count++;
  Serial.printf("Boot count: %u\n", count);
  prefs.putUInt("counter", count);
  prefs.end();
  if (count < 3) {
    delay(100);
    ESP.restart();
  }
}

void loop() {
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Cadenas, valores por omisión y todos los demás tipos

Cada tipo tiene su propio par de llamadas: putInt/getInt, putUInt, putLong, putFloat, putBool, putString/getString y putBytes para un struct. Lee una clave con el mismo tipo con el que la guardaste. Un float guardado con putFloat("t", 21.5) regresó de getFloat("t", 0) como 21.50.

Cada get recibe un valor por omisión, que se devuelve cuando falta la clave, así que la primera ejecución de un sketch no necesita un caso especial. Después de putString("ssid", "HomeNet"), getString("ssid", "none") imprimió "HomeNet" y getString("pass", "none") imprimió "none". Ese es el patrón para la configuración de WiFi: léelas con un valor por omisión en setup(), y pide nuevas solo cuando recibiste el valor por omisión.

isKey("ssid") imprimió 1 mientras la clave existía; después de remove("ssid") imprimió 0. clear() borra todas las claves del espacio de nombres abierto y deja las demás intactas.

Una cadena con valor por omisión
#include <Preferences.h>

Preferences prefs;

void setup() {
  Serial.begin(115200);
  prefs.begin("wifi", false);
  prefs.putString("ssid", "HomeNet");
  Serial.println(prefs.getString("ssid", "none"));
  Serial.println(prefs.getString("pass", "none"));
  Serial.println(prefs.isKey("ssid"));
  prefs.remove("ssid");
  Serial.println(prefs.isKey("ssid"));
  prefs.end();
}

void loop() {
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Guardar un struct completo con putBytes

Cuando un sketch tiene varias configuraciones, guardarlas en un struct y almacenarlo en una sola llamada es más ordenado que usar una clave para cada una. putBytes(key, &settings, sizeof(settings)) guarda los bytes del struct tal como están en memoria, y getBytes(key, &settings, sizeof(settings)) los copia de vuelta. Ambas funciones devuelven la cantidad de bytes que movieron. En el sketch de abajo cada una devolvió 8, el tamaño de un int y un float en un ESP32, y el struct volvió con un brillo de 180 y un desfase de -1.50.

Compara getBytesLength(key) con sizeof antes de confiar en lo que lees. Si más adelante agregas un campo al struct, la copia guardada por la versión anterior es más corta, y leerla dejaría el campo nuevo con lo que hubiera ahí. En la primera ejecución la clave todavía no existe, getBytesLength() devuelve 0, y el sketch conserva los valores predeterminados con los que empezó. Aquí imprimió 0 antes del primer put y 8 después.

Configuraciones en un struct
#include <Preferences.h>

struct Settings {
  int brightness;
  float offset;
};

Preferences prefs;
Settings settings = {128, 0.0};

void setup() {
  Serial.begin(115200);
  prefs.begin("my-app", false);
  Serial.println(prefs.getBytesLength("settings"));
  Settings changed = {180, -1.5};
  Serial.println(prefs.putBytes("settings", &changed, sizeof(changed)));
  Serial.println(prefs.getBytesLength("settings"));
  if (prefs.getBytesLength("settings") == sizeof(settings)) {
    Serial.println(prefs.getBytes("settings", &settings, sizeof(settings)));
  }
  Serial.println(settings.brightness);
  Serial.println(settings.offset);
  prefs.end();
}

void loop() {
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Cuando un put devuelve 0

Cada put devuelve la cantidad de bytes que guardó, y 0 cuando no guardó nada. putUInt() devolvió 4 con una clave válida. Cuatro errores hacen que devuelva 0, y aquí se cometió cada uno a propósito:

A key longer than 15 characters. "key_with_15chrs" stored 4 bytes; "a_key_with_16chr", one character longer, returned 0. Namespaces have the same limit, and begin("a_namespace_too_long", false) returned 0, so every call after it failed too. A namespace opened read-only: after begin("wifi", true), putUInt("x", 1) returned 0 while gets still worked. And no begin() at all: putUInt("x", 1) returned 0 and getUInt("x", 7) gave back the default, 7.

Las claves pertenecen a cada espacio de nombres. Una clave guardada bajo "wifi" no se encontró desde "other", que devolvió su valor predeterminado, 99. Dos bibliotecas pueden usar cada una una clave llamada "mode" sin conflicto, siempre que usen espacios de nombres distintos.

¿Preferences o EEPROM en un ESP32?

El ESP32 no tiene chip de EEPROM. EEPROM.h en un ESP32 se emula en una partición de flash: primero llamas a EEPROM.begin(size) y después a EEPROM.commit() tras escribir, o no se guarda nada. Aquí EEPROM.write(0, 42), y luego commit(), devolvió 1, y read(0) dio 42. Está ahí para sketches portados desde un Uno.

Preferences es la mejor opción para el código nuevo. Guardas por nombre en lugar de por dirección, cada valor conserva su tipo, y NVS reparte sus escrituras entre las páginas de la partición, lo cual importa porque la memoria flash se desgasta después de muchos ciclos de borrado. De cualquier forma, escribe cuando cambie un valor, no en cada pasada de loop().

Abre este circuito en el editor. ESP32 DevKit: el monitor serie, cableado tal como se ejecuta al inicio de esta página. Cambia un componente o un valor y ejecútalo de nuevo.

Preguntas

¿Dónde guarda datos la biblioteca Preferences del ESP32?

En NVS, un almacén de pares clave-valor en una partición de la memoria flash, así que los valores sobreviven a reinicios y cortes de energía. En Mokxi se guardan en RAM, lo que sobrevive a ESP.restart() pero no a una nueva ejecución.

Why does my Preferences put return 0?

La clave o el namespace tiene más de 15 caracteres, begin() no se llamó o falló, o el namespace se abrió en modo de solo lectura con begin(name, true).

¿Cómo guardo una cadena con Preferences del ESP32?

prefs.putString("ssid", value) para guardarla y prefs.getString("ssid", "none") para leerla de nuevo; devuelve "none" cuando nunca se guardó.

¿Debo usar Preferences o EEPROM en un ESP32?

Preferences. El ESP32 no tiene EEPROM, y EEPROM.h emula una en flash y necesita commit(). Preferences guarda valores con tipo por nombre.

¿Cuál es el enlace de preferencias del ESP32 para el IDE de Arduino?

Es la URL del gestor de placas que va en la propia ventana de Preferencias del IDE: https://espressif.github.io/arduino-esp32/package_esp32_index.json, de la guía de instalación de Espressif.

Ármalo en la vida real

Abre el editor, cambia un valor y mira cómo cambia el número con él. Nada que instalar y sin necesidad de cuenta.