建構 Matter 虛擬裝置

1. 簡介

Matter 是連線通訊協定,可為智慧型裝置帶來絕佳機會。在這個程式碼研究室中,您將使用預先設定的 Docker 映像檔中提供的 SDK 和依附元件,建構第一個 Matter 裝置。

如要進一步瞭解 Matter,請造訪 Google Home 開發人員中心連線標準聯盟網站

課程內容

  • 如何設定 Matter 建構環境
  • 如何打造可在電腦上執行的虛擬 Matter 裝置
  • 如何使用 Google Home 調試及控制虛擬 Matter 裝置

軟硬體需求

2. 設定環境

您將在 Linux 主機機器上使用先前設定的 Docker 容器。這個容器包含建構和執行 Matter 虛擬裝置的所有必要依附元件。

檢查硬體

這個 Docker 安裝項目不支援 Windows 和 macOS 電腦。你可以在 macOS 上手動安裝及建構 Matter

此外,這些指示假設 Linux 機器正在執行 X11 視窗系統。如果 Linux 機器執行的是 Wayland,請確認已安裝 X.Org

設定 Docker

  1. 安裝 Docker Engine (不要使用 Docker Desktop)。
  2. 從 Docker Hub 提取 Docker 映像檔。在終端機視窗中執行:
    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 Registry 中提取映像檔。
  • --ipc=host 可讓 Docker 與主機機器共用處理序間通訊命名空間。
  • --net=host 允許 Docker 在容器中使用主機的網路堆疊,這是為了將 mDNS 流量從主機傳送至容器,以及分享主機 X11 顯示畫面的必要條件。
  • -e DISPLAY 會將 $DISPLAY 匯出至主機,以便存取您的系統圖形介面。您必須在編輯 Matter 叢集時執行 ZAP 工具
  • -it 會透過互動終端機 (tty) 執行 Docker,而非做為背景程序。

您也可以選擇執行第二個終端機工作階段執行個體:

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。

$ 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 開發人員控制台是網頁應用程式,可以用來管理 Matter 與 Google Home 的整合作業。

凡是通過連線標準聯盟 (Alliance) Matter 認證的 Matter 裝置,都能在 Google Home 生態系統中運作。處於開發階段的裝置如未經過認證,可於特定條件下在 Google Home 生態系統中委託開發。詳情請參閱配對限制

建立開發人員專案

首先請前往 Google Home 開發人員控制台:

  1. 按一下 [Create Project]
  2. 輸入不重複的專案名稱,然後按一下「Create project」(建立專案) 建立新專案對話方塊
  3. 按一下「+ 新增整合」,前往「Matter 資源」畫面,即可查看 Matter 開發說明文件及查看部分工具。
  4. 準備好繼續進行時,請按一下「Next:開發」,系統隨即會顯示「Matter 檢查清單」頁面。
  5. 點選「下一步:設定」
  6. 在「設定」頁面中輸入您的「產品名稱」。
  7. 按一下「選取裝置類型」,然後從下拉式選單中選取裝置類型 (本例中為 Light)。
  8. 在「供應商 ID (VID)」中選取「Test VID」,然後從「測試 VID」下拉式選單中選取「0xFFF1」。在產品 ID (PID) 中輸入 0x8000,然後按一下「儲存並繼續」,接著在下一頁點選「儲存」。請使用這些正確的 VID/PID 值,後續的程式碼研究室步驟取決於這些值。
    設定專案
  9. 接著,「Matter 整合」下方會顯示整合項目。
  10. 請重新啟動中樞,確保裝置能接收最新的 Matter 整合專案設定。如果之後要變更 VID 或 PID,您也必須在儲存專案後重新啟動,變更才會生效。如需重新啟動的逐步操作說明,請參閱「重新啟動 Google Nest 或 Google Wifi 裝置」一文。

4. 打造裝置

您可以在 GitHub 存放區examples 資料夾中找到 Matter 中的所有範例。有幾個範例可供使用,但本程式碼研究室著重於主廚

Chef 同時為:

  • 範例應用程式提供終端機介面,也可在 examples/shell 應用程式中找到包裝功能。
  • 使用慣例上設定原則的指令碼,封裝了開發支援 Matter 的裝置所需的多項常見工作。

前往 Chef 範例資料夾,並建立第一個 Matter 版本:

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

Chef 提供幾個選項,只要執行 chef.py -h 即可查看。我們使用的選項如下:

  • -d:定義要使用的裝置類型。在這個範例中,我們將建立一個有開啟/關閉和音量控制項的照明應用程式。
  • -z:叫用 ZAP 工具,產生實作裝置類型的來源檔案。也就是說,根據您選擇的光源,ZAP 會自動建立程式碼,以便整合至建構中定義光源 (資料模型) 以及與其他裝置互動的方式 (互動模型)。
  • -b:版本。
  • -r:[選用] 在虛擬 Matter 裝置上啟用 RPC 伺服器,讓其他元件 (例如 GUI) 能與裝置進行通訊,以便設定及擷取資料模型屬性。
  • -t linux:目標平台。支援平台包括 linuxnrfconnectesp32。您可以執行 ./chef.py -h 查看所有可用指令和支援的目標平台。linux 用於虛擬 Matter 裝置。

執行裝置

Matter 使用 TCP/UDP 通訊埠 5540,因此如果您有在電腦上執行的防火牆,請將其關閉,或是允許透過通訊埠 5540 的連入 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*

5. 虛擬裝置控制器

虛擬裝置控制器是獨立的應用程式,提供圖形使用者介面,方便您控制及顯示虛擬 Matter 裝置的狀態。這項服務使用 RPC 用戶端與連線至開發環境的 Matter 裝置進行通訊。

虛擬裝置控制器

虛擬裝置控制器能以視覺化方式呈現虛擬裝置。

您可以透過虛擬裝置控制器圖像使用者介面 (GUI) 與虛擬裝置互動。您在 GUI 中所做的變更會影響基礎資料模型。如需支援 Matter 虛擬裝置類型的完整清單,請參閱「支援的裝置」。

安裝虛擬裝置控制器

虛擬裝置控制器已預先安裝在 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

如果您在啟動 Controller 時沒有提供任何引數,則會使用使用 localhost 通訊埠 33000 的網路通訊端選項。控制器可以連線至虛擬裝置後,畫面上會顯示顯示裝置狀態的畫面:

虛擬裝置圖形使用者介面

在 Virtual Controller 應用程式的變更時,應用程式會將要求傳送至裝置的 RPC 伺服器,並每秒輪詢 RPC 伺服器一次以擷取狀態。

此外,虛擬裝置控制器應用程式也能用來擷取 QR code,藉此進行裝置調適流程。按一下裝置圖片旁邊的 QR code 圖示,即可顯示這部裝置的 QR code。請使用這個 QR code 調試裝置。

6. 將裝置調派給

注意:您必須先在 Google Home 開發人員控制台中設定專案,這個步驟才會成功。

Nest Hub

裝置必須使用中樞裝置,才能進行 Matter 織物的調試。這款 Google Nest 裝置 (例如 Nest Hub (第 2 代) 支援 Matter,能同時做為支援 Thread 的裝置的邊界路由器,以及用於轉送智慧型住宅意圖的本機執行要求路徑。

請參閱這份清單,查看哪些中樞支援 Matter。

開始實施調試程序前,請確認下列事項:

  • 你的中樞裝置會與你在 Google Home 控制台中登入的 Google 帳戶配對。
  • 中樞裝置與用來執行虛擬 Matter 裝置的電腦已連上相同的 Wi-Fi 網路。
  • 中樞裝置與你在 Google Home 應用程式中使用的結構相同 (Google Home 圖表中的「房屋」代表住家結構體)。

取得 QR code

調試程序需要透過 QR code 提供的 Matter 新手上路資訊。您可以透過虛擬裝置控制器取得虛擬裝置的 QR code。

執行佣金作業

  1. 開啟 Google Home 應用程式。
  2. 輕觸左上角的「+」
  3. 輕觸「設定裝置」
  4. 輕觸「新裝置」
  5. 選取住家,然後輕觸「下一步」
  6. Google Home 應用程式會掃描你的裝置。如果出現「找到 Matter 裝置...」訊息,請輕觸「是」。如果是其他裝置,請輕觸「設定其他裝置」,然後從裝置清單中選取「Matter 裝置」
  7. 將相機對準裝置的 QR code 或網站產生的 QR code。
  8. 按照 Google Home 應用程式流程的說明繼續配對程序。

完成上述步驟後,Matter 虛擬裝置應能順利啟動,而且 Google Home 應用程式中會顯示為新圖示。

Google Home 應用程式中已配對的燈泡

疑難排解

調解失敗,出現「連線問題」或「無法聯絡 Google」錯誤訊息

  • 確認已在 Google Home 控制台中用正確的 VID/PID 組合 建立專案,且沒有任何其他專案使用相同的 VID/PID 組合。

長時間「掃描你的裝置」後無法執行調試

  • 確認電腦的防火牆已關閉,且您正在執行虛擬裝置。
  • 中斷任何實體網路介面 (乙太網路) 的連線,確保電腦僅使用 Wi-Fi 網路。

7. 操控裝置

支援 Matter 的裝置成功執行完畢,並在 Google Home 應用程式中顯示為燈泡後,你就可以使用下列不同方法測試裝置的控制結果:

  • 使用 Google 助理。
  • 使用 Google Home 應用程式。
  • 使用虛擬裝置 GUI。

Google 助理

在手機或中樞裝置上使用 Google 助理切換裝置狀態,例如說出「Ok Google,切換燈具」。

如需更多指令範例,請參閱「使用語音指令控制 Google Home 應用程式」中的「使用語音指令控制智慧住宅裝置」一節。

Google Home 應用程式

在 Google Home 應用程式中顯示的燈泡圖示旁邊,你可以輕觸「開啟」和「關閉」標籤。

詳情請參閱「控制已新增至 Google Home 應用程式的智慧住宅裝置」一文中的「透過 Google Home 應用程式控制裝置」一節。

虛擬裝置 GUI

您可以與虛擬裝置 GUI 互動來變更裝置狀態。無論是透過虛擬裝置控制器、手機上的 Google Home 應用程式或從中樞裝置控管虛擬裝置,這些介面都會反映虛擬裝置目前的狀態。

8. 恭喜!

您已成功建立第一個 Matter 裝置。太棒了!

在本程式碼研究室中,您瞭解如何:

  • 使用預先封裝的 Docker 映像檔安裝 Matter 開發環境。
  • 建構並執行 Matter 虛擬裝置。
  • 透過 Google Home 控制及控制虛擬裝置。

如要進一步瞭解 Matter,請參閱下列參考資料: