حفظ الإعدادات على ESP32 باستخدام Preferences
أو تصفّح كل الدروس.
- 526قطعة على المنضدة
- 46لوحة تعمل الآن
- 1.00xزمن حقيقي، على كل لوحة
مكتبة Preferences هي الطريقة التي يتذكّر بها كود ESP32 رقمًا أو نصًّا بعد انقطاع الطاقة: كلمة مرور WiFi، أو قيمة معايرة، أو عدّادًا. تأتي مع إصدار ESP32 core، فلا حاجة لتثبيت أي شيء. تفتح فضاء أسماء (namespace) بـ begin()، وتخزّن القيم وتقرؤها بالمفتاح باستخدام استدعاءات put وget بالنوع الصحيح، ثم تغلقه بـ end(). في الأسفل، تُحفظ القيم في NVS، وهو مخزن صغير للمفاتيح والقيم داخل الذاكرة الفلاشية.
الدائرة أعلاه هي ESP32 DevKit بمفرده، والشاشة التسلسلية هي الواجهة كلها. في الأسفل عدّاد الإقلاع الكلاسيكي، والنصوص مع القيم الافتراضية، والقواعد التي تجعل put تعيد 0، وكيف تقارن بـ EEPROM.
عدّاد إقلاع
هذا هو المثال الذي تبدأ به معظم الدروس. الدالة begin("my-app", false) تفتح فضاء الأسماء "my-app" للكتابة، وتنشئه في المرة الأولى. والدالة getUInt("counter", 0) تقرأ المفتاح، أو تعيد 0 إذا لم يكن موجودًا بعد. يضيف الكود واحدًا، ويطبعه، ويخزّنه بـ putUInt() ثم يغلق فضاء الأسماء.
على لوحة حقيقية، كل إعادة ضبط وكل فصل وتشغيل للطاقة يطبع الرقم التالي. هنا طبع أول تشغيل "Boot count: 1"، ومع ESP.restart() بعد كل عدّ طُبع "Boot count: 2" ثم "Boot count: 3"، لأن إعادة التشغيل تحتفظ بالقيم المخزنة. لوحة ESP32 في Mokxi لا تحمل ذاكرة فلاشية خلفها، لذا تعيش Preferences في RAM: تنجو من ESP.restart()، لكن ضغطة «تشغيل» جديدة أو زر EN تبدأ العد من 1 من جديد. الاستدعاءات ونتائجها هي نفسها في الإصدار core، فقط مدة الحياة أقصر.
#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() {
}افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.
النصوص والقيم الافتراضية وكل الأنواع الأخرى
لكل نوع زوج خاص به من الاستدعاءات: putInt/getInt، وputUInt، وputLong، وputFloat، وputBool، وputString/getString، وputBytes للبنى (struct). اقرأ المفتاح بالنوع نفسه الذي خزّنته به. القيمة العشرية المخزنة بـ putFloat("t", 21.5) عادت من getFloat("t", 0) بقيمة 21.50.
كل استدعاء get يأخذ قيمة افتراضية تُعاد عندما يكون المفتاح غائبًا، لذا لا يحتاج أول تشغيل للكود إلى معالجة خاصة. بعد putString("ssid", "HomeNet")، طبع الاستدعاء getString("ssid", "none") النص "HomeNet"، وطبع getString("pass", "none") النص "none". هذا هو النمط المتبع لإعدادات WiFi: اقرأها بقيمة افتراضية في setup()، ولا تطلب قيمًا جديدة إلا إذا حصلت على القيمة الافتراضية.
طبع الاستدعاء isKey("ssid") القيمة 1 طالما المفتاح موجود؛ وبعد remove("ssid") طبع 0. أما clear() فيحذف كل المفاتيح في فضاء الأسماء المفتوح ويترك بقية الفضاءات كما هي.
#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() {
}افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.
حفظ بنية كاملة باستخدام putBytes
عندما يحتوي الكود على عدة إعدادات، من الأنظف أن تجمعها في struct واحد وتحفظها في استدعاء واحد بدلًا من مفتاح لكل إعداد. putBytes(key, &settings, sizeof(settings)) يخزّن بايتات الـstruct كما هي في الذاكرة، وgetBytes(key, &settings, sizeof(settings)) ينسخها بالاتجاه المعاكس. كلتاهما تعيد عدد البايتات التي نقلتها. في الكود أدناه أعاد كل منهما 8، وهو حجم int وfloat على ESP32، وعاد الـstruct بسطوع 180 وإزاحة بقيمة -1.50.
قارن getBytesLength(key) بـsizeof قبل أن تثق بما قرأته. إذا أضفت حقلًا إلى الـstruct لاحقًا، فستكون النسخة المخزنة من النسخة القديمة أقصر، وقراءتها سيترك الحقل الجديد يحمل ما كان موجودًا هناك من قبل. عند التشغيل الأول لا يكون المفتاح موجودًا بعد، وتعيد getBytesLength() القيمة 0، فيحتفظ الكود بالقيم الافتراضية التي بدأ بها. هنا طُبع 0 قبل أول تخزين و8 بعده.
#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() {
}افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.
عندما يعيد put القيمة 0
كل استدعاء put يعيد عدد البايتات التي خزّنها، ويعيد 0 عندما لا يخزّن شيئًا. أعادت putUInt() القيمة 4 لمفتاح صالح. أربعة أخطاء تجعلها تعيد 0، وقد ارتُكب كل منها هنا عمدًا:
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.
المفاتيح خاصة بكل مساحة أسماء. مفتاح خُزّن تحت "wifi" لم يُعثر عليه من "other"، التي أعادت قيمتها الافتراضية 99. يمكن لمكتبتين أن تستخدم كل منهما مفتاحًا اسمه "mode" دون تعارض، ما دامتا تستخدمان مساحتي أسماء مختلفتين.
Preferences أم EEPROM على ESP32؟
لا يوجد في ESP32 شريحة EEPROM. ملف EEPROM.h على ESP32 محاكى داخل قسم في ذاكرة flash: تستدعي EEPROM.begin(size) أولًا ثم EEPROM.commit() بعد الكتابة، وإلا فلن يُحفظ شيء. هنا EEPROM.write(0, 42) ثم commit() أعادت 1، وأعطى read(0) القيمة 42. وهي موجودة من أجل أكواد منقولة من Uno.
تفضيلات «Preferences» هي الخيار الأفضل للكود الجديد. فأنت تحفظ بالاسم لا بالعنوان، وتحتفظ كل قيمة بنوعها، وتوزّع NVS عمليات الكتابة على صفحات القسم، وهذا مهم لأن ذاكرة الفلاش تتلف بعد دورات محو كثيرة. وفي كلتا الحالتين، اكتب القيمة عندما تتغيّر فقط، لا في كل دورة من loop().
افتح هذه الدائرة في المحرر. ESP32 DevKit: الشاشة التسلسلية، موصّلة كما تعمل في أعلى هذه الصفحة. غيّر قطعة أو قيمة ثم شغّلها من جديد.
الأسئلة
أين تخزّن مكتبة Preferences الخاصة بـ ESP32 البيانات؟
في NVS، وهو مخزن من نوع مفتاح-قيمة داخل قسم من ذاكرة الفلاش، لذا تحافظ القيم على حالتها بعد إعادة التشغيل وانقطاع الطاقة. أما في Mokxi فتُحفظ في ذاكرة RAM، التي تنجو من ESP.restart() لكنها لا تنجو من الضغط على «تشغيل» من جديد.
Why does my Preferences put return 0?
لأن المفتاح أو النطاق (namespace) أطول من 15 حرفًا، أو لأنه لم يتم استدعاء begin() أو فشل الاستدعاء، أو لأن النطاق فُتح للقراءة فقط باستخدام begin(name, true).
كيف أحفظ نصًا باستخدام ESP32 Preferences؟
استخدم prefs.putString("ssid", value) لحفظه، وprefs.getString("ssid", "none") لقراءته مجددًا، حيث تُرجع "none" إذا لم يكن قد حُفظ من قبل.
هل أستخدم Preferences أم EEPROM على ESP32؟
استخدم Preferences. فلوحة ESP32 لا تحتوي على EEPROM، ومكتبة EEPROM.h تحاكيها في ذاكرة الفلاش وتحتاج إلى commit(). أما Preferences فتحفظ القيم المُعرَّفة النوع بالاسم.
ما هو رابط تفضيلات ESP32 لبيئة Arduino IDE؟
هذا هو عنوان URL لمدير اللوحات الذي يُوضع في نافذة التفضيلات الخاصة بالبيئة نفسها: https://espressif.github.io/arduino-esp32/package_esp32_index.json، وهو مأخوذ من دليل التثبيت الخاص بـ Espressif.
واصل
من أين جاءت الحقائق في هذه الصفحة
ابنِ هذا على أرض الواقع
افتح المحرر وغيّر قيمة وشاهد الرقم يتحرك معها. لا شيء لتثبّته ولا حاجة إلى حساب.