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

1- مقدمة

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

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

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

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

المتطلبات

  • الموزع (hub) هو أي جهاز Google Nest متوافق مع معيار Matter، مثل Nest Hub (الجيل الثاني).
  • جهاز يعمل بنظام التشغيل Linux ويشغّل نظام النافذة X11.
  • Docker.
  • الإلمام بأساسيات نظام Linux.

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

سنستخدم حاوية Docker المهيأة مسبقًا على جهاز مضيف يعمل بنظام التشغيل Linux. تتضمّن هذه الحاوية جميع الاعتماديات اللازمة لإنشاء جهاز افتراضي متوافق مع معيار Matter وتشغيله.

تحقق من الأجهزة

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

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

إعداد Docker

  1. ثبِّت Docker Engine (لا تستخدم Docker Desktop).
  2. اسحب صورة Docker من Docker Hub. في نافذة المحطة الطرفية، نفِّذ ما يلي:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    قد يستغرق اكتمال هذه العملية بضع دقائق.
  3. ابدأ تشغيل حاوية Docker قيد التشغيل:
    user@host> xhost local:1000
user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

بعد بدء الحاوية، من المفترض أن تظهر لك بعض النتائج التشخيصية متبوعة برسالة تؤكّد أنّ إعدادات الحاوية صحيحة، وأخيرًا، ستطلب منك واجهة أوامر الحاوية:

Environment looks good, you are ready to go!
$

لنفهم أمر Docker والخيارات التي نقلناها إليه:

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

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

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

عندما يتم فتح الوحدة الطرفية، ستكون ضِمن مستودع Matter المنسوخ إلى ~/connectedhomeip. ليس عليك اتّخاذ خطوات إضافية لإعداد Matter.

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

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

شغِّل حاويتك مع الوسيطة الإضافية --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 (التحالف) متوافق مع منظومة Google Home المتكاملة. إنّ الأجهزة قيد التطوير التي لم يتم اعتمادها يمكن تفويضها في منظومة Google Home المتكاملة في ظل ظروف معيّنة. يُرجى الاطّلاع على قيود الإقران للحصول على مزيد من المعلومات.

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

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

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

4- إنشاء جهاز

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

Chef هو أيضًا:

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

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

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

لدى الطاهي بعض الخيارات التي يمكن مشاهدتها من خلال تشغيل 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. وحدة التحكّم الافتراضية للجهاز

Virtual Device Controller هي تطبيق مستقل يوفّر واجهة مستخدم رسومية للتحكّم في حالات أجهزة Matter الافتراضية وعرضها. وهو يستخدم برنامج استدعاء إجراء عن بُعد (RPC) للاتصال بأجهزة Matter المرتبطة ببيئة التطوير الخاصة بك.

وحدة التحكّم الافتراضية للجهاز

توفّر وحدة التحكّم الافتراضية للجهاز تمثيلاً مرئيًا لجهازك الافتراضي.

يمكنك التفاعل مع الجهاز الافتراضي من خلال واجهة المستخدم الرسومية لوحدة تحكّم الجهاز الافتراضي (GUI). تؤثر التغييرات التي يتم إجراؤها في واجهة المستخدم الرسومية على نموذج البيانات الأساسي. يمكنك الاطّلاع على الأجهزة المتوافقة للحصول على القائمة الكاملة لأنواع الأجهزة الافتراضية المتوافقة مع معيار Matter.

تثبيت وحدة التحكّم الافتراضية للجهاز

يتم تثبيت Virtual Device Controller مسبقًا على حاوية Docker 20.04 Ubuntu.

تشغيل وحدة التحكم الافتراضية للجهاز

أنشئ مثيل الجلسة الطرفية الثانية:

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

ابدأ تشغيل وحدة التحكم في الجهاز الافتراضي من خلال توفير مقبس الشبكة الذي سيتم استخدامه للاتصال بالجهاز الافتراضي:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

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

واجهة مستخدم لرسم جهاز افتراضي

يرسل التطبيق الطلبات إلى خادم استدعاء إجراء عن بُعد (RPC) على الجهاز أثناء إجراء تغييرات على تطبيق وحدة التحكم الافتراضية، كما يجري استطلاعًا لخادم استدعاء إجراء عن بُعد (RPC) مرة كل ثانية لاسترداد الحالة.

يمكن أيضًا استخدام تطبيق Virtual Device Controller لاسترداد رمز الاستجابة السريعة كجزء من عملية تشغيل الأجهزة. انقر على رمز الاستجابة السريعة بجانب صورة الجهاز لعرض رمز الاستجابة السريعة لهذا الجهاز. يمكنك استخدام رمز الاستجابة السريعة هذا لإضافة عمولة إلى جهازك.

6- تشغيل الجهاز

ملاحظة: لن تنجح هذه الخطوة إلا إذا سبق لك إعداد مشروعك في 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 التي يتم توفيرها من خلال رمز استجابة سريعة. يمكنك الحصول على رمز الاستجابة السريعة لجهازك الافتراضي من Virtual Device Controller.

إجراء عملية العمولة

  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 نفسها.

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

7- التحكّم في الجهاز

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

  • باستخدام "مساعد Google"
  • يَتِمُّ الْآنْ اسْتِخْدَامْ تَطْبِيقْ Google Home.
  • استخدام واجهة المستخدم التصويرية للجهاز الافتراضي.

مساعد Google

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

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

تطبيق Google Home

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

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

واجهة المستخدم التصويرية للجهاز الافتراضي

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

8- تهانينا!

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

تعلّمت في هذا الدرس التطبيقي حول الترميز طريقة تنفيذ ما يلي:

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

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