إنشاء جهاز افتراضي من Matter

‫1. مقدمة

‫Matter هو بروتوكول اتصال يوفّر فرصًا رائعة لتطوير الأجهزة الذكية. في هذا الدرس العملي، ستنشئ جهاز Matter الأول باستخدام موارد من حزمة تطوير البرامج (SDK) الخاصة بـ Matter.

لمزيد من المعلومات حول Matter، يُرجى زيارة مركز مطوّري Google Home أو الموقع الإلكتروني لتحالف معايير الاتصال.

أهداف الدورة التعليمية

  • كيفية إعداد بيئة إصدار Matter
  • كيفية إنشاء جهاز Matter افتراضي يعمل على الكمبيوتر
  • كيفية إعداد جهاز Matter الافتراضي والتحكّم فيه باستخدام Google Home

المتطلبات

  • جهاز محوّر، وهو أي جهاز Google Nest متوافق مع Matter، مثل Nest Hub (الجيل الثاني)
  • جهاز Linux يعمل بنظام النوافذ X11
  • ‫Docker
  • Git
  • معرفة أساسية بنظام التشغيل Linux
    • يُرجى العِلم أنّ واجهة سطر الأوامر المفترَضة لجميع الأوامر في هذا الدرس العملي هي BASH.

‫2. إعداد البيئة

التحقّق من جهازك

لا يتوافق إصدار Docker هذا مع أجهزة الكمبيوتر التي تعمل بنظامَي التشغيل Windows وmacOS. يمكنك تثبيت Matter وإنشائه يدويًا على جهاز macOS.

تفترض هذه التعليمات أيضًا أنّ جهاز Linux يعمل بنظام النوافذ X11. إذا كان جهاز Linux يعمل بنظام Wayland، تأكَّد من تثبيت X.Org أيضًا.

إعداد بيئة التطوير

  1. ثبِّت Docker Engine (لا تستخدِم Docker Desktop).
  2. استنسِخ حزمة تطوير البرامج (SDK) الخاصة ببروتوكول Matter، ودوِّن عملية الدمج التي نستخدمها في ما يلي.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. تشغيل حاوية إصدار باستخدام صور الدمج المتواصل (CI) العامة لحزمة SDK وتنفيذ الجهاز الافتراضي الذي تم إنشاؤه حديثًا من داخل هذه الحاوية ابحث عن الصورة التي تتطابق مع إصدار حزمة SDK على النحو التالي:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    إذا كنت تستخدم عملية الإرسال نفسها، من المفترض أن يظهر لك ghcr.io/project-chip/chip-build:66أولاً، عليك إعادة توجيه منافذ xhost حتى نتمكّن لاحقًا من استخدام تطبيقات واجهة المستخدم:
    xhost local:1000
    بعد ذلك، ابدأ الحاوية باستخدام الموارد المناسبة التي تمّت إعادة توجيهها من المضيف (عملية الدفع في حزمة تطوير البرامج (SDK) والشبكات وموارد العرض/الاتصالات).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

لنتعرّف على أمر Docker والخيارات التي مرّرناها إليه:

  • يسمح الخيار xhost local:1000 لنظام X Window بتلقّي اتصالات من المضيف المحلي على المنفذ 1000، ما يتيح استخدام واجهة مستخدم رسومية.
  • يشغّل الأمر docker run … image الصورة المحدّدة، ويجلبها من سجلّ Docker إذا لزم الأمر.
  • يسمح الخيار --ipc=host لـ Docker بمشاركة مساحة اسم الاتصال بين العمليات مع الجهاز المضيف.
  • تتيح العلامة --net=host لبرنامج Docker استخدام حزمة الشبكة الخاصة بالمضيف داخل الحاوية، وهو أمر ضروري لكي يتمكّن من تمرير زيارات mDNS من المضيف إلى الحاوية، ومشاركة شاشة X11 الخاصة بالمضيف.
  • تصدِّر -e DISPLAY $DISPLAY إلى المضيف، ما يتيح الوصول إلى واجهة الرسومات في نظامك. هذا الإذن مطلوب لتشغيل أداة ZAP عند تعديل مجموعات Matter.
  • يشغّل -it Docker باستخدام وحدة طرفية تفاعلية (tty)، بدلاً من تشغيله كعملية في الخلفية.
  • تثبّت --mount حزمة SDK التي تم استخراجها سابقًا في الحاوية.
  • يضبط الأمر --workdir دليل العمل عند التشغيل على دليل حزمة تطوير البرامج (SDK) الذي تم تحميله.

يمكنك اختياريًا تشغيل مثيل ثانٍ لجلسة نافذة الأوامر:

user@host> docker exec -it matter-container /bin/bash
$

إيقاف حاوية Matter Docker وبدء تشغيلها

عند تنفيذ أمر docker run، ستنشئ حاوية جديدة تحتوي على الصورة المحدّدة. عند إجراء ذلك، سيتم فقدان بياناتك القديمة التي تم حفظها في مثيل حاوية سابق. في بعض الأحيان، يكون هذا هو ما تريد حدوثه، لأنّه يتيح لك البدء بعملية تثبيت جديدة. ولكن في بعض الأحيان، قد تفضّل حفظ عملك وإعدادات البيئة بين الجلسات.

لهذا السبب، بعد إنشاء الحاوية، يمكنك إيقافها لمنع فقدان عملك.

user@host> docker stop matter-container

عندما تكون مستعدًا لإعادة التشغيل، ابدأ الحاوية وافتح نافذة وحدة طرفية:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

يمكنك فتح جلسات طرفية إضافية للحاوية باستخدام:

user@host> docker exec -it matter-container /bin/bash

أو ابدأ جلسة الجذر باستخدام:

user@host> docker exec -u 0 -it matter-container /bin/bash

عملية الإعداد الأوّلية لأجهزة Matter

إعداد حزمة تطوير البرامج (SDK)

ابدأ بإعداد حزمة تطوير البرامج (SDK) الخاصة ببروتوكول Matter. سيستغرق إكمال هذه العملية عدّة دقائق.

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

تم الآن إعداد حزمة تطوير البرامج (SDK) الخاصة ببروتوكول Matter. لإعادة تهيئة البيئة بسرعة في المستقبل، نفِّذ الأمر التالي:

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

مشاركة الملفات بين المضيف والحاوية

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

بشكل عام، استخدِم عمليات الربط عن طريق تشغيل الحاوية مع الوسيطة الإضافية --mount source=$(pwd),target=/workspace,type=bind لربط دليل العمل الحالي بالحاوية في /workspace.

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

يجب إدارة أذونات مستخدم الحاوية في الدليل المثبَّت في المضيف.

احصل على معرّف مجموعة مستخدم الحاوية من داخل الحاوية.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

افتح جلسة طرفية أخرى على مضيف الحاوية واضبط دليل العمل على الدليل الذي تم تركيبه بواسطة الحاوية.

اضبط المجموعة بشكل متكرّر للملفات في الدليل الذي تم تحميله على مجموعة مستخدم الحاوية.

user@host> sudo chgrp -R 1000 .

امنح المجموعة الأذونات المطلوبة في الدليل. يمنح هذا المثال مجموعة مستخدمي الحاوية أذونات القراءة والكتابة والتنفيذ على جميع الملفات في الدليل الذي تم تركيبه.

user@host> sudo chmod -R g+rwx .

يُرجى العلم أنّ هذه الأوامر لا تؤثر في إذن الملفات الجديدة التي أنشأها المستخدم المضيف. تذكَّر تعديل أذونات الملفات الجديدة التي تم إنشاؤها في الملف المضيف حسب الحاجة.

يمكنك إضافة مستخدم المضيف إلى مجموعة مستخدم الحاوية لاكتساب الأذونات على الملفات التي أنشأها مستخدم الحاوية.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3- Google Home Developer Console

Google Home Developer Console هو تطبيق الويب الذي يمكنك من خلاله إدارة عمليات دمج Matter مع Google Home.

يمكن استخدام أي جهاز Matter اجتاز شهادة Matter من مؤسسة Connectivity Standards Alliance (المعروفة باسم Alliance) في منظومة Google Home المتكاملة. يمكن إعداد الأجهزة التي لا تزال قيد التطوير ولم يتم اعتمادها في نظام Google Home المتكامل ضمن شروط معيّنة. يمكنك الاطّلاع على قيود الإقران لمزيد من المعلومات.

إنشاء مشروع مطوِّر

ابدأ بالانتقال إلى Google Home Developer Console:

  1. انقر على إنشاء مشروع.
  2. أدخِل اسمًا فريدًا للمشروع، ثم انقر على إنشاء مشروع. مربّع حوار "إنشاء مشروع جديد"
  3. انقر على + إضافة عملية دمج، وسيتم توجيهك إلى شاشة مراجع Matter، حيث يمكنك الاطّلاع على مستندات تطوير Matter وقراءة معلومات عن بعض الأدوات.
  4. عندما تكون مستعدًا للمتابعة، انقر على التالي: التطوير، ما يؤدي إلى عرض صفحة قائمة التحقّق من Matter.
  5. انقر على التالي: الإعداد.
  6. في صفحة الإعداد، أدخِل اسم المنتج.
  7. انقر على اختيار نوع الجهاز واختَر نوع الجهاز من القائمة المنسدلة (في هذه الحالة، Light).
  8. في "معرّف المورّد" (VID)، اختَر معرّف المورّد التجريبي، ثم اختَر 0xFFF1 من القائمة المنسدلة "معرّف المورّد التجريبي". في حقل "رقم تعريف المنتج" (PID)، أدخِل 0x8000 وانقر على حفظ ومتابعة، ثم انقر على حفظ في الصفحة التالية. استخدِم قيمتَي VID/PID هاتَين بالضبط، لأنّ خطوات الدرس العملي المبرمَج اللاحقة تعتمد عليهما.
    إعداد مشروع
  9. سيظهر لك الآن عملية الدمج ضمن عمليات دمج Matter.
  10. أعِد تشغيل المركز لضمان تلقّيه أحدث إعدادات مشروع دمج Matter. إذا كان عليك تغيير VID أو PID لاحقًا، عليك أيضًا إعادة التشغيل بعد حفظ المشروع لكي يصبح التغيير ساريًا. يمكنك الاطّلاع على إعادة تشغيل أجهزة Google Nest أو Google Wifi للحصول على تعليمات مفصّلة حول إعادة التشغيل.

4. إنشاء جهاز

يمكن العثور على جميع الأمثلة في Matter في المجلد examples في مستودع Github. تتوفّر عدة عيّنات، ولكنّنا سنركّز في هذا الدرس العملي على Chef.

Chef هو كلّ مما يلي:

  • تطبيق نموذجي يوفّر واجهة طرفية، ويضمّ ميزات متوفّرة أيضًا في تطبيق examples/shell.
  • نص برمجي يتبنّى مبدأ "الاتفاقية بدلاً من الإعداد" لتضمين العديد من المهام الشائعة اللازمة لتطوير جهاز متوافق مع Matter.

انتقِل إلى مجلد مثال Chef وأنشئ أول إصدار Matter:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

يتضمّن Chef بعض الخيارات التي يمكن الاطّلاع عليها من خلال تنفيذ chef.py -h. الخيارات التي نستخدمها هنا هي:

  • ‫-d: تحدّد نوع الجهاز الذي سيتم استخدامه. في هذه الحالة، سننشئ تطبيقًا للإنارة يتضمّن عناصر تحكّم في التشغيل/الإيقاف والمستوى.
  • ‫-z: يستدعي أداة ZAP لإنشاء ملفات المصدر التي تنفّذ نوع الجهاز. أي أنّه استنادًا إلى اختيارك للإضاءة، سينشئ ZAP تلقائيًا رمزًا برمجية يتم تضمينها في التصميم الذي يحدد الإضاءة (نموذج البيانات) وكيفية تفاعلها مع الأجهزة الأخرى (نموذج التفاعل).
  • ‫-b: عمليات الإنشاء
  • ‫-r: [اختياري] يفعّل خادم RPC على جهاز Matter الافتراضي لكي تتمكّن المكوّنات الأخرى (مثل واجهة المستخدم الرسومية) من التواصل مع الجهاز لضبط سمات نموذج البيانات واسترجاعها.
  • ‫-t linux: المنصة المستهدفة المنصات المتوافقة هي linux وnrfconnect وesp32. يمكنك تشغيل ./chef.py -h للاطّلاع على جميع الأوامر المتاحة والأنظمة الأساسية المستهدَفة المتوافقة. يُستخدَم linux لأجهزة Matter الافتراضية.

تشغيل الجهاز

يستخدم Matter منفذ TCP/UDP رقم 5540، لذا إذا كان لديك جدار حماية يعمل على جهاز الكمبيوتر، عليك إيقافه أو السماح باتصالات TCP/UDP الواردة على المنفذ رقم 5540.

شغِّل الجهاز الافتراضي في الحاوية باستخدام:

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

اترك جهازك قيد التشغيل. سننتقل الآن إلى تطبيق Google Home لنتمكّن من إعداد جهازك في Google Home.

إيقاف الجهاز

إذا كنت بحاجة إلى إيقاف الجهاز، يمكنك إنهاء البرنامج باستخدام CTRL+C. إذا لم يتم إغلاق التطبيق، قد تحتاج إلى استخدام CTRL+\ أيضًا.

يتم تخزين بيانات اعتماد جهازك الافتراضي في الدليل /tmp/، في ملفات تبدأ بالبادئة chip.

إذا أردت تكرار عملية الإعداد بأكملها من البداية، عليك حذف هذه الملفات من خلال تنفيذ الأمر التالي:

$ rm /tmp/chip*

5. تشغيل الجهاز

ملاحظة: لن تنجح هذه الخطوة إلا إذا سبق لك إعداد مشروعك في Google Home Developer Console.

Nest Hub

يجب توفّر مركز لتفعيل جهازك على شبكة Matter. هذا الجهاز هو جهاز Google Nest، مثل Nest Hub (الجيل الثاني)، الذي يتوافق مع Matter وسيعمل كجهاز توجيه حدود شبكة لأجهزة Thread وكطريقة تنفيذ محلية لتوجيه طلبات المنزل الذكي.

راجِع هذه القائمة لمعرفة مراكز الربط المتوافقة مع Matter.

قبل بدء عملية الإعداد، تأكَّد مما يلي:

  • يتم إقران مركزك بحساب Google نفسه الذي استخدمته لتسجيل الدخول إلى Google Home Console.
  • يجب أن يكون المحور متصلاً بشبكة Wi-Fi نفسها التي يتصل بها الكمبيوتر الذي تستخدمه لتشغيل جهاز Matter الوهمي.
  • يجب أن يكون الجهاز المركزي في البنية نفسها التي تستخدمها في تطبيق Google Home (يمثّل "المنزل" في مخطط Google Home بنيتك).

الحصول على رمز استجابة سريعة

تتطلّب عملية الإعداد توفير معلومات الإعداد الخاصة بمعيار Matter من خلال رمز استجابة سريعة. افحص ناتج وحدة تحكّم تطبيق Matter الذي سيتضمّن رابطًا لرمز الاستجابة السريعة ذي الصلة بعملية الإعداد.

تنفيذ عملية العمولة

  1. افتح تطبيق Google Home.
  2. انقر على + في أعلى يمين الشاشة.
  3. انقر على إعداد جهاز.
  4. انقر على جهاز جديد.
  5. اختَر منزلك وانقر على التالي.
  6. يبحث تطبيق Google Home عن جهازك. إذا ظهرت لك الرسالة "تم العثور على جهاز Matter..."، انقر على "نعم". بخلاف ذلك، انقر على إعداد جهاز آخر، ثم اختَر جهاز متوافق مع Matter من قائمة الأجهزة.
  7. وجِّه الكاميرا إلى رمز الاستجابة السريعة على جهازك أو رمز الاستجابة السريعة الذي تم إنشاؤه على الموقع الإلكتروني.
  8. واصِل عملية الإقران كما هو موضّح في مسار تطبيق Google Home.

بعد إكمال هذه الخطوات، من المفترض أن يتم إعداد جهاز Matter الافتراضي بنجاح، وأن يظهر كرمز جديد في تطبيق Google Home.

المصباح المقترن في تطبيق Google Home

تحديد المشاكل وحلّها

يتعذّر الإعداد وتظهر رسالة الخطأ "مشكلة في الاتصال" أو "تعذّر التواصل مع Google"

تعذُّر إعداد الجهاز بعد ظهور الرسالة "جارٍ فحص جهازك" لفترة طويلة

6. التحكّم في الجهاز

بعد إعداد جهازك المتوافق مع Matter بنجاح وظهوره في تطبيق Google Home كمصباح كهربائي، يمكنك اختبار التحكّم في الجهاز بطرق مختلفة:

  • استخدام "مساعد Google"
  • باستخدام تطبيق Google Home

مساعد Google

استخدِم "مساعد Google" على هاتفك أو مركز التحكم لتغيير حالة الجهاز من خلال الطلبات الصوتية، مثل قول "Ok Google، أريد تغيير حالة الأضواء".

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

تطبيق Google Home

يمكنك النقر على التصنيفين مفعّل وغير مفعّل بجانب رمز المصباح الظاهر في تطبيق Google Home.

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

7. تهانينا!

لقد أنشأت جهاز Matter الأول بنجاح. رائع!

في هذا الدرس العملي، تعلّمت كيفية:

  • ثبِّت بيئة تطوير Matter.
  • إنشاء جهاز افتراضي متوافق مع Matter وتشغيله
  • إعداد جهازك الافتراضي والتحكّم فيه من Google Home

لمزيد من المعلومات حول Matter، يمكنك الاطّلاع على المراجع التالية: