اتصال الأجهزة
هذا الفصل هو العقد الذي تتحدث به أجهزتك إلى SensoCAN. يرسل جهازك القراءات، فيطابق SensoCAN كل قراءة مع مستشعر أعددته، ثم يسلّمها إلى سلسلة القواعد الخاصة بذلك المستشعر. وتعتمد لوحات المعلومات والإنذارات والتصديرات كلها على ما يصل إلى هنا.
بروتوكولان ينقلان حمولة البيانات (payload) نفسها:
- MQTT: اتصال واحد دائم، وتنشر متى توفّرت لديك بيانات.
- HTTP: طلب واحد لكل قراءة أو دفعة، دون اتصال تبقيه مفتوحاً.
هل تستخدم إحدى بوابات BLE المدعومة بدلاً من برنامجك الثابت (firmware)؟ راجع فصل البوابات والمنارات.
اختيار البروتوكول
| MQTT | HTTP | |
|---|---|---|
| الاتصال | دائم ويبقى مفتوحاً | طلب واحد في كل مرة |
| التغذية الراجعة لكل رسالة | لا توجد | كاملة: أعداد القراءات المقبولة والمكرّرة والمرفوضة |
| الحِمل الإضافي لكل قراءة | منخفض جداً | مصافحة TLS وترويسات (headers) مع كل طلب |
| الملاءمة لجدار الحماية | يحتاج إلى منفذ صادر مفتوح | HTTPS عادي |
| التعبئة الرجعية دون اتصال | مدعومة | مدعومة |
| الاستخدام الأنسب | الأجهزة العاملة بالبطارية، ومعدلات الإرسال العالية، والوصلات الخلوية | الأجهزة خلف الشبكات المقيّدة، والبوابات التي لا تملك سوى حزمة HTTP، والتشغيل الأولي وتصحيح الأخطاء |
النشر عبر MQTT يخبرك بأن الرسالة غادرت الجهاز، لكنه لا يستطيع إخبارك بأن القراءة فُهمت، إذ لا توجد قناة رد. أما كل طلب HTTP فيرد عليك بما حدث لكل قراءة فيه. وعند تشغيل البرنامج الثابت لأول مرة، أرسل طلب HTTP واحداً واقرأ الاستجابة، ثم انتقل إلى MQTT بعد أن تتأكد من صحة الحمولة.
ما تحتاجه من المنصة أولاً
كل ما يحتاجه برنامجك الثابت موجود في صفحة تفاصيل الجهاز: افتح الأجهزة واختر اسم الجهاز.
| القيمة | أين تجدها | الاستخدام |
|---|---|---|
| معرّف الجهاز UUID | بطاقة معلومات الجهاز، مع زر نسخ | معرّف عميل MQTT؛ وجزء من كل عنوان URL في HTTP |
| موضوع MQTT | بطاقة معلومات الجهاز، معروضاً كاملاً مع زر نسخ | موضوع النشر على مستوى الجهاز |
| اسم مستخدم MQTT وكلمة المرور | زر بيانات اعتماد MQTT | الاتصال بمضيف MQTT |
| رمز الوصول | زر عرض الرمز | ترويسة Authorization في HTTP |
| المعرّف النصي للمستشعر ومعرّفه UUID | جدول المستشعرات ← افتح مستشعراً | توجيه القراءة إلى مستشعر بعينه |
لا تركّب المواضيع أو عناوين URL يدوياً. تعرض الصفحة الموضوع (topic) جاهزاً، ويفتح زر أمثلة حمولة MQTT المجاور له مواضيع وحمولات جاهزة معبّأة بمعرّفات هذا الجهاز الحقيقية.
أي شخص يملك رمز الوصول أو كلمة مرور MQTT يستطيع إرسال قراءات باسم هذا الجهاز. ويمكن إعادة إنشاء رمز الوصول في أي وقت من عرض الرمز، وهو ما يُبطل الرمز القديم فوراً ويمنع الجهاز من الاتصال حتى تبرمج القيمة الجديدة عليه. أما كلمة مرور MQTT فلا يمكن تدويرها بالطريقة نفسها؛ فإذا لزم تغييرها، لا يُعاد إصدارها تلقائياً إلا إذا فُقدت بيانات الاعتماد المخزّنة أو تعذّر فك تشفيرها.
قواعد الحمولة المشتركة بين البروتوكولين
غلّف القراءات داخل data. كل حمولة تحتوي على مفتاح data في المستوى الأعلى يحمل إما كائن قراءة واحداً وإما مصفوفة من الكائنات. ولا يُعامَل أي شيء خارج data على أنه قراءة.
value مطلوب، ويجب أن يكون رقماً. عبر HTTP تُرفض القيمة غير الرقمية. وعبر MQTT لا شيء يرفضها، لكن القواعد والمخططات والتصديرات تتوقع جميعها رقماً.
timestamp اختياري. أرسله بصيغة ISO 8601 (2026-09-03T10:00:00Z). وإذا أغفلته، تُختم القراءة بوقت وصولها.
ساعات الأجهزة تُصحَّح ولا يُعاقَب عليها. إذا سبق أحدث طابع زمني في الحمولة وقتَ وصولها، أي أن ساعة الجهاز متقدمة، تُزاح الحمولة كلها إلى الوراء بمقدار هذا الفارق الواحد: تحطّ أحدث قراءة عند وقت الوصول، وتبقى الفواصل بين القراءات كما هي. ولا يُهمَل شيء لأنه "في المستقبل"، فلا حاجة أبداً إلى فحص الساعة قبل تفريغ الذاكرة المؤقتة. وتسجّل القراءات المصحَّحة مقدار الإزاحة الذي طُبّق عليها في clock_offset_seconds ضمن بياناتها الوصفية المخزّنة، فتبقى البيانات المصحَّحة قابلة للتمييز عن البيانات المقيسة. أما الطوابع الزمنية في الماضي فتُخزَّن كما أُرسلت، وهذه هي التعبئة الرجعية المعتادة دون اتصال.
battery_voltage يقع بجوار data، لا داخله. أرسل الجهد بالفولت على هيئة رقم؛ ويُقبل أي رقم من 0 إلى 100، فخلية ليثيوم تبلّغ عن 3.7 مثال معتاد. وتعرضه صفحة تفاصيل الجهاز باسم الجهد الكهربائي مقابل نوع البطارية المهيَّأ للجهاز، وتشتق منهما نسبة المستوى. ويُتجاهَل في الأجهزة المضبوطة على التغذية المباشرة. وعبر MQTT يمكنك أيضاً نشر battery_voltage وحده، دون أي مفتاح data، على أي موضوع. أما عبر HTTP فيجب أن يتضمن كل طلب كائن data أو مصفوفة؛ فلا توجد نقطة نهاية (endpoint) للبطارية وحدها.
المفاتيح الإضافية تُنقل مع القراءة. يُحفظ أي مفتاح آخر داخل كائن القراءة بوصفه بيانات وصفية، ويمكن للقواعد قراءته: إصدار البرنامج الثابت، وقوة الإشارة، وعدد العينات. بحد أقصى 30 مفتاحاً لكل قراءة، وقيم مفردة فقط (بلا كائنات أو مصفوفات متداخلة)، وأسماء مفاتيح حتى 64 حرفاً، والنصوص تُقتطع عند 512 حرفاً.
القيم المكرّرة تُكبَح. في بعض أنواع المستشعرات، لا تُعالَج القيمة نفسها مرتين إذا أُرسلت مجدداً للمستشعر نفسه خلال ثوانٍ قليلة. لذا فإعادة إرسال محتوى الذاكرة المؤقتة آمنة، والتكرار ليس خطأً أبداً.
المقبول ليس هو المخزَّن
تُسلَّم القراءة المقبولة إلى سلسلة القواعد التي تنطبق على ذلك المستشعر، وهذه السلسلة هي التي تقرر ما يحدث بعد ذلك، بما في ذلك ما إذا كانت القراءة ستُحفظ. وكل حساب يبدأ ومعه سلسلة القواعد الافتراضية التي تحفظ كل ما يصلها. وإذا استبدلتها بسلسلة خاصة بك لا تتضمن خطوة حفظ، فسيظل جهازك يتلقى ما يفيد بقبول قراءاته بينما لا يظهر شيء في صفحة الجهاز. راجع السلسلة في الإدارة ← سلاسل القواعد قبل أن تشك في برنامجك الثابت.