مدخل إلى Silicon Labs BGAPI: كيف يتحكم مضيف Linux في وحدة Bluetooth Mesh عبر المنفذ التسلسلي؟

دليل ربط Linux بوحدة Silicon Labs Bluetooth Mesh NCP: توافق البرنامج الثابت وXAPI، والتحكم بتدفق UART، وأحداث الإقلاع وأدوار العقدة والتزويد.

عند الحديث سابقًا عن اختيار شريحة لبوابة Bluetooth Mesh، ذُكر تقسيم للمهام: يتولى مضيف Linux منطق التطبيق، وتتولى وحدة Silicon Labs مكدس البروتوكول اللاسلكي، ويتواصل الطرفان عبر منفذ تسلسلي.

يبدو ذلك بسيطًا في جملة واحدة. لكن عند البدء بالتوصيل فعليًا، من السهل الوقوع في مشكلة: «المنفذ التسلسلي يُفتح، لكن الوحدة لا تستجيب للأوامر».

وغالبًا لا يكون السبب غياب أمر سحري لتشغيل الضوء، بل عدم توافق بضعة متطلبات مسبقة: البرنامج الثابت المثبّت على الوحدة، وتعريفات API التي يستخدمها المضيف، والتحكم في تدفق البيانات عبر المنفذ التسلسلي، ودور جهاز Mesh داخل الشبكة.

تنطلق هذه المقالة من وثائق NCP الرسمية وأمثلة Python لتفصيل هذه السلسلة. هذا دليل تكامل يستند إلى الشيفرة المصدرية، ولم يُستكمل فيه اختبار تكامل فعلي على لوحة تطوير بعينها؛ ويجب التحقق من الأرجل ومعدل البود ومكوّنات البرنامج الثابت وفق العتاد وSDK المستخدمين.

يتحكم مضيف Linux في نقطة دخول إلى مكدس البروتوكول

في وضع NCP، أي المعالج المساعد للشبكة، يعمل منطق التطبيق على المضيف، بينما يعمل مكدس Bluetooth على الشريحة المستهدفة. وتستخدم Silicon Labs بروتوكول BGAPI لتعريف الأوامر والاستجابات والأحداث المتبادلة بينهما، ويُعد UART وسيلة اتصال شائعة.[1][2]

يمكن تصور المسار كما يلي:

برنامج التطبيق على Linux → مكتبة BGAPI للمضيف → المنفذ التسلسلي → برنامج NCP الثابت من Silicon Labs → شبكة Bluetooth Mesh.

BGAPI هو بروتوكول واجهة المضيف لدى Silicon Labs؛ وليس بروتوكول Mesh اللاسلكي، ولا مجموعة أوامر AT التي تستطيع أي وحدة Bluetooth تسلسلية فهمها.

بعد إرسال المضيف أمرًا، يعيد الطرف المستهدف استجابة، وقد يبلّغ عن أحداث بصورة غير متزامنة. لذلك لا يكفي كتابة حلقة «أرسل بايتات ثم انتظر ثانية» واعتبار غياب الاستثناءات دليلًا على اكتمال العملية.

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

الخطوة الأولى: تأكد من توافق البرنامج الثابت وواجهة API للمضيف

كون طراز الشريحة يدعم Bluetooth لا يعني أن البرنامج الثابت المثبّت عليها حاليًا يوفر قدرات Mesh NCP المطلوبة.

تميّز أمثلة pyBGAPI الرسمية بين أمثلة Bluetooth العادية وأمثلة Bluetooth Mesh. وتستخدم أمثلة Mesh ملفّي تعريف API: ‏sl_bt.xapi وsl_btmesh.xapi. كذلك لا يمكن اعتبار البرامج الثابتة الخاصة بـBLE العادي، وعُقد Mesh، وإدارة التزويد بالشبكة قابلة للتبادل لمجرد أنها تحمل جميعًا اسم «NCP».[1]

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

قبل البدء، يُنصح بتدوين أربع نقاط:

  1. طراز لوحة التطوير والشريحة، وواجهة العتاد المستخدمة.
  2. اسم مثال البرنامج الثابت، وإصدار SDK، ومكوّنات Mesh المفعّلة.
  3. إصدار برنامج المضيف، ومصدر ملفات تعريف API، وإصدار مكتبة Python.
  4. الدور المستهدف: هل سيكون الجهاز عقدة تُضاف إلى الشبكة، أم Provisioner يدير إضافة عقد أخرى؟

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

الخطوة الثانية: طابق إعدادات UART والتحكم في التدفق

وجود ملف جهاز للمنفذ التسلسلي لا يعني سوى أن Linux تعرّف على واجهة المنفذ، ولا يعني أن البرنامج الثابت المستهدف جاهز بالضرورة.

قبل التوصيل، راجع وثائق اللوحة للتحقق من مستويات الجهد والأرضي وTX/RX، وكذلك RTS/CTS عند تفعيل التحكم في التدفق بالعتاد؛ ولا توصل واجهة بمستويات جهد RS-232 مباشرة بأرجل UART على الشريحة. وإذا استُخدم منفذ تسلسلي افتراضي عبر لوحة التطوير، فتحقق أيضًا من إعدادات المنفذ التسلسلي في أداة التنقيح المدمجة باللوحة.

تفعّل أمثلة NCP في الإصدار القديم من AN1259 التحكم في التدفق بالعتاد افتراضيًا، وتؤكد ضرورة تطابق إعداداته بين الطرف المستهدف ولوحة التطوير.[2] وقد يفسر ذلك حالة شائعة: يمكن فتح المنفذ التسلسلي، لكن البيانات لا تتقدم لأن أحد الطرفين ينتظر إشارة التحكم في التدفق من الآخر.

لكن هذا لا يجعل عبارة «كل واجهات BGAPI تتطلب أربعة أسلاك» قاعدة في البروتوكول. يعتمد النقل وإعداد التحكم في التدفق على البرنامج الثابت والعتاد المحددين. والتوصية هنا هي: إذا بدأت من مثال يفعّل RTS/CTS افتراضيًا، فاحتفظ بهذا الإعداد كاملًا وطابقه أولًا؛ لا توصل سلكَي البيانات وحدهما بينما يظل البرنامج ينتظر إشارات التحكم في التدفق.

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

الخطوة الثالثة: تحقق من مسار بدء التشغيل باستخدام أصغر مثال رسمي

إصدار pybgapi-examples الرسمي الذي جرت مراجعته هنا مثبت عند الالتزام 87d004f.[1] يسهّل تثبيت الالتزام إعادة إنتاج الخطوات، لكنه لا يضمن بحد ذاته ملاءمته لكل إصدارات SDK المستخدمة لديك. تحقق أولًا من تعريفات API المرفقة به ومن البرنامج الثابت المستهدف.

في دليل محلي جديد، يمكنك إعداد بيئة Python مستقلة وفحص معاملات المثال:

git clone https://github.com/SiliconLabs/pybgapi-examples.git
cd pybgapi-examples
git checkout 87d004f1db3993bfa35783bec1ac58c32b5303e4
python3 -m venv .venv
. .venv/bin/activate
python -m pip install pybgapi
python example/btmesh_empty/app.py -h

بعد نجاح التثبيت، سجّل إصدار المكتبة الذي ثُبّت فعليًا. لا تُقدَّم هنا «توليفة إصدارات تصلح لكل شيء» من دون تحقق؛ فإذا لم يتطابق SDK، فاستخدم المثال وملفات API المتوافقة مع البرنامج الثابت، ثم أعد التحقق من الواجهات.

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

python example/btmesh_empty/app.py /dev/ttyACM0

المسار /dev/ttyACM0 مجرد مثال، ويجب استبداله بالجهاز الفعلي. دالة الاتصال المختصرة في المستودع مخصصة لإعدادات لوحات التطوير الافتراضية؛ أما تخصيص معاملات المنفذ التسلسلي فيتطلب تعديلها وفق واجهة المكتبة، ولا يصح إضافة خيار لمعدل البود أو التحكم في التدفق إلى الأمر من دون أن يكون موجودًا.[3]

هذا البرنامج يُجري عمليات على الجهاز المستهدف، وليس فحصًا للقراءة فقط. في الشيفرة التي جرت مراجعتها، يطلب مسار بدء التشغيل إعادة التشغيل، ثم يستدعي btmesh.node.init() بعد استقبال bt_evt_system_boot، وبعدها يعالج المثال حدث تهيئة العقدة؛ وإذا لم تكن العقدة قد أُضيفت إلى الشبكة، يبدأ الإعلان عن كونها غير مزوّدة بالشبكة.[3][4]

الهدف من هذه الخطوة هو رؤية اكتمال بدء التشغيل وتهيئة العقدة بين المضيف والطرف المستهدف، وليس التحكم فورًا في مصابيح المنزل.

ما زال ملف README في المستودع الرسمي يذكر أن عملية reset في مثال Mesh تمحو إعدادات العقدة السابقة، بينما تستدعي شيفرة BtMeshApp.reset() التي جرت مراجعتها bt.system.reboot(). وهما غير متطابقين. تفسر هذه المقالة الشيفرة وفق الالتزام المثبت، ولا تساوي بين تشغيل المثال واستعادة إعدادات المصنع؛ ومع ذلك، يجب فحص الإصدار المستخدم فعليًا، ولا سيما تجنب تجربة عملية reset غير واضحة المعنى على جهاز منضم بالفعل إلى شبكة إنتاج.[1][3]

الخطوة الرابعة: حدد من يضيف الأجهزة إلى الشبكة ومن يتحكم فيها

تهيّئ الفئة الأساسية في btmesh_empty دور Node. والإعلان عن عدم تزويد العقدة بالشبكة يعني «هذه العقدة تنتظر الانضمام إلى الشبكة»، ولا يعني «بدأت بإضافة مصابيح أخرى إلى الشبكة».

إذا كانت بوابتك ستبحث عن أجهزة غير مضافة إلى الشبكة، وتمنحها هوية شبكية، وتضبط إعداداتها، فيجب تصميمها وفق مسار Host Provisioner في SDK، مع التحقق من البرنامج الثابت والدور وتطبيق المضيف المقابل، لا الاكتفاء بإضافة استدعاء لتشغيل المصباح بعد مثال Empty.[1][2]

وحتى إذا أُضيف الجهاز إلى الشبكة بنجاح، فلن يعني ذلك اكتمال إعداد طبقة التطبيق تلقائيًا. للتحكم في مصباح، عليك معرفة العناصر والنماذج التي يدعمها، ومفتاح AppKey المستخدم، وكيفية ربط النماذج به، وما إذا كان التحكم يُرسل إلى عنوان أحادي أم عنوان مجموعة، وما إذا كانت علاقات الاشتراك صحيحة.

شُرحت هذه العلاقات في نجح تزويد Bluetooth Mesh بالشبكة، فلماذا لا يزال المصباح لا يستجيب؟. لا يوفر NCP عبر المنفذ التسلسلي سوى نقطة دخول إلى مكدس البروتوكول، ولا يلغي هذه الخطوات.

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

الخطوة الخامسة: اترك حلقة الأحداث للاتصال

تتولى الفئة المشتركة في الأمثلة الرسمية استقبال الأحداث ثم تمريرها إلى دوال معالجتها المناسبة.[1][3] وهنا أيضًا يسهل أن يفقد برنامج المضيف تنظيمه: يستقبل رسالة، ثم يطلب واجهة سحابية، ويكتب في قاعدة البيانات، ويجري حسابًا طويلًا، فتتكدس الأحداث اللاحقة كلها.

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

ويجب أيضًا تحديد ما سيحدث عند انتهاء مهلة الأمر. فعدم وصول نتيجة لا يعني بالضرورة أن الجهاز المستهدف لم ينفذ العملية؛ وقد يؤدي تكرار الإرسال مباشرة إلى تنفيذها مرة ثانية. وينبغي تصميم قرار إعادة المحاولة وطريقة ربط الطلب بالحالة وفق API والنموذج ومعنى العملية في التطبيق.

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

عند التعطل، افحص كل طبقة على حدة

الظاهرة الملحوظة ما ينبغي فحصه أولًا استنتاج لا يمكن استخلاصه بعد
لا يظهر جهاز منفذ تسلسلي أو يتعذر فتحه برنامج التشغيل، والتوصيل، والصلاحيات، واستخدام عملية أخرى للجهاز أن الشريحة لا تدعم Mesh
يمكن فتح المنفذ التسلسلي، لكن حدث بدء التشغيل لا يصل نوع البرنامج الثابت، ومعدل البود، والتحكم في التدفق، وطريقة إعادة التشغيل، وتحليل API أن الإشارة اللاسلكية ضعيفة جدًا
يظهر حدث بدء التشغيل، لكن الأمر غير مدعوم توافق إصداري API والبرنامج الثابت، والمكوّنات، والدور، وترتيب التهيئة أن زيادة عدد مرات الإرسال ستحل المشكلة
تنجح تهيئة Mesh، لكن المصباح لا يستجيب التزويد بالشبكة، وAppKey، وربط النماذج، وعنوان الوجهة، والاشتراكات أن مسار BGAPI معطّل بالتأكيد
يعمل النظام على نطاق صغير ثم يصبح غير مستقر مع زيادة الحمل زمن معالجة الأحداث، والمخازن المؤقتة، والتحكم في التدفق، واستراتيجية إعادة المحاولة أن كل المشكلات سببها الترحيل اللاسلكي

إن ترك نتيجة قابلة للملاحظة في كل خطوة يسهّل تحديد موضع المشكلة أكثر من البدء ببناء بوابة كاملة. أثبت أولًا أن المضيف يتحاور مع NCP على نحو صحيح، ثم أثبت صحة إعدادات Mesh، وبعد ذلك فقط صِل النظام بـMatter ومنطق التطبيق الأعلى.

ويرتبط ذلك أيضًا بـقائمة التحقق من قبول تكامل البوابة: فبين «نجاح الإرسال عبر المنفذ التسلسلي» وظهور حالة الجهاز الصحيحة على الهاتف، توجد مراحل أخرى يجب التحقق من كل منها على حدة.

المراجع

تاريخ المراجعة: 2026-11-09. انتهت مهلة تحميل صفحات وثائق SDK الرسمية على الإنترنت خلال هذه المراجعة؛ لذا تستند هذه المقالة إلى الأمثلة الرسمية المثبتة عند التزام محدد وإلى مذكرة تطبيق محدد إصدارها بوضوح، ولا تدّعي تغطية جميع واجهات أحدث SDK.

  1. أمثلة Silicon Labs pyBGAPI: ملف README عند التزام مثبت، تقسيم مهام NCP، وتوافق API، ودورا Node وProvisioner، وشرح الأمثلة.
  2. AN1259: ‏Bluetooth Stack v3.x and Higher in NCP Mode، المراجعة 1.5، الصفحات 2 و16 و41 و47–49 وغيرها. يذكر الغلاف أن الوثيقة أصبحت مهجورة بعد إصدار Simplicity SDK Suite 2024.12.2؛ ولا تُستخدم هنا إلا لشرح البنية والتحكم في التدفق في الأمثلة القديمة المقابلة، لا باعتبار واجهاتها أو مساراتها أو أوامرها مضمونة في أحدث إصدار.
  3. الفئة المشتركة للمضيف وموصل المنفذ التسلسلي الرسميان.
  4. مثال Bluetooth Mesh Empty الرسمي.

رسم مفاهيمي مولّد بالذكاء الاصطناعي، وليس صورة اختبار منتج أو واجهة فعلية أو مخطط توصيل.

Discussion

Share a question or your experience. Comments appear after moderation. Your email is never displayed publicly. Comment privacy

Loading comments…