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

راهنمای عیب‌یابی

این راهنما به شما کمک می‌کند تا مشکلات رایج هنگام کار با برنامه درسی اینترنت اشیاء برای مبتدیان را حل کنید. مشکلات بر اساس دسته‌بندی برای پیمایش آسان سازماندهی شده‌اند.

فهرست مطالب

• مشکلات نصب
  • نصب پایتون
  • VS Code و افزونه‌ها
  • PlatformIO (Wio Terminal)
  • کتابخانه‌های Grove
• مشکلات سخت‌افزاری
  • رسپبری پای
  • Wio Terminal
  • دستگاه مجازی (CounterFit)
• مشکلات اتصال
  • اتصال WiFi
  • خدمات ابری
  • MQTT
• مشکلات حسگر و عملگر
  • حسگرهای Grove
  • دوربین
  • میکروفون و بلندگو
• مشکلات محیط توسعه
  • VS Code
  • محیط‌های مجازی پایتون
  • وابستگی‌ها
• مشکلات عملکرد
• پیام‌های خطای رایج
• دریافت کمک

---

مشکلات نصب

نصب پایتون

مشکل: نسخه پایتون خیلی قدیمی است

خطا: Python 3.6 or higher is required

راه‌حل:

1. آخرین نسخه پایتون ۳ را از python.org دانلود کنید
2. هنگام نصب روی ویندوز، گزینه "Add Python to PATH" را انتخاب کنید
3. نصب را تأیید کنید:

   python3 --version
   

مشکل: نسخه‌های مختلف پایتون موجب تداخل شده‌اند

علائم: نسخه اشتباه پایتون اجرا می‌شود، بسته‌ها در محل اشتباه نصب می‌شوند

راه‌حل:

• ویندوز: به جای python از py -3 استفاده کنید تا به طور صریح پایتون ۳ را اجرا کنید
• مک‌اواس/لینوکس: به جای python از python3 استفاده کنید
• همیشه برای پروژه‌ها محیط مجازی ایجاد و استفاده کنید

مشکل: دستور pip پیدا نمی‌شود

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

راه‌حل:

1. به جای pip از pip3 استفاده کنید
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. پس از نصب PlatformIO، VS Code را ری‌استارت کنید
4. اتصال اینترنت خود را بررسی کنید (PlatformIO فایل‌های بزرگی دانلود می‌کند)

مشکل: برد توسط PlatformIO شناسایی نمی‌شود

علائم: امکان آپلود کد به Wio Terminal نیست

راه‌حل:

1. از کابل USB دیگری استفاده کنید (برخی کابل‌ها فقط شارژ هستند)
2. Device Manager (ویندوز) یا فرمان ls /dev/tty* (مک‌اواس/لینوکس) را بررسی کنید
3. درایورهای USB را نصب یا به‌روزرسانی کنید
4. از پورت USB دیگری استفاده کنید
5. کلید روشن/خاموش Wio Terminal را دو بار سریع بلغزانید تا وارد حالت بوتلودر شود

مشکل: خطاهای کامپایل در 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. بررسی منبع تغذیه: از منبع تغذیه رسمی ۵V 3A USB-C برای Pi 4 استفاده کنید
2. مشکلات کارت SD:
   • کارت SD را قالب‌بندی کرده و سیستم‌عامل رسپبری پای را دوباره نصب کنید
   • کارت 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. شبکه را بررسی کنید:
   • اطمینان حاصل کنید پای روی همان شبکه رایانه شماست
   • به جای WiFi از کابل اترنت استفاده کنید
4. نام کاربری/رمز عبور را بررسی کنید (پیش‌فرض: نام کاربری pi، رمز عبور raspberry)

مشکل: Grove Base Hat شناسایی نمی‌شود

علائم: حسگرها کار نمی‌کنند، خطاهای I2C

راه‌حل:

1. اطمینان حاصل کنید Base Hat به درستی روی همه پین‌های GPIO نشسته است
2. پین‌های خمیده روی پای یا Base Hat را بررسی کنید
3. رابط I2C را فعال کنید:

   sudo raspi-config nonint do_i2c 0
   sudo reboot
   

4. بررسی کنید I2C کار می‌کند: i2cdetect -y 1

مشکل: رسپبری پای کند کار می‌کند

علائم: رابط کاربری کند، پاسخ‌دهی آهسته

راه‌حل:

1. سرعت کارت SD را بررسی کنید (از کلاس ۱۰ یا بهتر استفاده کنید، یا SSD با USB)
2. فضای دیسک را آزاد کنید: با فرمان df -h بررسی کنید و فایل‌های غیر ضروری را حذف کنید
3. حافظه GPU را در raspi-config کاهش دهید اگر دوربین/نمایشگر به شدت استفاده نمی‌شود
4. برنامه‌های غیرضروری را ببندید
5. اگر از Pi 3 یا قدیمی‌تر استفاده می‌کنید، ارتقا به Pi 4 با رم بیشتر را در نظر بگیرید

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. بررسی اعتبارنامه WiFi: اطمینان حاصل کنید SSID و رمز عبور صحیح هستند
3. باند WiFi: Wio Terminal فقط از WiFi 2.4GHz پشتیبانی می‌کند (5GHz نه)
4. قدرت سیگنال: به روتر نزدیک‌تر شوید
5. تنظیمات روتر: برخی شبکه‌های Enterprise/WPA-Enterprise ممکن است کار نکنند

مشکل: Wio Terminal توسط رایانه شناخته نمی‌شود

علائم: دستگاه USB شناسایی نمی‌شود

راه‌حل:

1. کابل USB متفاوت امتحان کنید: از کابل داده استفاده کنید، کابل فقط شارژ را نخرید
2. وارد حالت بوتلودر شوید: کلید پاور را دو بار سریع به پایین بلغزانید
   • LED آبی باید پالس کند، دستگاه به عنوان "Arduino" در Device Manager ظاهر می‌شود
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. بررسی کنید پورت ۵۰۰۰ در استفاده نباشد:
   • ویندوز: netstat -ano | findstr :5000
   • مک‌اواس/لینوکس: lsof -i :5000
4. فرایندی که از پورت ۵۰۰۰ استفاده می‌کند را متوقف کنید یا پورت متفاوتی انتخاب کنید:

   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. SSID و رمز عبور را بررسی کنید: اعتبارنامه‌ها صحیح باشند
2. باند WiFi: اکثر دستگاه‌های IoT فقط از 2.4GHz پشتیبانی می‌کنند (5GHz نه)
3. تنظیمات روتر:
   • اگر ایزولاسیون AP فعال است آن را غیرفعال کنید
   • از امنیت WPA2-PSK استفاده کنید (از WPA3، WEP یا شبکه باز پرهیز کنید)
   • اطمینان حاصل کنید DHCP فعال است
4. شبکه‌های مخفی: اگر SSID مخفی است، ممکن است لازم باشد آن را به صراحت تنظیم کنید
5. قدرت سیگنال: دستگاه را به روتر نزدیک کنید
6. تداخل: سایر دستگاه‌ها، مایکروویو یا دیوارها می‌توانند مزاحمت ایجاد کنند

مشکل: اتصال WiFi مکرراً قطع می‌شود

علائم: اتصال ناپایدار

راه‌حل:

1. پایداری روتر را بررسی و در صورت نیاز ری‌استارت کنید
2. فرم‌ور دستگاه را به‌روزرسانی کنید
3. به جای DHCP از آی‌پی ثابت استفاده کنید
4. فاصله را به روتر کاهش دهید یا تقویت‌کننده WiFi اضافه کنید
5. برای تداخل از سایر دستگاه‌ها بررسی کنید
6. اطمینان حاصل کنید منبع تغذیه کافی است (خصوصاً برای رسپبری پای)

خدمات ابری

مشکل: نمی‌توان به Azure IoT Hub متصل شد

خطا: احراز هویت ناموفق، اتصال رد شده

راه‌حل:

1. اعتبارنامه‌ها را بررسی کنید:
   • رشته اتصال صحیح باشد
   • رشته اتصال فاقد فاصله اضافی یا شکست‌های خط باشد
2. ثبت دستگاه را بررسی کنید: دستگاه باید در IoT Hub ثبت شده باشد
3. فایروال/پراکسی: اطمینان حاصل کنید ترافیک خروجی MQTT (پورت ۸۸۸۳) یا HTTPS (پورت ۴۴۳) مجاز است
4. منطقه IoT Hub: اطمینان حاصل کنید IoT Hub در حال اجرا است و منطقه متفاوتی که باعث تاخیر شود نیست
5. محدودیت سهمیه: بررسی کنید محدودیت‌های سطح رایگان رعایت شده باشد
6. اتصال را تست کنید:

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

مشکل: Azure Functions فعال نمی‌شود

علائم: پیام‌ها ارسال شده‌اند اما تابع اجرا نمی‌شود

راه‌حل:

1. بررسی کنید اپلیکیشن Function در حال اجرا است (متوقف نشده)
2. رشته اتصال در تنظیمات Function App صحیح است
3. لاگ‌های تابع را در Azure Portal بررسی کنید
4. اطمینان حاصل کنید نقطه پایانی سازگار با Event Hub درست پیکربندی شده
5. بررسی کنید فرمت پیام مطابق انتظار تابع باشد
6. طرح سرویس Function App را بررسی کنید (مصرفی یا اختصاصی)

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: به جای 0 از QoS 1 یا 2 استفاده کنید
3. کاراکترهای جایگزین: اطمینان حاصل کنید کاراکترهای جایگزین موضوع به درستی استفاده شده‌اند (+ برای یک سطح، # برای چند سطح)
4. پیام‌های نگهداری شده: ناشر می‌تواند پرچم نگهداری را برای حفظ آخرین پیام تنظیم کند
5. زمان اتصال: اطمینان حاصل کنید مشترک قبل از انتشار پیام‌ها متصل شده است

---

مشکلات حسگر و عملگرها

حسگرهای Grove

مشکل: حسگر مقادیر نادرستی باز می‌گرداند

نشانه‌ها: مقدار خوانده شده 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 حداقل به 2 ثانیه فاصله بین خواندن‌ها نیاز دارند
4. بررسی تراکم: می‌تواند بر خواندن تأثیر بگذارد
5. کیفیت حسگر: دقت DHT11 از DHT22 کمتر است

دوربین

مشکل: دوربین در رزبری پای شناسایی نمی‌شود

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

راه‌حل:

1. فعالسازی رابط دوربین:

   sudo raspi-config
   

   به Interface Options → Camera → Enable بروید
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" → انتخاب محیط مجازی
2. راه‌اندازی مجدد VS Code پس از انتخاب مفسر
3. بررسی تنظیمات: درsettings.json اضافه کنید:

   "python.terminal.activateEnvironment": true
   

مشکل: کد روی دستگاه اجرا نمی‌شود

نشانه‌ها: کد اجرا می‌شود اما هیچ کاری روی دستگاه انجام نمی‌شود

راه‌حل:

1. اطمینان از ذخیره شدن کد (نشان نقطه روی تب فایل)
2. بررسی مفسر پایتون در حال اجرا: which python یا where python
3. برای Wio Terminal: اطمینان حاصل کنید کد از طریق PlatformIO آپلود شده است (روی دکمه آپلود کلیک کنید)
4. برای Raspberry Pi: از طریق SSH به Pi متصل شده و کد را آنجا اجرا کنید
5. بررسی پنجره خروجی برای خطاها

مشکل: IntelliSense توابع کتابخانه را نشان نمی‌دهد

نشانه‌ها: تکمیل خودکار برای ماژول‌های وارد شده وجود ندارد

راه‌حل:

1. اطمینان حاصل کنید کتابخانه در محیط فعال نصب شده است
2. پنجره VS Code را مجدداً بارگذاری کنید
3. بررسی کنید مفسر پایتون صحیح است
4. در صورت موجود بودن type stubs نصب کنید: pip install types-<نام کتابخانه>

محیط‌های مجازی پایتون

مشکل: نمی‌توان محیط مجازی ساخت

خطا: The virtual environment was not created successfully

راه‌حل:

1. نصب ماژول venv:
   • اوبونتو/دبیان: sudo apt install python3-venv
   • مک: معمولاً همراه با پایتون نصب است
   • ویندوز: پایتون را با همه اجزاء دوباره نصب کنید
2. بررسی نصب پایتون: مطمئن شوید پایتون به درستی نصب شده است
3. استفاده از مسیر کامل: سعی کنید با python3 -m venv .venv با فراخوانی صریح python3

مشکل: بسته‌ها در محل اشتباه نصب می‌شوند

نشانه‌ها: خطای ایمپورت پس از نصب بسته

راه‌حل:

1. اطمینان از فعال بودن محیط مجازی: پرامپت فرمان باید (.venv) را نشان دهد
2. بررسی موقعیت pip: which pip باید به .venv/bin/pip اشاره کند
3. از نو نصب در محیط مجازی: محیط مجازی را فعال کرده و سپس pip install <package>
4. از sudo با pip در محیط مجازی استفاده نکنید

مشکل: محیط مجازی قابل حمل نیست

نشانه‌ها: محیط مجازی پس از جابجایی یا روی کامپیوتر دیگر کار نمی‌کند

راه‌حل:

1. محیط‌های مجازی را جابه‌جا نکنید: حذف و در محل جدید دوباره بسازید
2. استفاده از requirements.txt:

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

3. دوباره ساختن محیط مجازی:

   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
   • مک: xcode-select --install
   • ویندوز: نصب Visual Studio Build Tools
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. بهینه‌سازی حلقه‌ها: از busy-waiting دوری کنید و sleep() یا توقف کوتاه استفاده کنید
3. مشکلات حافظه:
   • برنامه‌های غیرضروری را ببندید
   • فضای ذخیره‌سازی را آزاد کنید
   • با top یا htop روی Pi نظارت کنید
4. سرعت کارت SD: از کارت SD یا SSD سریع‌تر برای Raspberry Pi استفاده کنید
5. تاخیر شبکه: برای فراخوانی‌های شبکه از عملیات ناهمزمان استفاده کنید

مشکل: خطاهای کمبود حافظه

خطا: MemoryError یا قفل شدن سیستم

راه‌حل:

1. برای Raspberry Pi:
   • برنامه‌های غیرضروری را ببندید
   • فضای swap را افزایش دهید
   • از نسخه سبک‌تر سیستم عامل استفاده کنید (نسخه Lite)
   • رم را ارتقا دهید (Pi 4 دارای نسخه‌های 2/4/8 گیگابایت)
2. برای Wio Terminal:
   • اندازه بافرها را کاهش دهید
   • از تصاویر کوچکتر استفاده کنید
   • بهینه‌سازی استفاده از رشته‌ها
   • نشت حافظه را بررسی کنید (حافظه آزاد نشده)

مشکل: از دست رفتن یا خرابی داده‌ها

نشانه‌ها: پیام‌های گم شده، فایل‌های خراب

راه‌حل:

1. مشکلات کارت SD:
   • از کارت‌های SD با کیفیت استفاده کنید (از کارت بی‌کیفیت یا تقلبی خودداری کنید)
   • پشتیبان‌گیری منظم
   • خاموش کردن صحیح (کابل برق را ناگهانی قطع نکنید)
2. سرریز بافر: اندازه بافرها را در کد افزایش دهید
3. قابلیت اطمینان شبکه: منطق تلاش مجدد و مدیریت خطا را پیاده‌سازی کنید
4. کیفیت سرویس: از MQTT QoS 1 یا 2 برای پیام‌های مهم استفاده کنید

---

پیام‌های خطای رایج

ModuleNotFoundError: No module named 'X'

علت: بسته نصب نشده یا محیط مجازی فعال نشده

راه‌حل:

pip install X

ابتدا اطمینان حاصل کنید محیط مجازی فعال است.

Permission denied در لینوکس/مک

علت: نیاز به مجوزهای ارتقا یافته یا مشکل مجوز فایل

راه‌حل:

• برای عملیات سیستم: از sudo استفاده کنید
• برای pip: با venv از sudo استفاده نکنید، ابتدا 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. از تورفتگی یکنواخت استفاده کنید (چهار فاصله استاندارد پایتون است)
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 برای قطعات Grove

2. جستجو برای مشکلات مشابه

• مسائل GitHub: جستجوی مسائل موجود
• Stack Overflow: جستجو برای پیام‌های خطا
• انجمن‌های دستگاه: انجمن‌های Raspberry Pi یا Arduino را بررسی کنید

3. ایجاد Issue در GitHub

اگر نتوانستید راه حل پیدا کنید:

1. به مسائل GitHub بروید
2. روی "New Issue" کلیک کنید
3. موارد زیر را ارائه دهید:
   • توضیح واضح مشکل
   • مراحل بازتولید
   • پیام‌های خطا (متن کامل)
   • نسخه سخت‌افزار/نرم‌افزار
   • اقداماتی که انجام داده‌اید
   • اسکرین‌شات در صورت نیاز

4. به جامعه بپیوندید

• دیسکورد: Microsoft Foundry Discord
• Microsoft Learn: Microsoft Learn IoT

5. گزارش مشکل خوب ارائه دهید

یک گزارش مشکل خوب شامل:

• محیط: سیستم عامل، نسخه پایتون، سخت‌افزار استفاده شده
• مراحل بازتولید: مراحل دقیق وقوع مشکل
• رفتار مورد انتظار: آنچه باید اتفاق بیفتد
• رفتار واقعی: آنچه واقعاً اتفاق می‌افتد
• پیام‌های خطا: متن کامل خطا، نه اسکرین‌شات
• کد: مثال حداقلی کد که مشکل را بازتولید می‌کند

---

نکات پیشگیری

بهترین شیوه‌های کلی

1. پشتیبان‌گیری منظم: نسخه‌های پشتیبان منظم از کارت‌های SD / کدهای کاری
2. مستندسازی تغییرات: یادداشت کردن آنچه کار می‌کند در کامنت‌ها
3. کنترل نسخه: استفاده از گیت برای دنبال کردن تغییرات کد
4. آزمایش تدریجی: تست تغییرات کوچک قبل از ترکیب آنها
5. خواندن پیام‌های خطا: معمولاً دقیقاً می‌گویند چه مشکلی وجود دارد
6. به‌روزرسانی منظم: نگه داشتن نرم‌افزار / فرم‌ویر به‌روز
7. استفاده از قطعات با کیفیت: اجتناب از کابل‌ها / منابع تغذیه ارزان
8. برق پایدار: استفاده از منبع تغذیه مناسب (مخصوصاً برای پای)

روند توسعه

1. شروع ساده: از کد نمونه‌ای که کار می‌کند شروع کنید
2. یک تغییر در هر بار: آسان‌تر است که بفهمید چه چیزی خراب شده
3. آزمایش مکرر: مشکلات را زودتر پیدا کنید
4. مرتب نگه داشتن: فایل‌ها و کد را منطقی سازماندهی کنید
5. کد را کامنت‌گذاری کنید: نسخه آینده‌ی خودتان از این کار قدردانی خواهد کرد

---

این راهنمای عیب‌یابی توسط جامعه نگهداری می‌شود. اگر راه‌حلی برای مشکلی یافتید که در اینجا نیامده است، لطفاً در contributing مشارکت کنید تا به دیگران کمک نمایید!

---

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است دارای خطا یا عدم دقت باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، توصیه می‌شود ترجمه حرفه‌ای انسانی انجام گیرد. ما مسئول هیچ گونه سوءتفاهم یا برداشت نادرستی که از استفاده این ترجمه ناشی شود نیستیم.