تعلّم

struct في Arduino، على ثلاثة مصابيح تومض بمعدلات مختلفة

أو تصفّح كل الدروس.

  • 526قطعة على المنضدة
  • 46لوحة تعمل الآن
  • 1.00xزمن حقيقي، على كل لوحة
لوحة Arduino Uno: ثلاثة مصابيح، كل واحد منها structمباشر0.000 s 0.00x
اضغط على الزر مع الاستمرار
كل مصباح يحتفظ بطرفه ومعدله وآخر مرة تغيّر فيها وحالته، في Lamp واحد.

struct يعطي اسمًا واحدًا لعدة قيم تنتمي إلى بعضها. struct Lamp { int pin; unsigned long everyMs; bool on; }; ينشئ نوعًا جديدًا اسمه Lamp، وكل Lamp تنشئه يحمل طرفه ومعدله وحالته الخاصة. اقرأ أو عيّن عضوًا واحدًا بالنقطة، كما في red.pin أو red.on = true، واحفظ قائمة كاملة منها في مصفوفة واحدة من البُنى.

الدائرة أعلاه ثلاثة مصابيح على Uno، كل واحد يومض بمعدله. اضغط «تشغيل». تطبع الشاشة التسلسلية "lamp on pin 13 every 250 ms"، ثم الشيء نفسه للطرفين 12 و11 عند 400 و650 ms، ثم "sizeof(Lamp) = 11". يحتفظ الكود لكل مصباح بطرفه ومعدله وآخر تغيير وحالته في struct واحد، وتمرّ loop() على المصفوفة.

فيما يلي كيفية تعريف struct وملئها، وإرجاع قيمتين من دالة، وتمرير واحدة بالمرجع، وكم حجمها، وحفظها في EEPROM، والأخطاء التي يواجهها الناس أولًا، كل ذلك على Uno مع ما طبعته.

هل تريد النسخة خطوة بخطوة؟ الدرس "الأشياء التي تنتمي إلى بعضها" يشرح ذلك مع نقاط تحقق.

افتح الدرس

عرّفها، ثم أنشئ بعضًا منها

هذا هو struct في الكود الذي يعمل أعلاه، والمصفوفة التي تنشئ ثلاثة منها. القيم داخل كل زوج من الأقواس تملأ الأعضاء بالترتيب المكتوب به: الطرف، والمعدل، وآخر وقت تغيّر، وهل هو مضاء. لذا فإن lamps[1].everyMs تساوي 400 وlamps[2].pin يساوي 11.

Adding a fourth lamp is one more line in the list. loop() counts the array with sizeof(lamps) / sizeof(lamps[0]), so it picks the new lamp up without another change. Four loose arrays of pins, rates, last-change times and states would need an edit in four places.

ينتهي تعريف struct بفاصلة منقوطة بعد القوس المغلق. احذفها ويتوقف البناء: يقول clang‏ expected ';' after struct، ويقول GCC‏ expected ';' after struct definition.

firmware/uno/examples/cppstruct (المصابيح التي تعمل أعلاه)
struct Lamp {
  int pin;
  unsigned long everyMs;
  unsigned long last;
  bool on;
};

Lamp lamps[] = {
  {LAMP_A, 250, 0, false},
  {LAMP_B, 400, 0, false},
  {LAMP_C, 650, 0, false},
};

إرجاع قيمتين من دالة واحدة

الدالة تُعيد قيمة واحدة، لكن يمكن أن تكون تلك القيمة struct، وهذا هو الجواب المعتاد عن سؤال "كيف أُرجع قيمتين من دالة". الكود أدناه يجد أدنى قراءة وأعلاها من بين خمس قراءات في تمريرة واحدة ويعيد الاثنتين في Range. وقد طبع "low 471, high 530".

الأدنى والأعلى، في Range واحد
struct Range {
  int low;
  int high;
};

Range rangeOf(const int list[], int count) {
  Range r = {list[0], list[0]};
  for (int i = 1; i < count; i++) {
    if (list[i] < r.low) r.low = list[i];
    if (list[i] > r.high) r.high = list[i];
  }
  return r;
}

void setup() {
  Serial.begin(9600);
  int readings[] = {512, 498, 530, 471, 505};
  Range r = rangeOf(readings, 5);
  Serial.print("low ");
  Serial.print(r.low);
  Serial.print(", high ");
  Serial.println(r.high);
}

void loop() {
}

افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.

مرّرها بالمرجع لتغييرها

الـ struct الذي يُمرَّر إلى دالة يُنسخ، مثل int. toggleCopy() أدناه تقلب نسختها الخاصة ويبقى مصباح المستدعي مطفأً، لذا طبع السطر الأول 0. ضع & بعد النوع فتحصل الدالة على مصباح المستدعي نفسه: toggle() طبعت 1.

المرجع أيضًا يجنّبك نسخ struct كبير، وهذا مهم مع 2 KB من الذاكرة. عندما تقرأ الدالة الـ struct فقط، فقل ذلك بـ const: void show(const Lamp &lamp). ومع مؤشر إلى struct، استخدم السهم بدلًا من النقطة: Lamp *p = &lamps[1]; p->on = false;.

نسخة، ثم المصباح نفسه
struct Lamp {
  int pin;
  bool on;
};

void toggleCopy(Lamp lamp) {
  lamp.on = !lamp.on;
}

void toggle(Lamp &lamp) {
  lamp.on = !lamp.on;
}

void setup() {
  Serial.begin(9600);
  Lamp red = {13, false};
  toggleCopy(red);
  Serial.println(red.on);
  toggle(red);
  Serial.println(red.on);
}

void loop() {
}

افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.

كم حجم struct؟

sizeof(Lamp) printed 11 on the Uno: 2 bytes for the int, 4 each for the two unsigned longs and 1 for the bool. The Uno’s chip packs members one after another with no gaps. The same struct printed 16 on an ESP32-C3, where an int is 4 bytes and members are lined up on 4-byte boundaries. Count the bytes before sending a struct from one board to another.

حفظ struct في EEPROM

EEPROM.put() يكتب struct كاملًا بايتًا بايتًا، وEEPROM.get() يقرأه مرة أخرى في متغير من النوع نفسه. حفظ الكود أدناه إعدادين وقرأهما مجددًا كـ "brightness 180, mode 2". حجم الـ struct هو 3 بايتات، لذا يمكن أن يبدأ ما يُحفظ بعده من العنوان 3. على لوحة حقيقية تنجو هذه البايتات من انقطاع الكهرباء، وهذا يجعل struct الطريقة المرتبة لحفظ الإعدادات.

إعداداتان في put() واحد
#include <EEPROM.h>

struct Settings {
  int brightness;
  byte mode;
};

void setup() {
  Serial.begin(9600);
  Settings saved = {180, 2};
  EEPROM.put(0, saved);

  Settings back;
  EEPROM.get(0, back);
  Serial.print("brightness ");
  Serial.print(back.brightness);
  Serial.print(", mode ");
  Serial.println(back.mode);
  Serial.println(sizeof(Settings));
}

void loop() {
}

افتح هذا الكود في المحررالكود وحده: يضع المحرر اللوحة والقطع التي يستطيع قراءتها من الكود.

الأخطاء التي يواجهها الناس أولًا

قيم أكثر من اللازم: إعطاء Lamp خمس قيم وهي ذات أربعة أعضاء أوقف البناء برسالة excess elements in struct initializer. يقول GCC‏ too many initializers for 'Lamp'.

استُخدم قبل أن يُعرَّف: يجب تعريف struct فوق أول سطر يستخدمه. مع كتابة struct Reading أسفل setup()، توقف السطر الموجود داخل setup() الذي أنشأ واحدًا منها عند رسالة unknown type name 'Reading'، ويقول GCC إن 'Reading' لم يُعرَّف في هذا النطاق. انقل التعريف إلى أعلى الكود، أسفل أسطر #include.

مقارنة اثنين: if (a == b) مع مصباحين توقفت عند رسالة invalid operands to binary expression ('Lamp' and 'Lamp')؛ ويقول GCC: no match for 'operator=='. لغة C++ لا تقارن البُنى (structs) من أجلك. قارن الأعضاء التي تهمّك، a.pin == b.pin && a.on == b.on، أو ضع ذلك السطر في دالة.

افتح هذه الدائرة في المحرر. Arduino Uno: ثلاثة مصابيح، كل واحد منها struct، موصولة كما تعمل في أعلى هذه الصفحة. غيّر قطعة أو قيمة ثم شغّلها مرة أخرى.

الأسئلة

ما هو الـ struct في Arduino؟

نوع تعرّفه بنفسك يجمع عدة قيم تحت اسم واحد، مثل طرف ومعدل وحالة لمصباح واحد. إنها C++ عادية، لذا تعمل على كل لوحة تدعمها Arduino، ولكل متغير من هذا النوع نسخته الخاصة من كل عضو.

كيف أنشئ مصفوفة من البُنى (structs)؟

عرِّف الـ struct، ثم أعلن عن مصفوفة منه بزوج من الأقواس المعقوفة لكل عنصر: Lamp lamps[] = {{13, 250, 0, false}, {12, 400, 0, false}}; اقرأ عضوًا بواسطة lamps[i].pin داخل حلقة for.

كيف أُرجع قيمتين من دالة في Arduino؟

أرجِع struct يحمل الاثنتين، كما تفعل rangeOf() بقيمة منخفضة وأخرى مرتفعة هنا. أو مرِّر المتغيرات بالمرجع، بوضع & بعد كل نوع، ودع الدالة تضبطها.

ما الفرق بين struct و class؟

الفرق فقط في من يمكنه رؤية الأعضاء افتراضيًا. أعضاء الـ struct عامة (public) ما لم تقل غير ذلك، وأعضاء الـ class خاصة (private). كلاهما يمكنه حمل دوال فضلًا عن قيم؛ ويميل كود Arduino إلى استخدام struct لمجموعات القيم البسيطة.

لماذا يقول الكود الخاص بي إن الـ struct لم يُعرَّف؟

الـ struct معرَّف أسفل السطر الذي يستخدمه أولًا. انقل التعريف إلى أعلى الكود، فوق setup() وفوق أي دالة تستقبل واحدًا أو تُرجعه.

المصادر

من أين جاءت الحقائق في هذه الصفحة

ابنِ هذا على أرض الواقع

افتح المحرر وغيّر قيمة وشاهد الرقم يتحرك معها. لا شيء لتثبّته ولا حاجة إلى حساب.