Meshyface

Meshyface هي لوحة تحكم لـ Meshtastic تعتمد على المحادثة أولاً، وتعمل كخدمة Python واحدة وتقدّم واجهة ويب من صفحة واحدة عبر HTTP.

أسطح التطبيق الحالية

توفّر الواجهة الحالية ما يلي:

• المحادثة ومحادثات النظراء المباشرة
• مساحة عمل الشبكة للخريطة والنظرة العامة والروابط والمسارات وأجهزة الاستشعار وأفضل 10 تصنيفات وتفاصيل العقدة والسجل عند الطلب
• مساحة عمل Console لإخراج الحزم/السجلات المباشر
• مساحة عمل Apps مع ألعاب وتبويب Files عند تفعيل نقل الملفات
• مساحة عمل Settings مع أجزاء الراديو والجهاز والاتصال والموقع والقنوات وtickers والقوائم والمظهر وحول
• سجل مدعوم بـ SQLite، والبحث، والتجميعات (rollups)، واستمرار المظهر، واستمرار قواعد القياس عن بُعد المخصصة

مساحة عمل Console

مساحة عمل Console هي سطح تحكم بأسلوب طرفية لحركة الحزم، والبحث في السجل، وأوامر أدوات الشبكة.

• اكتب اسم أمر لفتح اقتراحات الإكمال التلقائي. استخدم Tab أو Enter للقبول، وArrowRight لقبول اللاحقة المعروضة باهتة، وArrowUp / ArrowDown للتنقل داخل النافذة المنبثقة.
• الأوامر التي تتطلب عقدة هدف تعرض اقتراحات عقد غنية بالاسم والمعرّف والرمز التعبيري والوسم والحالة والقفزات (hops) ونظام تحديد المواقع (GPS) وآخر حالة استماع والمنافذ ورقم العقدة. النص العادي يضيّق النتائج حسب أسماء العقد ووسومها؛ و! يضيّق حسب معرّف العقدة.
• live يبث حركة الحزم حتى Ctrl+C أو q. استخدم live grep <text> أو live rg <text> أو live filter=<text> أو live <text> فقط لبث مجموعات الحزم المباشرة المطابقة فقط. ما تزال فلاتر الطبقة والتفصيل (verbosity) مطبَّقة، على سبيل المثال live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <text> وrg <text> يبحثان في سجل الحزم/المحادثة المحتفظ به مع نوافذ سياق، وحدود، وفلاتر مصدر الحزم/المحادثة، وفلاتر نطاق الملخص/الحزم.
• /search <text> يفلتر مخرجات Console المرئية من موجه الأوامر دون بدء بحث في السجل المحتفظ به.

لقطات الشاشة

خريطة الشبكة المباشرة

عرض الخريطة مع مواقع العقد، والروابط، والمسارات الشائعة، والعناقيد، وخريطة حرارة الإشارة.

نظرة عامة على الشبكة

عرض السجل لأعداد العقد، وحالة الاتصال، والعقد الجديدة، وتقارير المواقع.

طوبولوجيا الروابط

عرض الطوبولوجيا الذي يظهر الروابط المرصودة من العقدة الجذرية المحددة.

تتبع المسار

عرض التتبع لمصدر ووجهة وروابط قريبة وتفاصيل الحزم لكل قفزة.

سجل أجهزة الاستشعار

مخطط القياس عن بُعد الذي يقارن سجل أجهزة الاستشعار عبر عقد متعددة.

بطاقات الحالة

بطاقات علوية لنشاط الراديو، وأعداد العقد، والحزم، والروابط، والبطارية، واستخدام القنوات.

تخصيص المظهر

يمكن للمظاهر إعادة تشكيل لوحة التحكم بالكامل بألوان مخصصة، وتدرجات لونية، وشفافية، وضبابية، وخطوط، وجسيمات، أو خلفية خريطة مباشرة. هذه اللوحات مثال على مظاهر مخصصة؛ اختر أي معاينة لفتح لقطة الشاشة بدقة كاملة.

Signal Green	Neon Magenta	Aurora Relay

مظاهر العقد المشتركة

يمكن لعقد Meshyface مشاركة حزم مظهر مضغوطة تحتوي على وصفة مظهر للعقدة وعلامة مائية أو شبح اختيارية. هيّئ عقدتك وعاينها في Settings > Appearance > Node Appearance، وفعّل Share node appearance، ثم استخدم Broadcast appearance لنشرها.

• تستخدم حزم المظهر قناة الإرسال الخاصة بملفات التعريف (Profiles) وترث إعداد حد القفزات في الراديو؛ لا تفرض Meshyface حد قفزات منفصلًا.
• يمكن للمظاهر المستلمة تنسيق هويات العقد في المحادثة، وقوائم الأعضاء، وتفاصيل العقد، والخرائط، والرسوم البيانية، وأجهزة الاستشعار، وtickers دون استبدال مظهر لوحة التحكم المستلمة نفسها.
• إيقاف تشغيل Share node appearance يعطّل جانبي الميزة. فهو يوقف البث ويتجاوز مسار استقبال ملفات التعريف قبل فك ترميز حزم المظهر الواردة أو تخزينها مؤقتًا أو حفظها؛ ويتم مسح المظاهر المشتركة المخزنة مؤقتًا ولا يتم عرض أي مظهر مستلم.
• عند تفعيل السجل، تستمر ملفات التعريف المستلمة وتفضيل المشاركة المحلي في قاعدة بيانات SQLite الخاصة بالسجل.
• المظاهر المشتركة بيانات وصفية تجميلية. لا يغيّر المظهر المستلم إعدادات الراديو أو القنوات أو مظهر الحزمة المحفوظ للوحة التحكم.

بنية النظام

flowchart LR
  Browser["Browser<br/>single-page UI"]
  CDN["Vendored browser assets<br/>Leaflet + leaflet.heat + particles.js"]
  Tiles["Basemap provider<br/>OpenStreetMap tile service"]
  Server["ThreadingHTTPServer<br/>HTML shell + JSON API"]
  Assets["Python template assembly<br/>meshdash/html* + meshdash/assets/*"]
  State["State loaders<br/>live snapshot + history readers"]
  Services["Write services<br/>chat, settings, tools, games, optional files"]
  Tracker["DashboardTracker<br/>live receive path + in-memory buffers"]
  History["HistoryStore / SQLite (WAL)<br/>chat, packets, rollups, settings"]
  Radio["Meshtastic interface<br/>serial or TCP"]
  Mesh["Meshtastic radio / mesh"]
  Atlas["Bundled offline atlas<br/>reference basemap fallback"]

  Browser -->|GET /| Server
  Browser -->|GET /api/*| Server
  Browser -->|POST write APIs| Server
  Browser --> CDN
  Browser --> Tiles
  Browser -->|fallback basemap data| Atlas
  Server --> Assets
  Server --> State
  Server --> Services
  State <--> Tracker
  State <--> History
  Services <--> History
  Services <--> Radio
  Radio <--> Mesh
  Radio -->|receive callbacks| Tracker

التثبيت

ابدأ بـ المتطلبات والتبعيات، ثم اختر مسار تثبيت واحد:

• التشغيل اليدوي في المقدمة: استنسخ في أي مكان وشغّل لوحة التحكم مباشرة.
• خدمة systemd الموصى بها: استنسخ إلى /opt/meshyface لاستضافة مستمرة قابلة للتحديث عبر GitHub.
• Docker: شغّل نقطة دخول التطبيق نفسها في حاوية مع تركيب /data للحالة المستمرة.
• نشر الدفع من محطة العمل: انسخ نسخة محلية إلى جهاز هدف عبر SSH.
• طوبولوجيا تشغيل Proxmox: اختر موضع راديو TCP أو USB لتثبيت VM/LXC.
• حزم الخرائط دون اتصال: أضف بيانات خرائط محلية مفصلة للوحات المعزولة عن الشبكة أو منخفضة الاتصال.

البيانات والتخزين

قاعدة بيانات السجل المشتركة

--history-db هو اسم ملف SQLite النهائي على القرص. لم تعد لوحة التحكم تضيف لاحقة الراديو المتصل، لذا فإن أي راديو يُوصَل بلوحة التحكم يساهم في نفس سجل الحزم والمحادثة والعقد والتجميعات المحفوظ.

أوضاع السجل

• الوضع الافتراضي يحفظ المحادثة والحزم وأحداث الاتصال وتحليلات العقد وسجلات النص التالف ومقاييس البيئة وتجميعات الملخص في SQLite.
• --no-history يعطّل التخزين المستمر ويبقي فقط المخازن المؤقتة الحية في الذاكرة.
• تُؤخذ عينات تجميعات الملخص أيضًا في الخلفية أثناء تشغيل لوحة التحكم عند تفعيل السجل.

المظهر والإعدادات المحلية

• حفظ اختيار مظهر مسبق يبقى في mesh_dashboard_theme_settings.json افتراضيًا، أو في الملف المقدَّم عبر --theme-settings-file.
• تُخزَّن قواعد القياس عن بُعد المخصصة في قاعدة بيانات SQLite الخاصة بالسجل.

أوامر الصيانة

الأوامر التشغيلية التي تفحص بيانات لوحة التحكم المحلية أو تصلحها موثقة في docs/maintenance.md.

دلالات عرض الروابط

العرض الفرعي Links هو عرض طوبولوجيا، وليس إعادة تشغيل لمسار الحزم.

• وضع History يرسم من سجل الروابط المخزَّن المحفوظ في SQLite.
• وضع Live يرسم من ملاحظات روابط الجلسة الحالية فقط.
• الحلقات المرقّمة تعرض أقصر مسافة في الرسم البياني من الجذر الحالي باستخدام بحث بالاتساع (breadth-first search) عبر رسم بياني للروابط المرصودة.
• أرقام الحلقات هذه ليست قفزات إرسال Meshtastic حرفية وليست تتبعًا للحزم في الوقت الفعلي.
• بيانات وصفية لقفزات الحزم، عندما تكون متاحة، تظهر مع ذلك بشكل منفصل في تفاصيل العقدة أو الحافة كقيم قفزات حزم.

الجذر الحالي هو العقدة التي يتمحور حولها الرسم البياني. اختيار عقدة مختلفة يغيّر الجذر ويعيد حساب حلقات المسافة المرقّمة من تلك العقدة.

مرجع الإعدادات

الاتصال والنقل

• --mesh-host <ip-or-dns>: مضيف راديو TCP
• --mesh-tcp-port <port>: منفذ راديو TCP، الافتراضي 4403
• --mesh-port <path>: مسار جهاز تسلسلي (serial)
• --default-gateway-host <host>: مضيف TCP احتياطي إذا لم يتم توفير --mesh-host وكان المنفذ التسلسلي ما يزال على المسار الافتراضي
• --default-gateway-port <port>: منفذ TCP احتياطي لـ --default-gateway-host
• --no-default-gateway: فرض التسلسلي ما لم يتم تعيين --mesh-host صراحةً

متغيرات البيئة ذات الصلة:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT للمسار التسلسلي الافتراضي

HTTP والواجهة والأمان

• --http-host <host>: مضيف الربط، الافتراضي 0.0.0.0
• --http-port <port>: منفذ الربط، الافتراضي 8877
• --refresh-ms <ms>: فترة استطلاع المتصفح، الافتراضية 3000
• --packet-limit <n>: حجم مخزن الحزم المباشرة الأخيرة، الافتراضي 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: إظهار المفاتيح الخاصة/كلمات المرور/مفاتيح PSK في لوحات JSON الخام
• --debug-mode / --no-debug-mode: إظهار أسطح لوحة تحكم خاصة بالتصحيح مثل تشخيصات الشبكة المتقدمة

متغيرات البيئة ذات الصلة:

• MESH_DASH_PRIVATE_MODE
• MESH_DASH_API_TOKEN
• MESH_DASH_GAMES_ENABLE
• MESH_DASH_VERSION
• MESH_DASH_GIT_COMMIT
• MESH_DASH_PR_NUMBER

الهوية في وقت التشغيل تأتي من التزام git المكوّن من 12 حرفًا، متبوعًا برقم طلب سحب اختياري، على سبيل المثال abc123456789 · PR #43. لوحة Software تعرض هذا التنقيح الواحد بدلاً من إصدار حزمة. يتم اكتشاف مواضيع التزامات الدمج/الضغط في GitHub تلقائيًا؛ ويمكن لنشر المعاينة غير المدمج تعيين MESH_DASH_PR_NUMBER صراحةً.

/api/revision هي نقطة نهاية الهوية الأساسية. حقلا revision و build_ref يبلغان عن تنقيح وقت التشغيل، بينما يبقيان commit وpr_number متاحين كحقلين منظمين. تبقى /api/version نقطة نهاية قديمة، ويحتفظ حقل version فيها ببيانات وصفية للإصدار/الحزمة. MESH_DASH_VERSION محجوز بالمثل للتعبئة الإصدارية الصريحة و لا يظهر في لوحة التحكم.

نقل الملفات

• --file-transfer-enable: تفعيل تطبيق Files؛ يتطلب --accept-file-transfer-traffic-disclaimer
• --file-transfer-auto-accept: قبول عمليات النقل الواردة المباشرة دون تأكيد من المتصفح
• --file-transfer-max-bytes <bytes>: حد لكل ملف، الافتراضي 65536 و مقيد بـ 1024-524288

تستخدم عمليات النقل بروتوكول MF_FILE_V2 التجريبي على المنفذ الخاص 258 وهي غير متوافقة مع نقل الرسائل النصية السابق. عندما يكون لدى الوجهة عدد قفزات مكتشف قابل للاستخدام، تستخدم Meshyface ذلك العدد زائد واحد، مع سقف حد قفزات الراديو المكوّن. بيانات القفزات الأقدم من ساعة واحدة ترجع إلى الحد المكوّن. يعرض تطبيق Files الحد المحدد ومصدره.

متغيرات البيئة ذات الصلة:

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

السجل والتحليلات

• --history-db <path>: مسار قاعدة بيانات SQLite الأساسي
• --history-max-rows <n>: الافتراضي 200000
• --history-retention-days <days>: الافتراضي 30، استخدم 0 لتعطيل تقليم العمر
• --history-event-max-rows <n>: سقف أحداث الحزم للإلحاق فقط، الافتراضي 200000
• --history-event-retention-days <days>: الافتراضي 30
• --history-rollup-retention-days <days>: الافتراضي 365
• --no-history: وضع الذاكرة فقط
• : تهيئة المتتبع المباشر من NodeDB للراديو المتصل

متغيرات البيئة ذات الصلة:

• MESH_DASH_HISTORY_DB

المظاهر

• --theme-presets <json>: ملف مظاهر مسبقة مخصص اختياري
• --theme-preset <name>: اسم المظهر المسبق المحدد
• --theme-settings-file <json>: ملف اختيار المظهر المحفوظ في وقت التشغيل

المظاهر المسبقة المدمجة:

• default (أزرق Meshyface الآمن، الجسيمات معطلة)
• custom (مظهر عرض مع جسيمات وتأثيرات خلفية مفعّلة)

التثبيتات الجديدة تكون افتراضية على default ما لم يحدد ملف إعدادات مظهر محفوظ أو MESH_DASH_THEME_PRESET مظهرًا مسبقًا آخر.

متغيرات البيئة ذات الصلة:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

الأمان

• لوحة التحكم هذه مخصصة لبيئات LAN/VPN الموثوقة.
• لا تعرّضها مباشرة للإنترنت العام بدون وكيل عكسي (reverse proxy) و تحكم في الوصول.
• استخدم --private-mode و/أو رمز API للتحكم الأكثر صرامة في مسار الكتابة.
• فضّل MESH_DASH_API_TOKEN على --api-token على المضيفات المشتركة أو متعددة المستخدمين. يمكن أن يكون رمز سطر الأوامر مرئيًا في قوائم العمليات ومحفوظًا في سجل الصدفة.
• الإعداد المسبق المدمج Join Meshyface للقناة يستخدم PSK خاص بـ Meshyface عامًا عمدًا للتوافق بين مستخدمي هذا البرنامج. لا تستخدم تلك القناة العامة لحركة مرور خاصة.
• --show-secrets يعرض قيمًا حساسة في لوحات JSON الخام؛ لا تفعّله بشكل عابر على شاشات مشتركة.
• تنزيلات قاعدة بيانات الحزم الخام يمكن أن تكشف محتويات الرسائل والقياس عن بُعد. على المضيفات المشتركة، اطلب رمز API واستخدم --no-allow-tokenless-raw-packet-download.
• يمكن أن يستهلك نقل الملفات قدرًا كبيرًا من زمن البث اللاسلكي للشبكة. أبقِه معطلاً ما لم تكن قد قبلت صراحةً تلك المقايضة.

الاختبار والتغطية

شغّل مجموعة الاختبارات العادية:

python -m pytest

شغّل Ruff بنفس الطريقة التي يعمل بها CI:

scripts/run_ruff_local.sh

شغّل تقرير تغطية التطبيق الاستشاري:

python -m pytest \
  --cov=meshdash \
  --cov=mesh_dashboard \
  --cov=mesh_connection \
  --cov-report=term

شغّل بوابة التغطية المحلية بالحد الأدنى الأكثر صرامة وهو 85%:

scripts/run_coverage_local.sh

شغّل معيار استجابة واجهة المستخدم الرسومية المحلي قبل طلبات السحب:

scripts/run_gui_responsiveness_local.sh

تستثني التغطية عمدًا حزمة محرك Zork المنقولة من التسجيل، لكن اختبارات Zork المستقلة والتوجيه ما تزال تعمل. ينشر GitHub Actions نفس تقرير التغطية كتعليق استشاري وقطعة أثرية على طلب السحب. يفشل CI تحت 80%. تبقى البوابة المحلية أعلى من CI بـ 5 نقاط مئوية.