یک دستگاه مجازی Matter بسازید

1. معرفی

Matter یک پروتکل اتصال است که فرصت های هیجان انگیزی را برای توسعه دستگاه های هوشمند به ارمغان می آورد. در این کد لبه، شما اولین دستگاه Matter خود را با استفاده از SDK و وابستگی های ارائه شده برای شما در یک تصویر از پیش پیکربندی شده Docker می سازید.

برای آشنایی با Matter، از مرکز توسعه‌دهنده Google Home یا وب‌سایت اتحاد استانداردهای اتصال دیدن کنید.

چیزی که یاد خواهید گرفت

  • نحوه راه اندازی یک محیط ساخت Matter
  • چگونه یک دستگاه مجازی Matter بسازیم که روی کامپیوتر شما اجرا شود
  • نحوه راه اندازی و کنترل دستگاه مجازی Matter با Google Home

آنچه شما نیاز دارید

2. محیط خود را تنظیم کنید

ما از یک کانتینر Docker که قبلاً پیکربندی شده است در دستگاه میزبان لینوکس استفاده خواهیم کرد. این کانتینر شامل تمام وابستگی های لازم برای ساخت و راه اندازی یک دستگاه مجازی Matter است.

سخت افزار خود را بررسی کنید

رایانه‌های Windows و macOS توسط این نصب Docker پشتیبانی نمی‌شوند. می توانید Matter را به صورت دستی در macOS نصب و بسازید .

همچنین، این دستورالعمل‌ها فرض می‌کنند که دستگاه لینوکس شما از سیستم پنجره X11 استفاده می‌کند. اگر دستگاه لینوکس شما Wayland را اجرا می کند، مطمئن شوید که X.Org نیز نصب شده باشد.

Docker را راه اندازی کنید

  1. Docker Engine را نصب کنید (از Docker Desktop استفاده نکنید).
  2. تصویر داکر را از داکر هاب بکشید. در یک پنجره ترمینال، اجرا کنید:
    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 تصویر داده شده را اجرا می کند و در صورت لزوم آن را از رجیستری Docker خارج می کند.
  • --ipc=host به داکر اجازه می دهد تا فضای نام ارتباط بین پردازشی را با دستگاه میزبان شما به اشتراک بگذارد.
  • --net=host به داکر اجازه می دهد تا از پشته شبکه میزبان در داخل کانتینر استفاده کند، که برای انتقال ترافیک mDNS از میزبان به کانتینر و اشتراک گذاری نمایشگر میزبان X11 لازم است.
  • -e DISPLAY $DISPLAY به میزبان صادر می کند و دسترسی به رابط گرافیکی سیستم شما را فراهم می کند. این برای اجرای ابزار ZAP هنگام ویرایش خوشه‌های ماده مورد نیاز است.
  • Docker -it با یک ترمینال تعاملی (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 قرار دارد. هیچ مرحله اضافی تنظیم Matter مورد نیاز نیست.

فایل ها را بین میزبان و کانتینر به اشتراک بگذارید

برای دسترسی به فایل‌های موجود در دستگاه میزبان خود از داخل کانتینر، می‌توانید از یک اتصال mount استفاده کنید. همچنین می‌توانید برای دسترسی آسان از میزبان، فایل‌هایی را از داخل کانتینر در فهرست نصب شده بنویسید.

ظرف خود را با آرگومان اضافی --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 Standards Connectivity Alliance (Alliance) را گذرانده باشد در اکوسیستم Google Home کار می کند. دستگاه‌های در حال توسعه که تأیید نشده‌اند را می‌توان تحت شرایط خاصی در اکوسیستم Google Home راه‌اندازی کرد - برای اطلاعات بیشتر به محدودیت‌های مرتبط‌سازی مراجعه کنید.

یک پروژه توسعه دهنده ایجاد کنید

با رفتن به Google Home Developer Console شروع کنید:

  1. روی ایجاد پروژه کلیک کنید.
  2. یک نام پروژه منحصر به فرد را وارد کنید و سپس روی ایجاد پروژه کلیک کنید.گفتگوی پروژه جدید ایجاد کنید
  3. روی + افزودن ادغام کلیک کنید، که شما را به صفحه منابع Matter می برد، جایی که می توانید اسناد توسعه Matter را مشاهده کنید و در مورد برخی از ابزارها مطالعه کنید.
  4. وقتی برای ادامه آماده شدید، روی Next: Develop کلیک کنید، که صفحه چک لیست Matter را نمایش می دهد.
  5. روی Next کلیک کنید: Setup
  6. در صفحه راه اندازی ، نام محصول خود را وارد کنید.
  7. روی انتخاب نوع دستگاه کلیک کنید و نوع دستگاه را از منوی کشویی انتخاب کنید (در این مورد، Light ).
  8. در شناسه فروشنده (VID)، Test VID را انتخاب کنید و 0xFFF1 را از منوی کشویی Test VID انتخاب کنید. در شناسه محصول (PID)، 0x8000 را وارد کنید و روی ذخیره و ادامه کلیک کنید و سپس در صفحه زیر روی ذخیره کلیک کنید. از این مقادیر دقیق VID/PID استفاده کنید، مراحل بعدی Codelab به آنها بستگی دارد.
    راه اندازی یک پروژه
  9. اکنون ادغام خود را در قسمت Matter integrations خواهید دید.
  10. هاب خود را مجددا راه اندازی کنید تا مطمئن شوید که آخرین پیکربندی پروژه یکپارچه سازی Matter را دریافت می کند. اگر بعداً مجبور به تغییر VID یا PID شدید، پس از ذخیره پروژه نیز باید راه‌اندازی مجدد کنید تا تغییر اعمال شود. برای دستورالعمل‌های گام به گام راه‌اندازی مجدد، به راه‌اندازی مجدد دستگاه‌های Google Nest یا Google Wifi مراجعه کنید.

4. یک دستگاه بسازید

تمام مثال‌های موجود در Matter در پوشه examples در مخزن Github یافت می‌شوند. چندین نمونه موجود است، اما تمرکز ما روی این کد لبه روی سرآشپز است.

آشپز هر دو است:

  • یک برنامه نمونه که یک رابط ترمینال را فراهم می کند، ویژگی های بسته بندی نیز در برنامه examples/shell یافت می شود.
  • اسکریپتی که اصل پیکربندی قراردادی بیش از حد را در بر می گیرد تا چندین کار رایج لازم برای توسعه یک دستگاه دارای ماده فعال را در بر بگیرد.

به پوشه Chef example بروید و اولین ساخت 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. کنترل کننده دستگاه مجازی

Virtual Device Controller یک برنامه مستقل است که یک رابط کاربری گرافیکی برای کنترل و نمایش وضعیت دستگاه های Matter مجازی شما ارائه می دهد. از یک کلاینت RPC برای برقراری ارتباط با دستگاه های Matter متصل به محیط توسعه شما استفاده می کند.

کنترلر دستگاه مجازی

کنترلر دستگاه مجازی یک نمایش بصری از دستگاه مجازی شما ارائه می دهد.

شما می توانید از طریق رابط کاربری گرافیکی Virtual Device Controller (GUI) با دستگاه مجازی تعامل داشته باشید. تغییرات شما در رابط کاربری گرافیکی بر مدل داده های اساسی تأثیر می گذارد. برای لیست کامل انواع دستگاه های مجازی پشتیبانی شده Matter به دستگاه های پشتیبانی شده مراجعه کنید.

کنترلر دستگاه مجازی را نصب کنید

Virtual Device Controller از قبل روی ظرف Docker Ubuntu LTS 20.04 نصب شده است.

کنترلر دستگاه مجازی را اجرا کنید

نمونه جلسه ترمینال دوم را ایجاد کنید:

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

کنترل کننده دستگاه مجازی را با ارائه سوکت شبکه ای که برای برقراری ارتباط با دستگاه مجازی استفاده می شود، راه اندازی کنید:

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

اگر کنترلر را بدون ارائه هیچ آرگومان راه اندازی کنید، به طور پیش فرض به گزینه سوکت شبکه با استفاده از پورت لوکال هاست 33000 تبدیل می شود. هنگامی که کنترلر بتواند به دستگاه مجازی متصل شود، صفحه ای را نشان می دهد که وضعیت دستگاه شما را نشان می دهد:

رابط کاربری گرافیکی دستگاه مجازی

با ایجاد تغییرات در برنامه Virtual Controller، برنامه درخواست‌ها را به سرور RPC دستگاه ارسال می‌کند و یک بار در ثانیه از سرور RPC برای بازیابی وضعیت نظرسنجی می‌کند.

برنامه Virtual Device Controller همچنین می تواند برای بازیابی کد QR به عنوان بخشی از جریان راه اندازی دستگاه شما استفاده شود. روی نماد کد QR در کنار تصویر دستگاه کلیک کنید تا کد QR این دستگاه نمایش داده شود. از این کد QR برای راه اندازی دستگاه خود استفاده کنید.

6. دستگاه را راه اندازی کنید

توجه : این مرحله تنها در صورتی موفق خواهد شد که پروژه خود را قبلاً در کنسول برنامه‌نویس Google Home راه‌اندازی کرده باشید.

Nest Hub

برای راه اندازی دستگاه شما روی پارچه Matter به هاب نیاز است. این یک دستگاه Google Nest است، مانند Nest Hub (نسل دوم)، که از Matter پشتیبانی می‌کند و هم به‌عنوان یک مسیریاب مرزی برای دستگاه‌های دارای Thread و هم به‌عنوان مسیر تکمیل محلی برای مسیریابی اهداف خانه هوشمند عمل می‌کند.

به این لیست مراجعه کنید تا ببینید کدام هاب از Matter پشتیبانی می کند.

قبل از شروع فرآیند راه اندازی، بررسی کنید که:

  • هاب شما با همان حساب Google که برای ورود به سیستم در کنسول خانگی Google استفاده کرده بودید جفت شده است.
  • هاب شما در همان شبکه Wi-Fi با رایانه ای است که برای اجرای Virtual Matter Device خود استفاده می کنید.
  • هاب شما در همان ساختاری است که در برنامه Google Home خود استفاده می کنید. («خانه» در نمودار Google Home نشان دهنده ساختار شماست).

یک کد QR دریافت کنید

فرآیند راه‌اندازی به اطلاعات مربوط به ورود ماده از طریق کد QR نیاز دارد. می توانید کد QR دستگاه مجازی خود را از کنترلر دستگاه مجازی دریافت کنید.

عملیات کمیسیون را انجام دهید

  1. برنامه Google Home را باز کنید.
  2. روی + در گوشه سمت چپ بالا ضربه بزنید.
  3. روی تنظیم دستگاه ضربه بزنید.
  4. روی دستگاه جدید ضربه بزنید.
  5. خانه خود را انتخاب کنید و روی Next ضربه بزنید.
  6. برنامه Google Home دستگاه شما را اسکن می کند. اگر با پیام "Matter Device found..." از شما خواسته شد، روی "بله" ضربه بزنید. در غیر این صورت، روی Set up a other device ضربه بزنید، سپس Matter device را از لیست دستگاه ها انتخاب کنید.
  7. دوربین خود را به سمت کد QR دستگاه یا کد QR ایجاد شده توسط وب سایت بگیرید.
  8. فرآیند جفت‌سازی را همانطور که در جریان برنامه Google Home نشان داده شده است، ادامه دهید.

پس از تکمیل این مراحل، دستگاه مجازی Matter باید با موفقیت راه اندازی شود، و باید به عنوان یک نماد جدید در برنامه Google Home شما ظاهر شود.

لامپ جفت شده در برنامه Google Home

عیب یابی

راه‌اندازی با پیام‌های خطای «مشکل اتصال» یا «نمی‌توان با Google تماس گرفت» انجام نمی‌شود

  • مطمئن شوید که پروژه ای با ترکیب صحیح VID/PID در کنسول خانگی Google ایجاد کرده اید و پروژه های دیگری با استفاده از همان ترکیب VID/PID ندارید.

پس از "اسکن کردن دستگاه" برای مدت طولانی، راه اندازی با شکست مواجه می شود

7. دستگاه را کنترل کنید

هنگامی که دستگاه دارای Matter با موفقیت راه اندازی شد و در برنامه Google Home به عنوان یک لامپ ظاهر شد، می توانید کنترل دستگاه را با روش های مختلف آزمایش کنید:

  • با استفاده از دستیار گوگل
  • با استفاده از برنامه Google Home.
  • استفاده از رابط کاربری گرافیکی دستگاه مجازی

دستیار گوگل

از دستیار Google در تلفن یا هاب خود برای تغییر وضعیت دستگاه از دستورات صوتی، مانند گفتن «Hey Google, toggle my lights» استفاده کنید.

برای نمونه‌های بیشتر دستورات، به بخش کنترل دستگاه‌های خانه هوشمند با فرمان‌های صوتی در کنترل دستگاه‌های خانه هوشمند افزوده شده به برنامه Google Home مراجعه کنید.

برنامه Google Home

می توانید روی برچسب های روشن و خاموش در کنار نماد لامپ نشان داده شده در برنامه Google Home ضربه بزنید.

برای اطلاعات بیشتر، به بخش «کنترل دستگاه‌ها» با بخش برنامه Google Home در «کنترل دستگاه‌های خانه هوشمند» که به برنامه Google Home اضافه شده است، مراجعه کنید.

رابط کاربری گرافیکی دستگاه مجازی

برای تغییر وضعیت دستگاه می توانید با رابط کاربری گرافیکی دستگاه مجازی تعامل داشته باشید. فرقی نمی‌کند دستگاه مجازی را با کنترلر دستگاه مجازی، برنامه Google Home روی تلفن خود یا با هاب خود کنترل کنید، همه این رابط‌ها وضعیت فعلی دستگاه مجازی را منعکس می‌کنند.

8. تبریک!

شما با موفقیت اولین دستگاه Matter خود را ایجاد کردید. عالی!

در این کد لبه یاد گرفتید که چگونه:

  • یک محیط توسعه Matter را با استفاده از یک تصویر Docker از پیش بسته بندی شده نصب کنید.
  • یک دستگاه مجازی Matter بسازید و اجرا کنید.
  • دستگاه مجازی خود را از Google Home اداره و کنترل کنید.

برای کسب اطلاعات بیشتر در مورد ماده، این منابع را بررسی کنید: