استكشاف الأخطاء وإصلاحها
اعمل انطلاقاً من الأعراض. تظهر أداتان تشخيصيتان في أنحاء هذه الصفحة، فتعلّمهما أولاً: تقرير الإقلاع والمنفذ التسلسلي.
تقرير الإقلاع
عند كل إقلاع، تسرد شاشة البداية الملحقات التي فشلت في التهيئة، وتُعاد القائمة نفسها عبر GET /api/system. يذكر كل مدخل المكوّن والخطأ:
| المدخل | السبب المرجح | الفحص |
|---|---|---|
SD (ESP_ERR_TIMEOUT) | بطاقة مفقودة، أو توصيلات خاطئة، أو لا مقاومة رفع على CS | هل البطاقة مُثبتة؟ مقاومة رفع 10 كيلو أوم على GPIO5؟ تبادل MISO/MOSI؟ |
NFC (ESP_ERR_TIMEOUT) | PN532 لا يستجيب على I2C | هل مفاتيح DIP على I2C؟ تبادل SDA/SCL؟ هل مقاومة الرفع موجودة؟ |
Audio (...) | دبابيس I2S أو طاقة المضخم | ترتيب BCLK/LRC/DIN، وVIN الخاص بالمضخم |
الملحق الفاشل يعطل ميزته لكن لا يعطل غيرها: الجهاز مصمم ليواصل الإقلاع.
المنفذ التسلسلي
وصّل USB-C وافتح طرفية تسلسلية بسرعة 115200 باود (الجهاز /dev/ttyACM0 على Linux، ومنفذ COM على Windows؛ لا حاجة إلى تعريفات على الأنظمة الحديثة). يروي البرنامج الثابت كل شيء: الإقلاع، ومحاولات WiFi مع أسباب الفشل، ومسوحات الشبكة، والتشغيل، والأخطاء. كل لغز تقريباً ينتهي هنا.
# Linux example
screen /dev/ttyACM0 115200
WiFi
| العرَض | السبب | الإصلاح |
|---|---|---|
يعرض المنفذ التسلسلي Target SSID '...' not visible on 2.4 GHz | الشبكة 5 غيغاهرتز فقط | لا يملك ESP32-S3 راديو 5 غيغاهرتز. فعّل 2.4 غيغاهرتز على الموجّه أو نقطة الاتصال ("توافق أقصى" على نقاط اتصال iPhone) |
إعادة محاولة مع reason=15 أو reason=204 | كلمة مرور خاطئة | أعد التزويد؛ انظر أول إقلاع وWiFi |
إعادة محاولة مع reason=201 | الشبكة غير موجودة | خطأ مطبعي في SSID، أو الشبكة خارج المدى |
إعادة محاولة مع reason=2 على شبكات متعددة | إطارات المصادقة لا يُرد عليها؛ غالباً طاقة هامشية تصل الراديو | استخدم كابل أو مصدر تغذية USB أفضل. كما ينزل البرنامج الثابت قدرة الإرسال تلقائياً عبر الدرجات لإنقاذ هذه الحالة |
| يتصل، ثم يتعذر الوصول إلى لوحة التحكم | عزل العملاء على الموجّه أو شبكة ضيف | اسمح بحركة LAN بين العملاء، أو استخدم الشبكة الرئيسية |
تبقى الساعة --:-- مع أن WiFi يعمل | الشبكة تحجب NTP (UDP 123) | اسمح بـNTP الصادر على الجدار الناري أو اضبط خادم SNTP يمكن الوصول إليه في بناء البرنامج الثابت |
الصوت
| العرَض | السبب | الإصلاح |
|---|---|---|
| لا صوت إطلاقاً، لكن لوحة التحكم تعرض تشغيلاً | السماعة موصولة خطأ، أو LRC/SD غير موصولين، أو المضخم بلا طاقة | مخرج المضخم جسر مربوط: مرر السماعة عبر طرفي + و-، لا إلى الأرضي أبداً. ثم تحقق من LRC (GPIO39)، ومن أن SD (GPIO41) موصول، وVIN. قائمة الفحص الكاملة في توصيلات الصوت |
| تشويه عند مستوى صوت مرتفع | هبوط التغذية أو سماعة أصغر من اللازم | غذِّ المضخم بـ5 فولت، واستخدم سماعة 3 واط أو أكبر |
| يتقطع الراديو، ويرتفع عداد نفاد المخزن | الشبكة لا تحافظ على البث | اقترب من الموجّه؛ فضّل محطات 64 إلى 128 كيلوبت/ثانية |
| ملف معين لا يعمل | حاوية غير مدعومة (m4a) أو ملف تالف | أعد الترميز إلى MP3؛ وجرب الملف على حاسوب |
بطاقة SD
| العرَض | السبب | الإصلاح |
|---|---|---|
| يظهر تقرير الإقلاع مهلة SD | انظر صف التوصيلات في تقرير الإقلاع | |
| تُركب البطاقة لكن المكتبة فارغة | البنية لا تطابق قواعد الماسح | انظر مكتبة SD؛ وشغّل tools/prepare_sd_card_data.sh --check |
| بطاقة exFAT | غير مدعومة | أعد التهيئة بـFAT32 |
لوحة التحكم
| العرَض | السبب | الإصلاح |
|---|---|---|
| يحذر المتصفح من الشهادة | متوقع، شهادة موقعة ذاتياً | اقبلها مرة واحدة؛ الاتصال يبقى مشفراً |
| كل إجراء يعود بـ"unauthorized" | رمز API مفقود أو خاطئ | أدخل الرمز في المطالبة التي تعرضها لوحة التحكم (أو الإعدادات، الوصول). كيفية قراءته من المنفذ التسلسلي |
| تعود مطالبة الرمز للظهور مع نقطة حالة حمراء | تغير رمز الجهاز (إعادة ضبط مصنع، إعادة وميض، إعادة تزويد) | الصق الرمز الحالي في المطالبة؛ واقرأه عبر USB بطرق استعادة رمز API |
| تُحمَّل الصفحات لكن لا يتحدث شيء حياً | WebSocket محجوب | تحجب بعض الشبكات المؤسسية ترقيات WebSocket؛ جرب شبكة أخرى |
| لوحة التحكم بطيئة أثناء تشغيل الصوت | طبيعي عند أول مصافحة TLS في الجلسة | الطلبات التالية سريعة؛ أبقِ التبويب مفتوحاً |
| تعرض شاشة الخمول تلميحاً خافتاً "اضبط الموقع من الإعدادات" | أوقات الصلاة بلا موقع مضبوط | اضبط الموقع في لوحة الصلاة بإعدادات لوحة التحكم (أو POST /api/prayer/config)؛ يختفي التلميح ما إن يُضبط |
NFC
| العرَض | السبب | الإصلاح |
|---|---|---|
| لا استجابة لأي بطاقة | PN532 فشل عند الإقلاع | راجع تقرير الإقلاع ومفاتيح DIP |
| بطاقة معينة تُتجاهل | غير مسجلة | سجلها من صفحة NFC في لوحة التحكم |
| مدى قراءة قصير | حافظة سميكة جداً أو معدن قريب | أبقِ منطقة القارئ خالية من البطارية والمعدن، انظر الحافظة |
البطارية
| العرَض | السبب | الإصلاح |
|---|---|---|
| نسبة البطارية عالقة عند 0 مع تغذية USB فقط | لا جهد استشعار للبطارية؛ تعطل المراقبة نفسها عند قراءات غير معقولة | متوقع على منضدة عمل من دون مقسم جهد البطارية |
| يُطفأ الجهاز ولا يبقى شغالاً | إقفال بطارية فارغة فعلاً | اشحنها؛ واضغط المقبض للاستيقاظ بعد السكون العميق |
| لا يعرض الشحن أبداً | دبوس CHRG غير موصول أو لا مقاومة رفع | توصيلات GPIO17 |
استعادة رمز API
الرمز المفقود لا يتطلب إعادة ضبط أبداً؛ يستطيع الجهاز طباعة رمزه الحالي عند الطلب:
- وصّل USB وافتح المنفذ التسلسلي، واكتب
tokenواضغط Enter. يطبع الجهاز الرمز الحالي. - من دون حاسوب: أثناء ظهور شاشة حالة WiFi، اضغط مع الاستمرار زر المقبض نحو 1.5 ثانية. يظهر الرمز لمدة 5 ثوانٍ ثم يختفي.
إعادة ضبط المصنع (أدناه) هي الطريق عندما تريد إحالة الرمز القديم للتقاعد وصك رمز جديد.
إعادة ضبط المصنع
تمسح إعادة ضبط المصنع كل الحالة (لا صوتيات SD) وتطبع رمز API جديداً على المنفذ التسلسلي عند الإقلاع التالي. لا زر إعادة ضبط في لوحة التحكم: أرسل POST /api/reset مع الرمز، أو امسح قسم nvs عبر المنفذ التسلسلي (parttool.py -p PORT erase_partition --partition-name=nvs). إنها طريق الضبط لرمز مفقود أو إعداد معطل.
ما زلت عالقاً؟
التقط سجل المنفذ التسلسلي لإقلاع كامل إضافة إلى الإجراء الفاشل وافتح مشكلة على GitHub معه. يكاد السجل يحتوي الجواب دائماً.