Salvar configurações num ESP32 com Preferences
- 526componentes na bancada
- 46placas rodando agora
- 1.00xtempo real, em todas as placas
A biblioteca Preferences é como um sketch de ESP32 lembra um número ou uma string depois que a energia acaba: uma senha de WiFi, um valor de calibração, uma contagem. Ela vem com o core do ESP32, então não há nada para instalar. Você abre um namespace com begin(), guarda e lê valores por chave com chamadas put e get do tipo certo, e o fecha com end(). Por baixo, os valores moram na NVS, um pequeno armazenamento de chave-valor na flash.
O circuito acima é um ESP32 DevKit sozinho; o monitor serial é toda a interface. Abaixo está o clássico contador de inicializações, strings com valores padrão, as regras que fazem um put retornar 0, e como isso se compara com a EEPROM.
Um contador de inicializaações
Esse é o exemplo com que a maioria dos tutoriais começa. begin("my-app", false) abre o namespace "my-app" para escrita, criando-o na primeira vez. getUInt("counter", 0) lê a chave, ou 0 quando ela ainda não existe. O sketch soma um, imprime, guarda com putUInt() e fecha o namespace.
Numa placa, todo reset e todo ciclo de energia imprime o próximo número. Aqui a primeira rodada imprimiu "Boot count: 1", e com ESP.restart() após cada contagem imprimiu "Boot count: 2" e depois "Boot count: 3", porque um restart mantém os valores guardados. O ESP32 do Mokxi não tem flash por trás, então as Preferences moram na RAM: elas sobrevivem ao ESP.restart(), e um novo Rodar ou o botão EN recomeça do 1. As chamadas e suas respostas são as do core; só a vida é mais curta.
#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 no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.
Strings, valores padrão e todos os outros tipos
Cada tipo tem seu par de chamadas: putInt/getInt, putUInt, putLong, putFloat, putBool, putString/getString e putBytes para um struct. Leia uma chave com o mesmo tipo com que guardou. Um float guardado com putFloat("t", 21.5) voltou de getFloat("t", 0) como 21.50.
Todo get recebe um valor padrão, devolvido quando a chave não existe, então a primeira rodada de um sketch não precisa de caso especial. Depois de putString("ssid", "HomeNet"), getString("ssid", "none") imprimiu "HomeNet" e getString("pass", "none") imprimiu "none". Esse é o padrão para configurações de WiFi: leia com um padrão no setup(), e só peça novas quando recebeu o padrão de volta.
isKey("ssid") imprimiu 1 enquanto a chave existia; depois de remove("ssid") imprimiu 0. clear() apaga toda chave do namespace aberto e deixa as outras em paz.
#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 no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.
Salvar um struct inteiro com putBytes
Quando um sketch tem várias configurações, mantê-las em um único struct e salvá-las em uma única chamada é mais organizado do que uma chave para cada uma. putBytes(key, &settings, sizeof(settings)) grava os bytes do struct exatamente como estão na memória, e getBytes(key, &settings, sizeof(settings)) os copia de volta. Ambas retornam o número de bytes movidos. No sketch abaixo, cada uma retornou 8, o tamanho de um int e um float em um ESP32, e o struct voltou com brilho de 180 e deslocamento de -1,50.
Confira getBytesLength(key) com sizeof antes de confiar no que você leu. Se você adicionar um campo ao struct mais tarde, a cópia guardada pela versão antiga será mais curta, e a leitura deixaria o novo campo com qualquer coisa que estivesse lá. Na primeira execução a chave ainda não existe, getBytesLength() retorna 0, e o sketch mantém os valores padrão com que começou. Aqui ele imprimiu 0 antes do primeiro put e 8 depois dele.
#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 no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.
Quando um put retorna 0
Todo put retorna o número de bytes gravados, e 0 quando não gravou nada. putUInt() retornou 4 com uma chave válida. Quatro erros fazem ele retornar 0, e cada um foi cometido aqui de 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.
As chaves pertencem a cada namespace. Uma chave gravada em "wifi" não foi encontrada a partir de "other", que retornou seu padrão, 99. Duas bibliotecas podem usar cada uma uma chave chamada "mode" sem conflito, desde que usem namespaces diferentes.
Preferences ou EEPROM em um ESP32?
O ESP32 não tem chip de EEPROM. O EEPROM.h em um ESP32 é emulado em uma partição de flash: você chama EEPROM.begin(size) primeiro e EEPROM.commit() depois de escrever, ou nada é salvo. Aqui EEPROM.write(0, 42), seguido de commit(), retornou 1, e read(0) deu 42. Ele existe para sketches portados de um Uno.
Preferences é a melhor escolha para código novo. Você grava por nome em vez de por endereço, cada valor mantém seu tipo, e o NVS distribui suas escritas pelas páginas da partição, o que importa porque a flash se desgasta após muitos ciclos de apagamento. De qualquer forma, escreva quando um valor muda, não a cada passada de loop().
Abra este circuito no editor. ESP32 DevKit: o monitor serial, ligado como aparece no topo desta página. Mude um componente ou um valor e rode de novo.
Perguntas
Onde a biblioteca Preferences do ESP32 guarda os dados?
No NVS, um armazenamento de chave-valor em uma partição da flash, então os valores sobrevivem a resets e quedas de energia. No Mokxi eles ficam na RAM, que sobrevive a ESP.restart() mas não a um novo Rodar.
Why does my Preferences put return 0?
A chave ou o namespace tem mais de 15 caracteres, begin() não foi chamado ou falhou, ou o namespace foi aberto apenas para leitura com begin(name, true).
Como salvo uma string com o Preferences do ESP32?
prefs.putString("ssid", value) para guardar e prefs.getString("ssid", "none") para ler de volta, com "none" retornado quando nunca foi guardado.
Devo usar Preferences ou EEPROM em um ESP32?
Preferences. O ESP32 não tem EEPROM, e o EEPROM.h emula uma na flash e precisa de commit(). Preferences guarda valores tipados por nome.
O que é o link de preferências do ESP32 para o Arduino IDE?
É a URL do gerenciador de placas que vai na própria janela de Preferências do IDE: https://espressif.github.io/arduino-esp32/package_esp32_index.json, do guia de instalação da Espressif.
Continuar
Monte isto de verdade
Abra o editor, mude um valor e veja o número mudar junto. Nada para instalar, e não precisa de conta.