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

1. مقدمه

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

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

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

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

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

  • هاب، که هر دستگاه Google Nest است که از Matter پشتیبانی می‌کند ، مانند Nest Hub (نسل دوم).
  • یک ماشین لینوکس که سیستم پنجره X11 را اجرا می کند.
  • داکر.
  • Git.
  • دانش اولیه لینوکس.
    • توجه داشته باشید که پوسته فرضی برای همه دستورات در این کد لبه BASH است.

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

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

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

همچنین، این دستورالعمل‌ها فرض می‌کنند که دستگاه لینوکس شما از سیستم پنجره X11 استفاده می‌کند. اگر دستگاه لینوکس شما 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
    اگر از همان commit استفاده می کنید، باید ابتدا ghcr.io/project-chip/chip-build:66 را ببینید، پورت های xhost را فوروارد کنید تا بعداً بتوانیم از برنامه های UI استفاده کنیم:
    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 به داکر اجازه می دهد تا فضای نام ارتباط بین پردازشی را با دستگاه میزبان شما به اشتراک بگذارد.
  • --net=host به داکر اجازه می دهد تا از پشته شبکه میزبان در داخل کانتینر استفاده کند، که برای انتقال ترافیک mDNS از میزبان به کانتینر و اشتراک گذاری نمایشگر میزبان X11 لازم است.
  • -e DISPLAY $DISPLAY را به میزبان صادر می کند و دسترسی به رابط گرافیکی سیستم شما را فراهم می کند. این برای اجرای ابزار ZAP هنگام ویرایش خوشه‌های ماده مورد نیاز است.
  • Docker را با یک ترمینال تعاملی (tty) به جای فرآیند پس‌زمینه -it می‌کند.
  • --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 را راه اندازی کنید

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 bind mounts استفاده کنید تا فهرست کاری فعلی خود را در کانتینر در /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. دستگاه را راه اندازی کنید

توجه : این مرحله تنها در صورتی موفق خواهد شد که پروژه خود را قبلاً در کنسول برنامه‌نویس 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 نیاز دارد. خروجی کنسول برنامه Matter را بررسی کنید که حاوی پیوندی برای کد 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 ندارید.

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

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

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

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

دستیار گوگل

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

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

برنامه Google Home

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

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

7. تبریک می گویم!

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

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

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

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