Belajar

Menyimpan pengaturan di ESP32 dengan Preferences

Atau lihat semua pelajaran.

  • 526komponen di meja kerja
  • 46board sedang berjalan
  • 1.00xwaktu nyata, di semua board
ESP32 DevKit: Serial Monitorlive0.000 s 0.00x
Klik untuk membukanya di editor
Tempel sketch Preferences dari bawah ke editor dan tekan Jalankan.

Library Preferences adalah cara sketch ESP32 mengingat sebuah angka atau string setelah daya mati: kata sandi WiFi, nilai kalibrasi, sebuah hitungan. Library ini sudah ada bersama core ESP32, jadi tidak ada yang perlu dipasang. Kamu membuka namespace dengan begin(), menyimpan dan membaca nilai berdasarkan key dengan panggilan put dan get bertipe yang tepat, lalu menutupnya dengan end(). Di bawahnya, nilai tersimpan di NVS, sebuah key-value store kecil di flash.

Rangkaian di atas hanyalah ESP32 DevKit sendiri; serial monitor adalah seluruh antarmukanya. Di bawah ini adalah boot counter klasik, string dengan nilai bawaan, aturan yang membuat put mengembalikan 0, dan perbandingannya dengan EEPROM.

Boot counter

Ini contoh yang paling banyak dipakai tutorial untuk memulai. begin("my-app", false) membuka namespace "my-app" untuk menulis, dan membuatnya saat pertama kali. getUInt("counter", 0) membaca key itu, atau 0 bila belum ada. Sketch menambah satu, mencetaknya, menyimpannya dengan putUInt() lalu menutup namespace.

Di board, setiap reset dan setiap power cycle mencetak angka berikutnya. Di sini run pertama mencetak "Boot count: 1", dan dengan ESP.restart() setelah tiap hitungan tercetak "Boot count: 2" lalu "Boot count: 3", karena restart menjaga nilai yang tersimpan. ESP32 di Mokxi tidak punya flash di belakangnya, jadi Preferences hidup di RAM: nilainya bertahan lewat ESP.restart(), dan Run baru atau tombol EN memulai lagi dari 1. Panggilan dan jawabannya milik core; hanya umurnya yang lebih pendek.

Boot counter dengan 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() {
}

Buka sketch ini di editorKodenya saja: editor menempatkan board dan komponen yang bisa dibacanya dari sketch.

String, nilai bawaan, dan tipe lainnya

Tiap tipe punya pasangan panggilannya sendiri: putInt/getInt, putUInt, putLong, putFloat, putBool, putString/getString, dan putBytes untuk struct. Baca key dengan tipe yang sama seperti saat menyimpannya. Float yang disimpan dengan putFloat("t", 21.5) kembali dari getFloat("t", 0) sebagai 21.50.

Setiap get menerima nilai bawaan, dikembalikan saat key tidak ada, jadi run pertama sebuah sketch tidak butuh kasus khusus. Setelah putString("ssid", "HomeNet"), getString("ssid", "none") mencetak "HomeNet" dan getString("pass", "none") mencetak "none". Itulah pola untuk pengaturan WiFi: baca dengan nilai bawaan di setup(), dan hanya minta yang baru saat kamu mendapat nilai bawaan itu kembali.

isKey("ssid") mencetak 1 selama key ada; setelah remove("ssid") ia mencetak 0. clear() menghapus semua key di namespace yang terbuka dan membiarkan yang lain tetap ada.

String dengan nilai bawaan
#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() {
}

Buka sketch ini di editorKodenya saja: editor menempatkan board dan komponen yang bisa dibacanya dari sketch.

Menyimpan seluruh struct dengan putBytes

Kalau sebuah sketch punya beberapa pengaturan, lebih rapi menyimpannya dalam satu struct dan menyimpannya sekali panggil daripada satu key untuk masing-masing. putBytes(key, &settings, sizeof(settings)) menyimpan byte struct apa adanya di memori, dan getBytes(key, &settings, sizeof(settings)) menyalinnya kembali. Keduanya mengembalikan jumlah byte yang dipindahkan. Pada sketch di bawah, masing-masing mengembalikan 8, ukuran int dan float di ESP32, dan struct kembali dengan brightness 180 dan offset -1,50.

Cek getBytesLength(key) terhadap sizeof sebelum kamu mempercayai apa yang kamu baca. Kalau kamu menambahkan field ke struct nanti, simpanan dari versi lama lebih pendek, dan membacanya akan membuat field baru berisi apa pun yang ada di situ. Pada Run pertama key belum ada, getBytesLength() mengembalikan 0, dan sketch mempertahankan nilai bawaan yang dipakainya dari awal. Di sini hasil cetaknya 0 sebelum put pertama dan 8 setelahnya.

Pengaturan dalam 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() {
}

Buka sketch ini di editorKodenya saja: editor menempatkan board dan komponen yang bisa dibacanya dari sketch.

Saat put mengembalikan 0

Setiap put mengembalikan jumlah byte yang disimpan, dan 0 saat tidak menyimpan apa pun. putUInt() mengembalikan 4 untuk key yang benar. Empat kesalahan membuatnya mengembalikan 0, dan masing-masing sengaja dilakukan di sini:

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.

Key berlaku per namespace. Key yang disimpan di bawah "wifi" tidak ditemukan dari "other", yang mengembalikan nilai bawaannya, 99. Dua library bisa sama-sama memakai key bernama "mode" tanpa bentrok, asalkan keduanya memakai namespace yang berbeda.

Preferences atau EEPROM di ESP32?

ESP32 tidak punya chip EEPROM. EEPROM.h di ESP32 diemulasikan di partisi flash: kamu memanggil EEPROM.begin(size) dulu dan EEPROM.commit() setelah menulis, atau tidak ada yang tersimpan. Di sini EEPROM.write(0, 42), lalu commit(), mengembalikan 1, dan read(0) memberi 42. Itu ada untuk sketch yang dipindahkan dari Uno.

Preferences adalah pilihan yang lebih baik untuk kode baru. Kamu menyimpan berdasarkan nama, bukan alamat, setiap nilai mempertahankan tipenya, dan NVS menyebarkan penulisannya ke halaman-halaman partisi, yang penting karena flash aus setelah banyak siklus hapus. Apa pun pilihanmu, tulis saat nilai berubah, bukan di setiap putaran loop().

Buka rangkaian ini di editor. ESP32 DevKit: Serial Monitor, dengan kabel seperti saat program dijalankan di bagian atas halaman ini. Ubah satu komponen atau nilai lalu jalankan lagi.

Pertanyaan

Di mana library Preferences ESP32 menyimpan data?

Di NVS, penyimpan key-value di satu partisi flash, jadi nilai tetap ada setelah reset dan kehilangan daya. Di Mokxi nilainya disimpan di RAM, yang bertahan melewati ESP.restart() tapi tidak melewati Run baru.

Why does my Preferences put return 0?

Key atau namespace lebih panjang dari 15 karakter, begin() tidak dipanggil atau gagal, atau namespace dibuka read-only dengan begin(name, true).

Bagaimana cara menyimpan string dengan ESP32 Preferences?

prefs.putString("ssid", value) untuk menyimpannya dan prefs.getString("ssid", "none") untuk membacanya kembali, dengan "none" dikembalikan saat tidak pernah disimpan.

Haruskah aku pakai Preferences atau EEPROM di ESP32?

Preferences. ESP32 tidak punya EEPROM, dan EEPROM.h mengemulasikannya di flash dan butuh commit(). Preferences menyimpan nilai bertipe berdasarkan nama.

Apa link preferences ESP32 untuk Arduino IDE?

Itu adalah URL boards manager yang dimasukkan di jendela Preferences milik IDE itu sendiri: https://espressif.github.io/arduino-esp32/package_esp32_index.json, dari panduan instalasi Espressif.

Rakit versi nyatanya

Buka editor, ubah sebuah nilai, dan lihat angkanya ikut berubah. Tidak ada yang perlu dipasang, dan tidak perlu akun.