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

1. مقدمة

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

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

ما ستتعرَّف عليه

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

المتطلبات

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

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

فحص الأجهزة

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

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

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

  1. ثبِّت Docker Engine (لا تستخدم Docker Desktop).
  2. استنسِخ حزمة Matter SDK، مع مراعاة الالتزام الذي نستخدمه في ما يلي.
    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 System بتلقي اتصالات من المضيف المحلي على المنفذ 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

الإعداد الأولي للمسألة القانونية

إعداد حزمة تطوير البرامج (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

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

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

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

انتقِل أولاً إلى "وحدة تحكّم المطوّرين في Google Home":

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

4. إنشاء جهاز

يمكنك العثور على جميع الأمثلة المتوفّرة في Matter في مجلد examples في مستودع GitHub. تتوفّر نماذج متعددة، ولكن تركيزنا على هذا الدرس التطبيقي حول الترميز ينصبّ على Chef.

أما الشيف، فيكون:

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

انتقل إلى المجلد "مثال الشيف" وأنشئ أول إصدار لـ 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 الافتراضية.

تشغيل الجهاز

تستخدم المسألة القانونية منفذ 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 Console.

Nest Hub

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

يُرجى الرجوع إلى هذه القائمة للاطّلاع على الموزعات المتوافقة مع معيار Matter.

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

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

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

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

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

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

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

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

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

تعذُّر التشغيل بسبب "مشكلة في الاتصال" أو "تعذر الاتصال بـ Google" رسائل خطأ

  • تأكَّد من أنّك أنشأت مشروعًا باستخدام مجموعة VID/PID الصحيحة في Google Home Console، وأنّك ليست لديك مشاريع أخرى تستخدم مجموعة VID/PID نفسها.

تعذُّر التشغيل بعد "فحص جهازك" لفترة طويلة

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، اطّلِع على المراجع التالية:

  • يمكنك الاطّلاع على مقالة Matter Primer من خلال مركز المطوّرين في Google Home حيث ستتعرَّف على أساسيات مفاهيم Matter.
  • مواصفات Matter ومكتبة الأجهزة المتوافقة مع Matter ومكتبة مجموعة التطبيقات المتوافقة مع معيار Matter، والتي تم نشرها من قِبل Connectivity Standards Alliance
  • مستودع GitHub المطلوب