# راهنمای عیب‌یابی این راهنما به شما کمک می‌کند تا مشکلات رایج هنگام کار با برنامه درسی اینترنت اشیاء برای مبتدیان را حل کنید. مشکلات بر اساس دسته‌بندی برای پیمایش آسان سازماندهی شده‌اند. ## فهرست مطالب - [مشکلات نصب](../..) - [نصب پایتون](../..) - [VS Code و افزونه‌ها](../..) - [PlatformIO (Wio Terminal)](../..) - [کتابخانه‌های Grove](../..) - [مشکلات سخت‌افزاری](../..) - [رسپبری پای](../..) - [Wio Terminal](../..) - [دستگاه مجازی (CounterFit)](../..) - [مشکلات اتصال](../..) - [اتصال WiFi](../..) - [خدمات ابری](../..) - [MQTT](../..) - [مشکلات حسگر و عملگر](../..) - [حسگرهای Grove](../..) - [دوربین](../..) - [میکروفون و بلندگو](../..) - [مشکلات محیط توسعه](../..) - [VS Code](../..) - [محیط‌های مجازی پایتون](../..) - [وابستگی‌ها](../..) - [مشکلات عملکرد](../..) - [پیام‌های خطای رایج](../..) - [دریافت کمک](../..) --- ## مشکلات نصب ### نصب پایتون #### مشکل: نسخه پایتون خیلی قدیمی است **خطا:** `Python 3.6 or higher is required` **راه‌حل:** 1. آخرین نسخه پایتون ۳ را از [python.org](https://www.python.org/downloads/) دانلود کنید 2. هنگام نصب روی ویندوز، گزینه "Add Python to PATH" را انتخاب کنید 3. نصب را تأیید کنید: ```bash 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` پیکربندی برد صحیحی دارد: ```ini [env:seeed_wio_terminal] platform = atmelsam board = seeed_wio_terminal framework = arduino ``` ### کتابخانه‌های Grove #### مشکل: ایمپورت کتابخانه Grove در رسپبری پای خطا می‌دهد **خطا:** `ModuleNotFoundError: No module named 'grove'` **راه‌حل:** 1. کتابخانه‌های Grove را مجدداً نصب کنید: ```bash 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 را فعال کنید: ```bash 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](https://wiki.seeedstudio.com/Wio-Terminal-Getting-Started/) به‌روزرسانی کنید 3. کد مقداردهی اولیه نمایشگر را اضافه کنید: ```cpp #include TFT_eSPI tft; tft.begin(); tft.fillScreen(TFT_BLACK); ``` 4. نمونه اسکیچ از PlatformIO آپلود کنید تا سخت‌افزار تست شود #### مشکل: WiFi در Wio Terminal کار نمی‌کند **علائم:** نمی‌تواند به WiFi متصل شود، خطاهای شبکه **راه‌حل:** 1. **آپدیت فرم‌ور WiFi:** راهنمای [به‌روزرسانی فرم‌ور WiFi Wio Terminal](https://wiki.seeedstudio.com/Wio-Terminal-Network-Overview/) را دنبال کنید 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 را از [اینجا](https://wiki.seeedstudio.com/Driver_for_Seeeduino/) دانلود و نصب کنید 4. **استفاده از پورت USB دیگر:** از هاب USB استفاده نکنید، اتصال مستقیم داشته باشید 5. **درایورهای USB سیستم را به‌روزرسانی کنید** #### مشکل: حسگرها در Wio Terminal کار نمی‌کنند **علائم:** حسگرهای Grove داده‌ای نمی‌خوانند **راه‌حل:** 1. اتصالات کابل Grove را بررسی کنید 2. اطمینان حاصل کنید از پورت Grove صحیح (چپ یا راست) استفاده می‌کنید 3. کتابخانه‌های صحیح حسگر را وارد کنید 4. نیازمندی‌های تغذیه حسگر را بررسی کنید 5. حسگر را با کد نمونه از کتابخانه آزمایش کنید ### دستگاه مجازی (CounterFit) #### مشکل: اپلیکیشن CounterFit اجرا نمی‌شود **خطا:** خطاهای مختلف پایتون هنگام اجرای CounterFit **راه‌حل:** 1. اطمینان حاصل کنید محیط مجازی فعال است 2. CounterFit را نصب یا مجدداً نصب کنید: ```bash pip install CounterFit ``` 3. بررسی کنید پورت ۵۰۰۰ در استفاده نباشد: - ویندوز: `netstat -ano | findstr :5000` - مک‌اواس/لینوکس: `lsof -i :5000` 4. فرایندی که از پورت ۵۰۰۰ استفاده می‌کند را متوقف کنید یا پورت متفاوتی انتخاب کنید: ```bash 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. **اتصال را تست کنید:** ```bash 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. **فعالسازی رابط دوربین:** ```bash sudo raspi-config ``` به Interface Options → Camera → Enable بروید 2. **بررسی کابل روبان:** اطمینان حاصل کنید کابل دوربین به درستی وارد شده است - سمت آبی روبان به سمت پورت‌های USB روی Pi Zero باشد - سمت آبی روبان به دور از پورت‌های USB روی Pi 4 باشد 3. **به‌روزرسانی فریم‌ور:** ```bash sudo apt update sudo apt full-upgrade sudo reboot ``` 4. **تست دوربین:** ```bash raspistill -o test.jpg ``` #### مشکل: کیفیت تصاویر دوربین پایین است **نشانه‌ها:** تصاویر تار، تاریک یا کم‌رنگ هستند **راه‌حل:** 1. **کانون:** فیلم محافظ لنز را بردارید، در صورت امکان کانون را تنظیم کنید 2. **نورپردازی:** اطمینان حاصل کنید نور کافی وجود دارد 3. **تنظیمات دوربین:** در کد مقدار اکسپوژر، ISO، تعادل سفید را تنظیم کنید 4. **ثبات:** دوربین را ثابت نگه دارید، در صورت نیاز از سه‌پایه استفاده کنید 5. **رزولوشن:** رزولوشن بیش از حد دوربین استفاده نکنید ### میکروفون و بلندگو #### مشکل: ورودی/خروجی صدا ندارد **نشانه‌ها:** میکروفون ضبط نمی‌کند، بلندگو صدا پخش نمی‌کند **راه‌حل:** 1. **بررسی اتصالات:** اطمینان حاصل کنید دستگاه‌های صوتی به درستی متصل باشند 2. **آزمایش سخت‌افزار:** - بلندگو: `speaker-test -t wav -c 2` - میکروفون: `arecord -l` برای فهرست، `arecord test.wav` برای ضبط 3. **تنظیمات صدا:** حجم صدا را بررسی و تنظیم کنید: ```bash alsamixer ``` 4. **انتخاب دستگاه صوتی:** دستگاه صوتی صحیح را در کد مشخص کنید 5. **مشکلات درایور:** ALSA را به‌روزرسانی کنید یا درایورهای صوتی را دوباره نصب کنید #### مشکل: برد ReSpeaker کار نمی‌کند **نشانه‌ها:** دستگاه صوتی شناسایی نمی‌شود **راه‌حل:** 1. **نصب درایورها:** ```bash 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` اضافه کنید: ```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 ` 4. **از sudo با pip در محیط مجازی استفاده نکنید** #### مشکل: محیط مجازی قابل حمل نیست **نشانه‌ها:** محیط مجازی پس از جابجایی یا روی کامپیوتر دیگر کار نمی‌کند **راه‌حل:** 1. **محیط‌های مجازی را جابه‌جا نکنید:** حذف و در محل جدید دوباره بسازید 2. **استفاده از requirements.txt:** ```bash pip freeze > requirements.txt pip install -r requirements.txt ``` 3. **دوباره ساختن محیط مجازی:** ```bash python3 -m venv .venv source .venv/bin/activate # یا activate.bat در ویندوز pip install -r requirements.txt ``` ### وابستگی‌ها #### مشکل: نصب پکیج‌ها شکست می‌خورد **خطا:** خطاهای مختلف pip هنگام نصب **راه‌حل:** 1. **بروزرسانی pip:** ```bash 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/ ` 5. **نصب نسخه مشخص:** `pip install ==` #### مشکل: تعارض وابستگی‌ها **خطا:** `ERROR: pip's dependency resolver does not currently take into account all the packages that are installed` **راه‌حل:** 1. **استفاده از محیط مجازی تازه** برای هر پروژه 2. **بروزرسانی بسته‌ها:** `pip install --upgrade ` 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'` **علت:** بسته نصب نشده یا محیط مجازی فعال نشده **راه‌حل:** ```bash 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 :` یا `netstat -ano | findstr :` 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` **علت:** مشکلات کدگذاری کاراکتر **راه‌حل:** ```python # هنگام خواندن فایل‌ها 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](README.md) و دستورالعمل‌های درس را مرور کنید - **راهنمای سخت‌افزار:** فایل [hardware.md](hardware.md) برای اطلاعات خاص سخت‌افزار را بررسی کنید - **ویکی Seeed Studio:** [Seeed Studio Wiki](https://wiki.seeedstudio.com/) برای قطعات Grove ### 2. جستجو برای مشکلات مشابه - **مسائل GitHub:** جستجوی [مسائل موجود](https://github.com/microsoft/IoT-For-Beginners/issues) - **Stack Overflow:** جستجو برای پیام‌های خطا - **انجمن‌های دستگاه:** انجمن‌های Raspberry Pi یا Arduino را بررسی کنید ### 3. ایجاد Issue در GitHub اگر نتوانستید راه حل پیدا کنید: 1. به [مسائل GitHub](https://github.com/microsoft/IoT-For-Beginners/issues) بروید 2. روی "New Issue" کلیک کنید 3. موارد زیر را ارائه دهید: - توضیح واضح مشکل - مراحل بازتولید - پیام‌های خطا (متن کامل) - نسخه سخت‌افزار/نرم‌افزار - اقداماتی که انجام داده‌اید - اسکرین‌شات در صورت نیاز ### 4. به جامعه بپیوندید - **دیسکورد:** [Microsoft Foundry Discord](https://discord.gg/nTYy5BXMWG) - **Microsoft Learn:** [Microsoft Learn IoT](https://docs.microsoft.com/learn/browse/?products=azure-iot) ### 5. گزارش مشکل خوب ارائه دهید یک گزارش مشکل خوب شامل: - **محیط:** سیستم عامل، نسخه پایتون، سخت‌افزار استفاده شده - **مراحل بازتولید:** مراحل دقیق وقوع مشکل - **رفتار مورد انتظار:** آنچه باید اتفاق بیفتد - **رفتار واقعی:** آنچه واقعاً اتفاق می‌افتد - **پیام‌های خطا:** متن کامل خطا، نه اسکرین‌شات - **کد:** مثال حداقلی کد که مشکل را بازتولید می‌کند --- ## نکات پیشگیری ### بهترین شیوه‌های کلی 1. **پشتیبان‌گیری منظم:** نسخه‌های پشتیبان منظم از کارت‌های SD / کدهای کاری 2. **مستندسازی تغییرات:** یادداشت کردن آنچه کار می‌کند در کامنت‌ها 3. **کنترل نسخه:** استفاده از گیت برای دنبال کردن تغییرات کد 4. **آزمایش تدریجی:** تست تغییرات کوچک قبل از ترکیب آنها 5. **خواندن پیام‌های خطا:** معمولاً دقیقاً می‌گویند چه مشکلی وجود دارد 6. **به‌روزرسانی منظم:** نگه داشتن نرم‌افزار / فرم‌ویر به‌روز 7. **استفاده از قطعات با کیفیت:** اجتناب از کابل‌ها / منابع تغذیه ارزان 8. **برق پایدار:** استفاده از منبع تغذیه مناسب (مخصوصاً برای پای) ### روند توسعه 1. **شروع ساده:** از کد نمونه‌ای که کار می‌کند شروع کنید 2. **یک تغییر در هر بار:** آسان‌تر است که بفهمید چه چیزی خراب شده 3. **آزمایش مکرر:** مشکلات را زودتر پیدا کنید 4. **مرتب نگه داشتن:** فایل‌ها و کد را منطقی سازماندهی کنید 5. **کد را کامنت‌گذاری کنید:** نسخه آینده‌ی خودتان از این کار قدردانی خواهد کرد --- *این راهنمای عیب‌یابی توسط جامعه نگهداری می‌شود. اگر راه‌حلی برای مشکلی یافتید که در اینجا نیامده است، لطفاً در [contributing](CONTRIBUTING.md) مشارکت کنید تا به دیگران کمک نمایید!* --- **سلب مسئولیت**: این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است دارای خطا یا عدم دقت باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، توصیه می‌شود ترجمه حرفه‌ای انسانی انجام گیرد. ما مسئول هیچ گونه سوءتفاهم یا برداشت نادرستی که از استفاده این ترجمه ناشی شود نیستیم.