تنبيه: سيتم طرح برامج معاينة المطوّرين الجديدة قريبًا. يمكنك تقديم طلب من هنا كُن من أوائل الأشخاص الذين يجرّبون الأدوات الجديدة ويقدّمون الملاحظات.

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

1- المقدمة

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

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

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

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

المتطلبات

  • الموزع، وهو أي جهاز من أجهزة Google Nest يتوافق مع Matter، مثل Nest Hub (الجيل الثاني). يمكنك شراء مركز من Google Store أو من بائع التجزئة المفضّل لديك.
  • آلة Linux تعمل بنظام التشغيل X11.
  • Docker.
  • معرفة أساسية بنظام التشغيل Linux.

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

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

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

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

تفترض هذه التعليمات أيضًا أن جهاز 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 Window System بتلقي اتصالات من المضيف المحلي على المنفذ 1000، مما يسمح باستخدام واجهة مستخدم تصويرية.
  • يشغّل docker run … image الصورة المحددة، ويسحبها من قاعدة بيانات المسجّلين في Docker إذا لزم الأمر.
  • يسمح --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 في ~/connectedhomeip. لا يلزم إجراء خطوات إضافية لإعداد المسائل القانونية.

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

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

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

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

يمكنك البدء بالانتقال إلى Google Home Developer Console:

  1. في صفحة إدارة المشاريع، انقر على إنشاء مشروع.
    مركز مطوّري برامج Google Home
  2. في صفحة البدء، انقر على إنشاء مشروع.

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

4- إنشاء جهاز

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

الرئيس هما:

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

انتقِل إلى مجلد الأمثلة على 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 الافتراضي بحيث يمكن للمكونات الأخرى (مثل GUI) الاتصال بالجهاز لضبط سمات نموذج البيانات واستردادها.
  • -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. أداة التحكم بالجهاز الافتراضي

"وحدة التحكّم في الأجهزة الافتراضية" هي تطبيق مستقل يوفّر واجهة مستخدم تصويرية للتحكّم في حالات أجهزة Matter الافتراضية وعرضها. ويستخدم برنامج RPC للتواصل مع أجهزة Matter المتصلة ببيئة التطوير.

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

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

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

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

تأتي وحدة التحكم في الأجهزة الافتراضية مثبتة مسبقًا في حاوية Ubuntu LTS 20.04 Docker.

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

إنشاء مثيل الجلسة الطرفية الثانية:

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

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

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

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

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

يرسل التطبيق طلبات إلى خادم RPC للجهاز أثناء إجراء تغييرات على تطبيق Virtual Controller، ويبحث عن خادم RPC مرة واحدة في الثانية لاسترداد الحالة.

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

رمز الاستجابة السريعة

يمكنك استخدام رمز الاستجابة السريعة هذا لتنفيذ إجراءات على جهازك.

6- تكليف الجهاز

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

Nest Hub

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

ارجع إلى هذه القائمة لمعرفة المراكز المتوافقة مع Matter.

قبل بدء عملية التكليف، تحقق للتأكد مما يلي:

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

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

وتحتاج عملية التكليف إلى معلومات إعداد 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 نفسها.

تعذّر التفويض بعد "مسح الجهاز" لفترة طويلة

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.

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