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

۱. مقدمه

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

برای کسب اطلاعات بیشتر در مورد Matter، به مرکز توسعه‌دهندگان Google Home یا وب‌سایت Connectivity Standards Alliance مراجعه کنید.

آنچه یاد خواهید گرفت

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

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

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

۲. محیط خود را آماده کنید

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

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

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

محیط توسعه را تنظیم کنید

1. موتور داکر را نصب کنید (از داکر دسکتاپ استفاده نکنید).
   file_download داکر
2. SDK مربوط به Matter را کلون کنید، به کامیتی که در ادامه استفاده می‌کنیم توجه کنید.

   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 اجازه می‌دهد تا اتصالات را از میزبان محلی روی پورت ۱۰۰۰ دریافت کند، بنابراین امکان استفاده از رابط کاربری گرافیکی را فراهم می‌کند.
• docker run … image تصویر داده شده را اجرا می‌کند و در صورت لزوم آن را از رجیستری داکر دریافت می‌کند.
• --ipc=host به داکر اجازه می‌دهد تا فضای نام ارتباط بین پردازشی را با دستگاه میزبان شما به اشتراک بگذارد.
• --net=host به داکر اجازه می‌دهد تا از پشته شبکه میزبان درون کانتینر استفاده کند، که برای عبور ترافیک mDNS از میزبان به کانتینر و اشتراک‌گذاری نمایشگر X11 میزبان ضروری است.
• -e DISPLAY $DISPLAY را به میزبان صادر می‌کند و دسترسی به رابط گرافیکی سیستم شما را فراهم می‌کند. این برای اجرای ابزار ZAP هنگام ویرایش خوشه‌های Matter لازم است.
• -it به جای یک فرآیند پس‌زمینه، داکر را با یک ترمینال تعاملی (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

یا با استفاده از دستور زیر یک جلسه روت (root session) ایجاد کنید:

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

تنظیمات اولیه Matter

مقداردهی اولیه SDK

کیت توسعه نرم‌افزار Matter را راه‌اندازی کنید. تکمیل این عملیات چند دقیقه طول خواهد کشید.

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

SDK مربوط به Matter شما اکنون مقداردهی اولیه شده است. برای مقداردهی مجدد سریع محیط در آینده، دستور زیر را اجرا کنید:

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

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

پیش از این، ما با استفاده از bind mount از داخل کانتینر به فایل‌های روی دستگاه میزبان شما دسترسی پیدا کردیم. همچنین می‌توانید برای دسترسی از طریق میزبان، فایل‌ها را از داخل کانتینر در دایرکتوری mount شده بنویسید.

به طور کلی، با اجرای کانتینر خود با آرگومان اضافی --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)

یک بخش ترمینال دیگر روی میزبان کانتینر باز کنید و دایرکتوری کاری را روی دایرکتوری که توسط کانتینر نصب شده است تنظیم کنید.

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

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

۳. کنسول توسعه‌دهندگان گوگل هوم

کنسول توسعه‌دهندگان گوگل هوم، یک برنامه تحت وب است که در آن می‌توانید ادغام‌های Matter خود را با گوگل هوم مدیریت کنید.

هر دستگاه Matter که گواهینامه Connectivity Standards Alliance (Alliance) Matter را گذرانده باشد، در اکوسیستم Google Home کار می‌کند. دستگاه‌های در حال توسعه که گواهینامه دریافت نکرده‌اند، می‌توانند تحت شرایط خاصی در اکوسیستم Google Home راه‌اندازی شوند - برای اطلاعات بیشتر به محدودیت‌های جفت‌سازی مراجعه کنید.

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

با رفتن به کنسول توسعه‌دهندگان گوگل هوم شروع کنید:

به کنسول توسعه‌دهندگان گوگل هوم بروید

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

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

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

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

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

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

دستگاه را اجرا کنید

نرم‌افزار Matter از پورت ۵۵۴۰ TCP/UDP استفاده می‌کند ، بنابراین اگر فایروال روی رایانه شما فعال است، آن را خاموش کنید یا اجازه دهید اتصالات TCP/UDP ورودی روی پورت ۵۵۴۰ برقرار شوند.

دستگاه مجازی را در کانتینر با دستور زیر اجرا کنید:

$ ./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*

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

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

هاب نست

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

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

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

• هاب شما با همان حساب گوگلی که برای ورود به کنسول گوگل هوم استفاده کرده‌اید، جفت شده است.
• هاب شما به همان شبکه وای‌فای متصل است که رایانه‌ای که برای اجرای دستگاه Virtual Matter خود از آن استفاده می‌کنید، به آن متصل است.
• هاب شما در همان ساختاری است که در برنامه Google Home خود استفاده می‌کنید. ("خانه" در نمودار Google Home نشان دهنده ساختار شماست).

دریافت کد QR

فرآیند راه‌اندازی به اطلاعات مربوط به ورود به Matter که از طریق یک کد QR ارائه می‌شود، نیاز دارد. خروجی کنسول برنامه Matter را بررسی کنید که حاوی پیوندی برای کد QR مربوط به راه‌اندازی است.

انجام عملیات کمیسیون

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

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

عیب‌یابی

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

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

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

• تأیید کنید که فایروال رایانه شما خاموش است و دستگاه مجازی را اجرا می‌کنید.
• هرگونه رابط شبکه فیزیکی (اترنت) را قطع کنید تا مطمئن شوید که رایانه شما منحصراً از Wi-Fi استفاده می‌کند.

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

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

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

دستیار گوگل

از دستیار گوگل روی گوشی یا هاب خود برای تغییر وضعیت دستگاه از طریق دستورات صوتی استفاده کنید، مثلاً بگویید «هی گوگل، چراغ‌های من را روشن کن».

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

برنامه گوگل هوم

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

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

۷. تبریک می‌گویم!

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

در این آزمایشگاه کد یاد گرفتید که چگونه:

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

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

• مقدمات Matter در مرکز توسعه‌دهندگان گوگل هوم، جایی که اصول اولیه مفاهیم Matter را خواهید آموخت.
• مشخصات ماده، کتابخانه دستگاه ماده و کتابخانه خوشه کاربرد ماده، منتشر شده توسط اتحاد استانداردهای اتصال .
• مخزن گیت‌هاب Matter .