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

1- مقدمة

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

للتعرّف على 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. استنسِخ 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 بتلقّي الاتصالات من المضيف المحلي على المنفذ 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)

أعِد إعداد Matter SDK. ستستغرق هذه العملية عدة دقائق حتى تكتمل.

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

تم الآن إعداد Matter SDK. لإعادة إعداد البيئة بسرعة في المستقبل، شغِّل:

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 من تحالف معايير الاتصال في نظام 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. إذا كان عليك تغيير رقم تعريف المورّد أو رقم تعريف المنتج لاحقًا، عليك أيضًا إعادة التشغيل بعد حفظ المشروع لكي يصبح التغيير ساريًا. يُرجى الاطّلاع على مقالة إعادة تشغيل أجهزة 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 المنفذ 5540 لبروتوكولَي TCP/UDP، لذا إذا كان جهازك يتضمّن برنامج حماية، أوقِفه أو اسمح باتصالات 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 Graph بنيتك).

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

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

تنفيذ عملية التشغيل

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

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

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

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

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

  • تأكَّد من أنّك أنشأت مشروعًا باستخدام مجموعة VID/PID الصحيحة correct VID/PID combination في 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 في مركز Google Home للمطوّرين، حيث ستتعرّف على أساسيات مفاهيم Matter
  • مواصفات Matter ومكتبة أجهزة Matter ومكتبة مجموعات تطبيقات Matter، التي نشرها تحالف معايير الاتصال.
  • مستودع Matter على GitHub.