لوحة التحكم عبر الويب

يقدم صافي لوحة تحكمه الخاصة عبر HTTPS. لا حاجة إلى تثبيت أي شيء: أي متصفح على الشبكة نفسها يعمل، هاتفاً كان أو حاسوب مكتبي. تحمل اللوحة الهوية الزمردية والذهبية نفسها التي يحملها هذا الموقع، وتتبع تفضيل نظامك للوضع الفاتح أو الداكن (مع مفتاح يدوي)، وهي ثنائية اللغة بالكامل: زر اللغة في الترويسة يبدّل بين الإنجليزية والعربية مع تخطيط صحيح من اليمين إلى اليسار.

الاتصال

1. تصفح https://safi.local. يعلن الجهاز عن نفسه عبر mDNS، لذا يعمل الاسم مباشرة في معظم الشبكات المنزلية. إذا حجبت شبكتك mDNS، اقرأ عنوان IP من شاشة WiFi في الجهاز (أو من قائمة عملاء موجّهك) وتصفح https://<ip> بدلاً من ذلك.
2. اقبل تحذير الشهادة. يولّد الجهاز شهادة موقعة ذاتياً، لذا لا يستطيع المتصفح معرفتها مسبقاً. هذا متوقع للأجهزة المحلية؛ ويبقى الاتصال مشفراً. تثبيت شهادة يثق بها متصفحك ممكن ومغطى في فصل HTTPS للمطورين.

يمكنك أيضاً تثبيت لوحة التحكم كتطبيق: توفر المتصفحات خيار "إضافة إلى الشاشة الرئيسية" لها، وهو ما يمنحك رمزاً بملء الشاشة على الهاتف.

رمز API

تحتاج لوحة التحكم إلى رمز قبل أن تتحكم بالجهاز. قراءة المعلومات (ما الذي يعمل، مستوى البطارية، المكتبة) مفتوحة، لكن كل إجراء يغيّر شيئاً (تشغيل محطة، ضبط مستوى الصوت، تعديل الإعدادات، بدء تحديث) يتطلب رمز API الخاص بالجهاز. من دونه تعود تلك الإجراءات بـRequest failed: unauthorized.

لا حاجة لأن تبحث عن مكان إدخاله. في المرة الأولى التي تفتح فيها لوحة التحكم، تظهر مطالبة تسأل عن الرمز، ولا تعود للظهور تلقائياً إلا عندما يُرفض الرمز المخزن برد تغيّر الرمز الموصوف أدناه. الصق الرمز هناك واضغط Save and connect. يُخزن في متصفحك ويُرفق بكل طلب بعد ذلك، فلا تفعل هذا إلا مرة واحدة لكل متصفح. يمكنك أيضاً عرضه أو تغييره لاحقاً تحت الإعدادات، الوصول.

إذا تغير رمز الجهاز يوماً (بعد إعادة ضبط مصنع، أو إعادة وميض، أو إعادة تزويد)، تُرفض كل الإجراءات المحمية برسالة الجهاز "Invalid or expired token". تتعرف لوحة التحكم على ذلك الرد تحديداً، وتفتح المطالبة من جديد مع إشعار بتغير الرمز وتلوّن نقطة حالة الاتصال بالأحمر؛ الصق الرمز الحالي واضغط Save and connect. كما تزيل لوحة التحكم أي ?token= من شريط العنوان عند التحميل ولا تكتب الرمز في الرابط أبداً، فيبقى الرمز خارج سجل المتصفح.

كيف تحصل على الرمز

ينشئ الجهاز رمزاً عشوائياً عند أول إقلاع له على الإطلاق ويطبعه مرة واحدة على منفذه التسلسلي عبر USB. لقراءته:

1. وصّل الجهاز بحاسوبك بكابل USB (منفذ COM).
2. افتح شاشة تسلسلية على ذلك المنفذ بسرعة 115200 باود. أي طرفية تسلسلية تعمل: idf.py -p PORT monitor إذا كنت تكتب الفلاش مع ESP-IDF، أو شاشة Arduino IDE التسلسلية، أو PuTTY، أو screen، أو minicom.
3. أعد تشغيل الجهاز (زر إعادة التشغيل، أو افصل الوصلة وأعد توصيلها) وراقب الأسطر الأولى التي يطبعها. عند أول إقلاع سترى كتلة مثل هذه:

W (612) API_AUTH: ============================================
W (613) API_AUTH: NEW API TOKEN GENERATED (save this!):
W (613) API_AUTH: 3f121aae376ab54849b6bb22c0f8df30d571597a3852b630edde96f19fa8f12f
W (614) API_AUTH: ============================================

السطر الطويل بين الفاصلين هو رمزك: 64 محرفاً سداسياً عشرياً. انسخه والصقه في مطالبة لوحة التحكم.

يمكن قراءة الرمز عند الطلب، في أي وقت، لا عند أول إقلاع فقط. افتح طرفية تسلسلية على منفذ وحدة الجهاز واكتب token ثم Enter: يطبع الجهاز الرمز الحالي.

يمكنك أيضاً قراءة الرمز من الجهاز نفسه. أثناء ظهور شاشة حالة WiFi، اضغط مع الاستمرار على زر المقبض لنحو 1.5 ثانية؛ يظهر الرمز على الشاشة لمدة 5 ثوانٍ ثم يختفي. تعود الشاشة إلى ساعة الخمول من تلقاء نفسها بعد 10 ثوانٍ، لذا ابدأ الضغط المطول وهي ما تزال معروضة.

يُطبع الرمز فقط عند إنشائه لأول مرة

في كل إقلاع لاحق يسجل الجهاز فقط API token loaded from NVS ولا يعيد طباعة الرمز، عمداً، حتى لا يسافر الرمز إلى مكان يمكن التقاطه منه. استعادة رمز مفقود لا تتطلب إعادة ضبط أبداً: أمر الوحدة token يطبع الرمز الحالي عند الطلب، وكشف الشاشة بالضغط المطول يعرضه أثناء ظهور شاشة حالة WiFi. أما إذا أردت رمزاً جديداً كلياً، فامسح إعدادات الجهاز المخزنة ليتولد رمز جديد عند الإقلاع التالي: parttool.py -p PORT erase_partition --partition-name=nvs، ثم أعد تشغيل الجهاز واقرأ الرمز الجديد كما سبق. يمسح هذا أيضاً بيانات اعتماد WiFi المحفوظة، لذا ستعيد تزويد WiFi. المنطق وراء عدم كشف الرمز عبر الشبكة إطلاقاً في أمن REST.

الصفحات الثماني

الرئيسية

أزرار التشغيل، شريط التقدم، منزلق مستوى الصوت، والحالة الحية: ما الذي يعمل، الوقت المنقضي، وعنوان البث في الراديو. تعرض لوحة الجهاز البطارية، الذاكرة الحرة، مدة التشغيل، رقم إصدار البرنامج الثابت، عداد نفاد المخزن الصوتي (يجب أن يبقى صفراً على شبكة سليمة)، وحرارة RTC عند تركيب وحدة الساعة. تصل التحديثات عبر WebSocket، لذا تبقى عدة متصفحات مفتوحة متزامنة مع الجهاز وفيما بينها.

المكتبة

محتوى بطاقة SD الممسوح: القراء في جانب، وملفاتهم في الجانب الآخر. الملفات المسماة بأرقام السور تعرض أسماء السور الصحيحة، عربية ونقحرة، بدلاً من أسماء الملفات الخام. اضغط أي صف للتشغيل.

المفضلة

كل ما حفظته، مع عدد مرات التشغيل. النموذج في الجانب يضيف مفضلة بالسورة أو البث أو مسار الملف، مع منتقي سور حقيقي.

الراديو

محطات قرآن جاهزة إضافة إلى بثوثك المحفوظة. الصيغ المدعومة هي MP3 وAAC وHE-AAC عبر HTTP أو HTTPS. تأتي اللوحة بعدد من المحطات المدمجة؛ أما البثوث المخصصة التي تضيفها فتُحفظ على الجهاز، فيرى كل متصفح وبطاقة NFC القائمة نفسها.

البطاقات (NFC)

تسجيل البطاقات وإدارتها، موصوفة بالكامل في بطاقات NFC. حقل السورة منتقٍ يحوي أسماء السور الـ114 كلها.

المجدول

قواعد التشغيل المرتبطة بالوقت، موصوفة في المفضلة والمجدول.

الإعدادات

مستوى الصوت، سطوع الشاشة، المنطقة الزمنية (من قائمة جاهزة أو قاعدة POSIX مخصصة)، تنسيق الساعة 12 أو 24 ساعة، ساعة الجهاز (المصدر، وخيار "استخدم وقت المتصفح" بلمسة واحدة للتثبيتات غير المتصلة)، الاستئناف التلقائي، سياسة إزالة بطاقة NFC، بيانات اعتماد WiFi، حقل رمز API، وزر سكون يُدخل الجهاز في السكون العميق حتى يُضغط الزر أو يحين الجدول التالي. كل إعداد موثق في الإعدادات.

التحديث (OTA)

تحديثات البرنامج الثابت برفع ملف أو بالسحب عبر رابط، مع تقدم حي. انظر التحديث.

التحديثات الحية

تستمع لوحة التحكم عبر WebSocket لدفعات من الجهاز: حالة التشغيل، مستوى الصوت، البطارية، تغيرات WiFi، لمسات NFC، عناوين البث، تحذيرات التخزين المؤقت، وتقدم التحديث. يعرض المؤشر في الترويسة حالة الاتصال مع نقطة ملونة: ذهبية أثناء الاتصال، خضراء عندما يُصادق المقبس، وحمراء عندما يكون غير مصرح (لم يعد الرمز مطابقاً) أو مغلقاً. لا يعيد المقبس غير المصرح الاتصال من تلقاء نفسه حتى يُحفظ رمز صالح؛ أما غير ذلك، فإذا انقطع الاتصال تعيد الصفحة الاتصال تلقائياً مع تراجع تدريجي، كما أن التحديث اليدوي يعيد مزامنة كل شيء دائماً. تظهر إخفاقات أي إجراء كإشعار منبثق في الزاوية بدلاً من الاختفاء بصمت.

عدة مشاهدين

يمكن فتح أي عدد من المتصفحات في وقت واحد. تغييرات الحالة التي تحدث في أي مكان (بما في ذلك على الجهاز نفسه، كإدارة مقبض مستوى الصوت مثلاً) تنتشر إلى جميعها في أقل من ثانية.