IoT-For-Beginners/translations/ar/TROUBLESHOOTING.md

دليل استكشاف الأخطاء وإصلاحها

هذا الدليل يساعدك في حل المشاكل الشائعة عند العمل مع منهج إنترنت الأشياء للمبتدئين. تم تنظيم المشاكل حسب الفئة لسهولة التنقل.

جدول المحتويات

• مشاكل التثبيت
  • تثبيت بايثون
  • VS Code والإضافات
  • PlatformIO (جهاز Wio Terminal)
  • مكتبات Grove
• مشاكل الأجهزة
  • راسبيري باي
  • Wio Terminal
  • الجهاز الافتراضي (CounterFit)
• مشاكل الاتصال
  • اتصال WiFi
  • خدمات السحابة
  • MQTT
• مشاكل الحساسات والمشغلات
  • حساسات Grove
  • الكاميرا
  • الميكروفون ومكبر الصوت
• مشاكل بيئة التطوير
  • VS Code
  • بيئات بايثون الافتراضية
  • التبعيات
• مشاكل الأداء
• رسائل الخطأ الشائعة
• الحصول على المساعدة

---

مشاكل التثبيت

تثبيت بايثون

المشكلة: إصدار بايثون قديم جدًا

الخطأ: Python 3.6 or higher is required

الحل:

1. قم بتنزيل أحدث إصدار من بايثون 3 من python.org
2. أثناء التثبيت على نظام ويندوز، قم بتحديد خيار "Add Python to PATH"
3. تحقق من التثبيت:

   python3 --version
   

المشكلة: تعدد إصدارات بايثون يسبب تعارضات

الأعراض: تشغيل إصدار بايثون خاطئ، تثبيت الحزم في موقع خاطئ

الحل:

• ويندوز: استخدم py -3 بدلاً من python لاستدعاء بايثون 3 صراحةً
• ماك/لينكس: استخدم python3 بدلاً من python
• دائمًا أنشئ واستخدم بيئات افتراضية للمشاريع

المشكلة: أمر pip غير معروف

الخطأ: 'pip' is not recognized as an internal or external command

الحل:

1. جرب pip3 بدلاً من pip
2. أو استخدم python -m pip أو python3 -m pip
3. تأكد من إضافة بايثون إلى PATH (أعد تثبيت بايثون مع تحديد الخيار)

VS Code والإضافات

المشكلة: امتداد Pylance لا يعمل

الأعراض: لا يوجد IntelliSense للبايثون، أو إكمال الشفرة، أو التحقق من الأنواع

الحل:

1. افتح لوحة الأوامر في VS Code (Ctrl+Shift+P أو Cmd+Shift+P)
2. شغّل "Python: Select Interpreter"
3. اختر مفسر البايثون الصحيح (بيئة افتراضية إذا كنت تستخدم واحدة)
4. أعد تحميل نافذة VS Code

المشكلة: VS Code لا يكتشف البيئة الافتراضية

الأعراض: اختيار مفسر بايثون خاطئ

الحل:

1. تأكد من تفعيل البيئة الافتراضية في الطرفية
2. افتح لوحة الأوامر وشغّل "Python: Select Interpreter"
3. اختر المفسر من مجلد .venv
4. تحقق من شريط الحالة (أسفل اليسار) لعرض إصدار بايثون الصحيح

PlatformIO (جهاز Wio Terminal)

المشكلة: فشل تثبيت PlatformIO

الخطأ: أخطاء مختلفة أثناء تثبيت PlatformIO

الحل:

1. تأكد من تحديث VS Code
2. قم بتثبيت إضافة C/C++ أولاً
3. أعد تشغيل VS Code بعد تثبيت PlatformIO
4. تحقق من اتصال الإنترنت (PlatformIO يحمل ملفات كبيرة)

المشكلة: لم يتم اكتشاف اللوحة بواسطة PlatformIO

الأعراض: لا يمكن رفع الكود إلى Wio Terminal

الحل:

1. جرب استخدام كابل USB مختلف (بعض الكابلات للشحن فقط)
2. تحقق من إدارة الأجهزة (ويندوز) أو استخدم الأمر ls /dev/tty* (ماك/لينكس)
3. ثبّت أو حدّث تعريفات USB
4. جرب منفذ USB مختلف
5. حرّك مفتاح التشغيل في Wio Terminal مرتين بسرعة للدخول إلى وضع الـ bootloader

المشكلة: أخطاء الترجمة في PlatformIO

الخطأ: fatal error: Arduino.h: No such file or directory

الحل:

1. احذف مجلد .pio في مشروعك
2. شغّل "PlatformIO: Rebuild" من لوحة الأوامر
3. تأكد من أن platformio.ini به إعدادات اللوحة الصحيحة:

   [env:seeed_wio_terminal]
   platform = atmelsam
   board = seeed_wio_terminal
   framework = arduino
   

مكتبات Grove

المشكلة: فشل استيراد مكتبة Grove على راسبيري باي

الخطأ: ModuleNotFoundError: No module named 'grove'

الحل:

1. أعد تثبيت مكتبات Grove:

   cd ~
   git clone https://github.com/Seeed-Studio/grove.py
   cd grove.py
   sudo pip3 install .
   

2. إذا كنت تستخدم بيئة افتراضية، قد تحتاج لتثبيتها عالميًا أو نسخ المكتبات
3. تحقق من تفعيل I2C: sudo raspi-config nonint do_i2c 0

المشكلة: حساس Grove غير مكتشف

الخطأ: IOError: [Errno 121] Remote I/O error

الحل:

1. تحقق من الاتصالات المادية (تأكد من إدخال كابل Grove بالكامل)
2. تأكد من توصيل الحساس بالمنفذ الصحيح (تناظري، رقمي، I2C، UART)
3. شغّل الأمر i2cdetect -y 1 لترى إذا كان الجهاز يظهر على ناقل I2C
4. جرب كابل Grove مختلف
5. تأكد من أن قاعدة Grove Base Hat مثبتة بشكل صحيح على دبابيس GPIO في راسبيري باي

---

مشاكل الأجهزة

راسبيري باي

المشكلة: راسبيري باي لا يقلع

الأعراض: لا يوجد عرض، لا نشاط LED، أو شاشة قوس قزح

الحل:

1. تحقق من مصدر الطاقة: استخدم مزود طاقة 5 فولت 3 أمبير USB-C رسمي للـ Pi 4
2. مشاكل بطاقة SD:
   • أعد تهيئة بطاقة SD وأعد تثبيت نظام تشغيل Raspberry Pi OS
   • جرب بطاقة SD مختلفة (استخدم العلامات الموصى بها)
   • تأكد من إدخال بطاقة SD بشكل صحيح
3. تحقق من اتصال HDMI: جرب كلا منفذي HDMI في Pi 4، استخدم المنفذ الأقرب لمصدر الطاقة

المشكلة: لا يمكن الاتصال بـ SSH على راسبيري باي

الأعراض: تم رفض الاتصال أو انتهاء المهلة

الحل:

1. تفعيل SSH:
   • عند تفليش بطاقة SD باستخدام Raspberry Pi Imager، قم بضبط SSH في الخيارات المتقدمة
   • أو أنشئ ملف فارغ باسم ssh (بدون امتداد) في قسم الإقلاع
2. العثور على عنوان IP للبي:
   • تحقق من الأجهزة المتصلة على جهاز التوجيه الخاص بك
   • استخدم الأمر ping raspberrypi.local (إذا كانت خدمة mDNS تعمل)
   • استخدم أدوات فحص الشبكة مثل nmap أو Angry IP Scanner
3. تحقق من الشبكة:
   • تأكد أن البي على نفس الشبكة مع جهاز الكمبيوتر
   • جرب الاتصال بكابل Ethernet بدلاً من WiFi
4. تحقق من اسم المستخدم/كلمة المرور (الافتراضي: المستخدم pi وكلمة المرور raspberry)

المشكلة: قاعدة Grove Base Hat غير معروفة

الأعراض: الحساسات لا تعمل، أخطاء I2C

الحل:

1. تأكد من تثبيت القاعدة بشكل صحيح على جميع دبابيس GPIO
2. تحقق من عدم وجود دبابيس منحنية على البي أو القاعدة
3. تفعيل واجهة I2C:

   sudo raspi-config nonint do_i2c 0
   sudo reboot
   

4. تحقق من عمل I2C: i2cdetect -y 1

المشكلة: راسبيري باي يعمل ببطء

الأعراض: واجهة المستخدم بطيئة، استجابة متأخرة

الحل:

1. تحقق من سرعة بطاقة SD (استخدم فئة 10 أو أفضل، أو SSD عبر USB)
2. وفر مساحة على القرص: استخدم df -h للتحقق واحذف الملفات غير الضرورية
3. قلل من ذاكرة GPU في raspi-config إذا لم تكن تستخدم الكاميرا أو العرض بشكل مكثف
4. أغلق التطبيقات غير الضرورية
5. فكر في الترقية إلى Pi 4 بذاكرة RAM أكبر إذا كنت تستخدم Pi 3 أو إصدار أقدم

Wio Terminal

المشكلة: شاشة Wio Terminal تبقى فارغة

الأعراض: لا يوجد إخراج عرض بعد رفع الكود

الحل:

1. تحقق من أن الكود يقوم بتهيئة العرض (مكتبة TFT_eSPI)
2. حدّث برنامج Wio Terminal من ويكي Seeed
3. أضف كود تهيئة العرض:

   #include <TFT_eSPI.h>
   TFT_eSPI tft;
   tft.begin();
   tft.fillScreen(TFT_BLACK);
   

4. جرب رفع مثال من PlatformIO لاختبار الجهاز

المشكلة: WiFi لا يعمل على Wio Terminal

الأعراض: لا يمكن الاتصال بشبكة WiFi، أخطاء في الشبكة

الحل:

1. تحديث برنامج WiFi الثابت: اتبع دليل تحديث WiFi لـ Wio Terminal
2. تحقق من بيانات الاعتماد: تأكد من صحة اسم الشبكة وكلمة المرور
3. نطاق WiFi: Wio Terminal يدعم فقط WiFi بتردد 2.4GHz (ليس 5GHz)
4. قوة الإشارة: اقترب من جهاز التوجيه
5. إعدادات الموجه: قد لا تعمل بعض الشبكات المؤسسية أو WPA-Enterprise

المشكلة: Wio Terminal غير معروف من قبل الكمبيوتر

الأعراض: الجهاز USB غير مكتشف

الحل:

1. جرب كابل USB مختلف: استخدم كابل بيانات، وليس للشحن فقط
2. ادخل وضع bootloader: حرّك مفتاح التشغيل لأسفل مرتين بسرعة
   • يجب أن يومض LED أزرق، ويظهر الجهاز كـ "Arduino" في إدارة الأجهزة
3. تثبيت التعريفات (ويندوز):
   • قم بتنزيل وتثبيت تعريف USB الخاص بـ Seeed
4. جرب منفذ USB مختلف: تجنب محور USB، استخدم اتصالًا مباشرًا
5. تحديث تعريفات USB للنظام

المشكلة: الحساسات لا تعمل على Wio Terminal

الأعراض: حساسات Grove لا تقرأ بيانات

الحل:

1. تحقق من توصيل كابل Grove
2. تحقق من استخدام المنفذ الصحيح لـ Grove (الأيسر أو الأيمن)
3. اضمن إدراج المكتبات الصحيحة للحساس
4. تحقق من متطلبات الطاقة للحساس
5. اختبر الحساس باستخدام كود المثال من المكتبة

الجهاز الافتراضي (CounterFit)

المشكلة: تطبيق CounterFit لا يبدأ

الخطأ: أخطاء بايثون مختلفة عند بدء CounterFit

الحل:

1. تأكد من تفعيل البيئة الافتراضية
2. قم بتثبيت/إعادة تثبيت CounterFit:

   pip install CounterFit
   

3. تحقق من أن المنفذ 5000 غير مستخدم:
   • ويندوز: netstat -ano | findstr :5000
   • ماك/لينكس: lsof -i :5000
4. أوقف العملية التي تستخدم المنفذ 5000 أو استخدم منفذًا مختلفًا:

   counterfit --port 5001
   

المشكلة: لا يمكن الاتصال بـ CounterFit من الشفرة

الخطأ: تم رفض الاتصال أو انتهاء المهلة

الحل:

1. تحقق من تشغيل CounterFit: افتح المتصفح على http://127.0.0.1:5000
2. تحقق من عنوان الاتصال في الشفرة يطابق عنوان CounterFit
3. تأكد من عدم وجود جدار ناري يمنع الاتصال
4. جرب إعادة تشغيل تطبيق CounterFit والشفرة الخاصة بك

المشكلة: الحساسات لا تظهر في CounterFit

الأعراض: الحساسات المنشأة لا تظهر في واجهة المستخدم لـ CounterFit

الحل:

1. أنشئ الحساسات في واجهة CounterFit قبل تشغيل الشفرة
2. حدّث صفحة المتصفح
3. تحقق من نوع الحساس يطابق المتوقع في الشفرة
4. نظّف ذاكرة التخزين المؤقت للمتصفح

---

مشاكل الاتصال

اتصال WiFi

المشكلة: الجهاز لا يمكنه الاتصال بشبكة WiFi

الأعراض: انتهاء مهلة الاتصال، فشل التحقق من الهوية

الحل:

1. تحقق من اسم الشبكة وكلمة المرور: تأكد من صحة بيانات الاعتماد
2. نطاق WiFi: معظم أجهزة إنترنت الأشياء تدعم فقط 2.4GHz (وليس 5GHz)
3. إعدادات الموجه:
   • تعطيل عزل نقاط الوصول إذا كان مفعلًا
   • استخدم أمان WPA2-PSK (تجنب WPA3، WEP أو الشبكات المفتوحة)
   • تأكد من تفعيل DHCP
4. شبكات مخفية: إذا كان اسم الشبكة مخفيًا، قد تحتاج لتكوينه صراحةً
5. قوة الإشارة: قرب الجهاز من الموجه
6. التداخل: أجهزة أخرى، الميكروويف، أو الجدران قد تسبب تداخلات

المشكلة: انقطاع اتصال WiFi بشكل متكرر

الأعراض: اتصال متقطع

الحل:

1. تحقق من استقرار الموجه وفكر في إعادة تشغيله
2. حدّث البرنامج الثابت للجهاز
3. استخدم عنوان IP ثابت بدلاً من DHCP
4. قلل المسافة إلى الموجه أو أضف موسع WiFi
5. تحقق من التداخل من أجهزة أخرى
6. تأكد من أن مصدر الطاقة كافٍ (خصوصًا لراسبيري باي)

خدمات السحابة

المشكلة: لا يمكن الاتصال بـ Azure IoT Hub

الخطأ: فشل التحقق من الهوية، تم رفض الاتصال

الحل:

1. تحقق من بيانات الاعتماد:
   • تأكد من صحة سلسلة الاتصال
   • لا توجد مسافات أو فواصل أسطر إضافية في سلسلة الاتصال
2. تحقق من تسجيل الجهاز: يجب تسجيل الجهاز في IoT Hub
3. جدار حماية / وكيل: تأكد من السماح بخروج MQTT (المنفذ 8883) أو HTTPS (المنفذ 443)
4. منطقة IoT Hub: تأكد من تشغيل IoT Hub وليس في منطقة مختلفة تسبب تأخيرًا
5. حدود الحصة: تحقق من عدم تجاوز حدود الطبقة المجانية
6. اختبر الاتصال:

   az iot hub device-identity show-connection-string --hub-name YourIoTHub --device-id YourDevice
   

المشكلة: Azure Functions لا تعمل

الأعراض: تم إرسال الرسائل لكن الوظيفة لا تنفذ

الحل:

1. تحقق من أن تطبيق الوظائف قيد التشغيل (ليس متوقفًا)
2. تحقق من سلسلة الاتصال في إعدادات تطبيق الوظائف
3. راجع سجلات الوظائف في بوابة Azure
4. تأكد من تكوين نقطة نهاية متوافقة مع Event Hub بشكل صحيح
5. تحقق من تنسيق الرسائل يتوافق مع توقعات الوظيفة
6. تحقق من خطة خدمة تطبيق الوظائف (الاستهلاك مقابل المخصصة)

MQTT

المشكلة: فشل الاتصال بـ MQTT

الخطأ: اتصال مرفوض، فشل في المصادقة

الحل:

1. عنوان الوسيط: تحقق من أن عنوان URL/IP الخاص بالوسيط صحيح
2. المنفذ: تحقق من رقم المنفذ (1883 للاتصال غير المشفر، 8883 لـ TLS)
3. المصادقة: تحقق من اسم المستخدم/كلمة المرور إذا كانت مطلوبة
4. TLS/SSL: تأكد من أن الشهادات صالحة وموثوقة
5. جدار الحماية: تحقق من أن المنفذ غير محظور
6. اختبر باستخدام عميل MQTT: استخدم MQTT Explorer أو mosquitto_pub/sub للاختبار

المشكلة: لم تصل رسائل MQTT

الأعراض: تم نشر الرسائل لكن المشتغلين عليها لم يستلموها

الحل:

1. أسماء المواضيع: تحقق من أن موضوع المشترك يطابق بالضبط موضوع الناشر
2. مستوى QoS: جرب QoS 1 أو 2 بدلاً من 0
3. المتغيرات العامة: تحقق من استخدام المتغيرات العامة في الموضوع بشكل صحيح (+ لمستوى واحد، # لعدة مستويات)
4. الرسائل المحتفظ بها: يمكن للناشر تعيين علم الاحتفاظ للاحتفاظ بآخر رسالة
5. توقيت الاتصال: تأكد من أن المشترك يتصل قبل نشر الرسائل

---

مشكلات الحساسات والمشغلات

حساسات جروف

المشكلة: الحساس يعيد قيم غير صحيحة

الأعراض: القراءات 0، -1، أو قيم غير منطقية

الحل:

1. تحقق من الاتصالات: تأكد من توصيل الحساس بشكل صحيح
2. المنفذ الصحيح: تحقق من أن الحساس في نوع المنفذ الصحيح:
   • الحساسات التناظرية → منافذ تناظرية (A0, A2, A4)
   • الحساسات الرقمية → منافذ رقمية (D5, D16, D18، إلخ)
   • حساسات I2C → منافذ I2C
3. المعايرة: بعض الحساسات تحتاج إلى معايرة (رطوبة التربة، الضوء)
4. إعادة تشغيل الطاقة: فصل ثم توصيل الحساس
5. ورقة بيانات الحساس: تحقق من مواصفات ومتطلبات الحساس

المشكلة: حساس رطوبة التربة السعوي يقرأ دائماً أنه مبلل

الأعراض: يقرأ الحساس رطوبة عالية حتى عندما يكون جافًا

الحل:

1. تحتاج إلى معايرة: حساسات التربة تحتاج إلى معايرة:
   • اقرأ القيمة في الهواء (الخط الأساسي الجاف)
   • اقرأ القيمة في الماء (الخط الأساسي المبلل)
   • اربط القراءات بين هاتين القيمتين
2. تحقق من طلاء الحساس: يمكن أن تتلف حساسات الرطوبة إذا تلف الطلاء
3. الموضع: تأكد من أن الحساس مدخل كاملاً في التربة

المشكلة: قراءات حساس درجة الحرارة/الرطوبة غير صحيحة

الأعراض: DHT11/DHT22 تظهر درجة حرارة أو رطوبة خاطئة

الحل:

1. موضع الحساس: تجنب التعرض المباشر للشمس أو مصادر الحرارة أو تيار الهواء
2. زمن التسخين: انتظر 2 ثانية بعد تشغيل الحساس قبل القراءة
3. تردد القراءة: حساسات DHT تحتاج إلى وقت بين القراءات (لا يقل عن ثانيتين)
4. تحقق من التكثف: يمكن أن يؤثر على القراءات
5. جودة الحساس: DHT11 أقل دقة من DHT22

الكاميرا

المشكلة: الكاميرا غير مكتشفة على Raspberry Pi

الخطأ: mmal: mmal_vc_component_create: failed to create component 'vc.ril.camera'

الحل:

1. تفعيل واجهة الكاميرا:

   sudo raspi-config
   

اذهب إلى خيارات الواجهة → الكاميرا → تمكين
2. تحقق من كابل الشريط: تأكد من إدخال كابل الكاميرا بشكل صحيح

• الجانب الأزرق يواجه منافذ USB على Pi Zero
• الجانب الأزرق يواجه بعيدًا عن منافذ USB على Pi 4

3. تحديث البرنامج الثابت:

   sudo apt update
   sudo apt full-upgrade
   sudo reboot
   

4. اختبر الكاميرا:

   raspistill -o test.jpg
   

المشكلة: صور الكاميرا ذات جودة ضعيفة

الأعراض: صور ضبابية، داكنة، أو باهتة

الحل:

1. التركيز: أزل الفيلم الواقي عن العدسة، وضبط التركيز إذا كان قابلاً للتعديل
2. الإضاءة: تأكد من توفر إضاءة كافية
3. إعدادات الكاميرا: ضبط التعريض، ISO، توازن اللون الأبيض في الكود
4. الثبات: حافظ على ثبات الكاميرا، استخدم حامل ثلاثي الأرجل إذا لزم الأمر
5. الدقة: لا تتجاوز أقصى دقة للكاميرا

الميكروفون ومكبر الصوت

المشكلة: لا يوجد إدخال أو إخراج صوتي

الأعراض: الميكروفون لا يسجل، ومكبر الصوت لا يصدر صوتًا

الحل:

1. تحقق من الاتصالات: تحقق من توصيل أجهزة الصوت بشكل صحيح
2. اختبر العتاد:
   • مكبر الصوت: speaker-test -t wav -c 2
   • الميكروفون: arecord -l للقائمة، arecord test.wav للتسجيل
3. إعدادات الصوت: تحقق واضبط الصوت:

   alsamixer
   

4. اختر جهاز الصوت: حدد الجهاز الصحيح في الكود
5. مشكلات التعريفات: قم بتحديث ALSA أو أعد تثبيت برامج التشغيل

المشكلة: بطاقة ReSpeaker لا تعمل

الأعراض: جهاز الصوت غير مكتشف

الحل:

1. تثبيت التعريفات:

   git clone https://github.com/HinTak/seeed-voicecard
   cd seeed-voicecard
   sudo ./install.sh
   sudo reboot
   

2. تحقق من التثبيت: يجب أن تعرض arecord -l بطاقة ReSpeaker
3. تحديث البرنامج الثابت: بعض نسخ نظام Pi OS تحتاج تحديثات تعريف
4. تحقق من التوصيل: تأكد من توصيل البطاقة بشكل صحيح على دبابيس GPIO

---

مشكلات بيئة التطوير

VS Code

المشكلة: الطرفية لا تفعل البيئة الافتراضية تلقائياً

الأعراض: تفتح الطرفية لكن البيئة الافتراضية غير مفعلة

الحل:

1. حدد مفسر بايثون: قائمة الأوامر → "Python: Select Interpreter" → اختر venv
2. أعد تشغيل VS Code بعد اختيار المفسر
3. تحقق من الإعدادات: في settings.json، أضف:

   "python.terminal.activateEnvironment": true
   

المشكلة: الكود لا يعمل على الجهاز

الأعراض: الكود يعمل لكن لا يحدث شيء على الجهاز

الحل:

1. تأكد من حفظ الكود (تحقق من وجود نقطة على لسان الملف)
2. تحقق من أي بايثون يعمل: which python أو where python
3. لـ Wio Terminal: تأكد من رفع الكود عبر PlatformIO (انقر زر الرفع)
4. لـ Raspberry Pi: ادخل عبر SSH وشغل الكود هناك
5. تحقق من نافذة الإخراج للأخطاء

المشكلة: IntelliSense لا يعرض دوال المكتبات

الأعراض: لا يظهر الإكمال التلقائي للوحدات المستوردة

الحل:

1. تأكد من تثبيت المكتبة في البيئة الحالية
2. أعد تحميل نافذة VS Code
3. تحقق من اختيار مفسر بايثون الصحيح
4. ثبت الحزم الخاصة بالأنواع إذا كانت متاحة: pip install types-<اسم-المكتبة>

البيئات الافتراضية في بايثون

المشكلة: لا يمكن إنشاء بيئة افتراضية

الخطأ: The virtual environment was not created successfully

الحل:

1. تثبيت وحدة venv:
   • أوبونتو/ديبيان: sudo apt install python3-venv
   • macOS: مضمّن مع بايثون عادة
   • ويندوز: أعد تثبيت بايثون مع كل المكونات
2. التحقق من تثبيت بايثون: تحقق من تثبيت بايثون بشكل صحيح
3. استخدم المسار الكامل: جرب python3 -m venv .venv مع نداء python3 الصريح

المشكلة: الحزم مثبتة في مكان خاطئ

الأعراض: خطأ في الاستيراد بعد تثبيت الحزمة

الحل:

1. تأكد من تفعيل venv: يجب أن يظهر سطر الأوامر (.venv)
2. تحقق من موقع pip: which pip يجب أن يشير إلى .venv/bin/pip
3. أعد التثبيت في venv: فعّل venv ثم pip install <package>
4. لا تستخدم sudo مع pip في البيئة الافتراضية

المشكلة: البيئة الافتراضية غير قابلة للنقل

الأعراض: البيئة لا تعمل بعد نقلها أو على جهاز مختلف

الحل:

1. لا تنقل venv: احذفها وأعد إنشاؤها في المكان الجديد
2. استخدم requirements.txt:

   pip freeze > requirements.txt
   pip install -r requirements.txt
   

3. أعد إنشاء venv:

   python3 -m venv .venv
   source .venv/bin/activate  # أو activate.bat على ويندوز
   pip install -r requirements.txt
   

التبعيات

المشكلة: فشل تثبيت الحزمة

الخطأ: أخطاء متعددة في pip أثناء التثبيت

الحل:

1. تحديث pip:

   pip install --upgrade pip
   

2. تثبيت أدوات البناء:
   • أوبونتو/ديبيان: sudo apt install build-essential python3-dev
   • macOS: xcode-select --install
   • ويندوز: تثبيت أدوات بناء Visual Studio
3. تحقق من اتصال الإنترنت
4. جرب فهرس حزم مختلف: pip install --index-url https://pypi.org/simple/ <package>
5. ثبت إصدار محدد: pip install <package>==<version>

المشكلة: تعارض التبعيات

الخطأ: ERROR: pip's dependency resolver does not currently take into account all the packages that are installed

الحل:

1. استخدم بيئة افتراضية جديدة لكل مشروع
2. تحديث الحزم: pip install --upgrade <package>
3. تحقق من المتطلبات: استخدم pip check للعثور على التعارضات
4. ثبت الإصدارات المتوافقة: حدد نطاقات الإصدارات في requirements.txt

---

مشكلات الأداء

المشكلة: الكود يعمل ببطء

الأعراض: تأخيرات، مهلات، سلوك غير مستجيب

الحل:

1. قلل تكرار قراءة الحساس: لا تقرأ الحساسات بشكل متكرر جداً
2. حسّن الحلقات: تجنب الانتظار المشغول، استخدم sleep() أو تأخيرات
3. مشكلات الذاكرة:
   • أغلق التطبيقات غير الضرورية
   • حرر مساحة التخزين
   • راقب باستخدام top أو htop على Pi
4. سرعة بطاقة SD: استخدم بطاقة SD أسرع أو SSD لـ Raspberry Pi
5. تأخيرات الشبكة: استخدم عمليات غير متزامنة للاتصالات الشبكية

المشكلة: أخطاء نفاد الذاكرة

الخطأ: MemoryError أو تجمد النظام

الحل:

1. لـ Raspberry Pi:
   • أغلق التطبيقات غير الضرورية
   • زِد مساحة التبديل (swap)
   • استخدم نظام تشغيل أخف (Lite)
   • زد ذاكرة الوصول العشوائي (Pi 4 يقدم 2/4/8GB)
2. لـ Wio Terminal:
   • قلل حجم المخازن المؤقتة
   • استخدم صور أصغر
   • حسّن استخدام السلاسل النصية
   • تحقق من تسريبات الذاكرة (الذاكرة غير المُفرَج عنها)

المشكلة: فقدان أو فساد البيانات

الأعراض: رسائل مفقودة، ملفات تالفة

الحل:

1. مشكلات بطاقة SD:
   • استخدم بطاقات SD عالية الجودة (تجنب الرخيصة/المزيفة)
   • نسخ احتياطية منتظمة
   • إيقاف تشغيل نظيف (لا تفصل الطاقة مباشرة)
2. تجاوز المخزن المؤقت: زد حجم المخزين في الكود
3. موثوقية الشبكة: نفّذ منطق إعادة المحاولة ومعالجة الأخطاء
4. جودة الخدمة: استخدم MQTT QoS 1 أو 2 للرسائل المهمة

---

رسائل الأخطاء الشائعة

ModuleNotFoundError: No module named 'X'

السبب: الحزمة غير مثبتة أو البيئة الافتراضية غير مفعلة

الحل:

pip install X

تأكد من تفعيل البيئة الافتراضية أولاً.

Permission denied على Linux/macOS

السبب: تحتاج صلاحيات مرتفعة أو مشكلة في صلاحيات الملفات

الحل:

• لعمليات النظام: استخدم sudo
• بالنسبة لـ pip: لا تستخدم sudo مع venv، قم بتفعيل venv أولاً
• للمنفذ التسلسلي: أضف المستخدم إلى مجموعة dialout: sudo usermod -a -G dialout $USER، ثم أعد تسجيل الخروج/تسجيل الدخول

OSError: [Errno 98] Address already in use

السبب: المنفذ مستخدم بالفعل من قبل عملية أخرى

الحل:

1. اعثر على العملية التي تستخدم المنفذ: lsof -i :<port> أو netstat -ano | findstr :<port>
2. اقطع العملية أو استخدم منفذ مختلف في الكود

SSL: CERTIFICATE_VERIFY_FAILED

السبب: فشل التحقق من شهادة SSL

الحل:

1. حدّث الشهادات: pip install --upgrade certifi
2. تحقق من صحة وقت النظام: date
3. فقط للتطوير (ليس للإنتاج): تعطيل التحقق في الكود

IndentationError: unexpected indent

السبب: مشاكل في المسافات البادئة في بايثون (خلط علامات التبويب والمسافات)

الحل:

1. استخدم تباعدًا متسقًا (4 فراغات هو معيار بايثون)
2. قم بضبط المحرر لاستخدام الفراغات بدلاً من علامات التبويب
3. في VS Code: اضبط "editor.insertSpaces": true و "editor.tabSize": 4

UnicodeDecodeError أو UnicodeEncodeError

السبب: مشاكل في ترميز الأحرف

الحل:

# عند قراءة الملفات
with open('file.txt', 'r', encoding='utf-8') as f:
    content = f.read()

# عند كتابة الملفات
with open('file.txt', 'w', encoding='utf-8') as f:
    f.write(content)

---

طلب المساعدة

إذا جربت هذه الخطوات ولم تُحل المشكلة:

1. تحقق من الموارد الموجودة

• التوثيق: راجع README وتعليمات الدرس
• أدلّة العتاد: تحقق من hardware.md لمعلومات العتاد الخاصة
• ويكي Seeed Studio: Seeed Studio Wiki لمكونات جروف

2. ابحث عن مشكلات مشابهة

• قضايا GitHub: ابحث في القضايا القائمة
• Stack Overflow: ابحث عن رسائل الخطأ
• منتديات الأجهزة: راجع منتديات Raspberry Pi أو Arduino

3. أنشئ قضية على GitHub

إذا لم تجد حلاً:

1. اذهب إلى قضايا GitHub
2. اضغط "New Issue"
3. قدم:
   • وصف واضح للمشكلة
   • خطوات التكرار
   • رسائل الخطأ (نص كامل)
   • إصدارات العتاد/البرمجيات
   • ما جربته بالفعل
   • لقطات شاشة إذا كانت ذات صلة

4. انضم للمجتمع

• Discord: Microsoft Foundry Discord
• Microsoft Learn: Microsoft Learn IoT

5. قدم تقارير أخطاء جيدة

يشمل تقرير الخطأ الجيد:

• البيئة: نظام التشغيل، إصدار بايثون، الأجهزة المستخدمة
• خطوات إعادة الإنتاج: الخطوات الدقيقة التي تسبب المشكلة
• السلوك المتوقع: ما يجب أن يحدث
• السلوك الفعلي: ما يحدث فعليًا
• رسائل الخطأ: نص الخطأ الكامل، وليس لقطات الشاشة
• الكود: مثال كود مصغر يعيد إنتاج المشكلة

---

نصائح للوقاية

أفضل الممارسات العامة

1. احتفظ بنسخ احتياطية: نسخ احتياطية منتظمة لبطاقات SD/الكود العامل
2. وثق التغييرات: سجل ما يعمل في التعليقات
3. تحكم بالإصدار: استخدم git لتتبع تغييرات الكود
4. اختبر تدريجيًا: اختبر التغييرات الصغيرة قبل الدمج
5. اقرأ رسائل الخطأ: غالبًا ما تخبرك بما هو الخطأ بالضبط
6. قم بالتحديث بانتظام: حافظ على تحديث البرامج/البرامج الثابتة
7. استخدم مكونات ذات جودة: تجنب الكابلات/مصادر الطاقة الرخيصة
8. طاقة مستقرة: استخدم مصدر طاقة مناسب (خصوصًا لبي)

سير عمل التطوير

1. ابدأ ببساطة: ابدأ بكود مثال يعمل
2. تغيير واحد في المرة: أسهل في العثور على ما يسبب العطل
3. اختبر بشكل متكرر: اكتشف الأخطاء مبكرًا
4. حافظ على النظافة: نظم الملفات والكود بشكل منطقي
5. علق على الكود: أنت في المستقبل ستقدر ذلك

---

هذا الدليل الخاص بحل المشكلات تتم صيانته من قبل المجتمع. إذا وجدت حلًا لمشكلة غير مدرجة هنا، يرجى التفكير في المساهمة لمساعدة الآخرين!

---

تنويه:
تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية Co-op Translator. بينما نسعى لضمان الدقة، يرجى العلم بأن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار الوثيقة الأصلية بلغتها الأصلية المصدر المعتمد. للمعلومات الحرجة، يُنصح بالاستعانة بترجمة بشرية احترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.