建立 Matter 虛擬裝置

1. 簡介

Matter 是一種連線通訊協定，可為智慧型裝置開發帶來令人期待的機會。在本程式碼研究室中，您將使用 Matter SDK 的資源建構第一個 Matter 裝置。

如要瞭解 Matter，請前往 Google Home Developer Center或 Connectivity Standards Alliance 網站。

課程內容

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

軟硬體需求

  • 中樞裝置，也就是支援 Matter 的 Google Nest 裝置，例如 Nest Hub (第 2 代)。
  • 執行 X11 視窗系統的 Linux 機器。
  • Docker。
  • Git。
  • 具備 Linux 基礎知識。
    • 請注意，本程式碼研究室中所有指令都假設使用 BASH 介面。

2. 設定環境

檢查硬體

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

此外，這些操作說明假設您的 Linux 電腦正在執行 X11 視窗系統。如果 Linux 電腦執行 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. 使用 SDK 的公開 CI 映像檔執行建構容器，並從這個容器內執行新建立的虛擬裝置。找到與 SDK 版本相符的圖片，如下所示：
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    如果您使用相同的提交內容，應該會看到 ghcr.io/project-chip/chip-build:66「First, forward xhost ports so we can later use UI applications:」(首先，轉送 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 Window System 接收本機主機在通訊埠 1000 上的連線，因此允許使用圖形使用者介面。
  • docker run … image 會執行指定的映像檔，並視需要從 Docker 登錄檔提取該映像檔。
  • --ipc=host 可讓 Docker 與主體機器共用處理序間通訊命名空間。
  • --net=host 可讓 Docker 在容器內使用主機的網路堆疊，這是將 mDNS 流量從主機傳遞至容器，以及共用主機 X11 螢幕的必要條件。
  • -e DISPLAY 會將 $DISPLAY 匯出至主機，讓主機存取系統圖形介面。編輯 Matter 叢集時，必須具備這個角色才能執行 ZAP 工具。
  • -it 會以互動式終端機 (tty) 執行 Docker，而不是以背景程序執行。
  • --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

初始 Matter 設定

初始化 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 執行容器，將目前的工作目錄掛接到容器的 /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 開發人員控制台是網頁應用程式，您可以在這裡管理與 Google Home 的 Matter 整合。

只要是通過連線標準聯盟 (聯盟) Matter 認證的裝置，都可以在 Google Home 生態系統中運作。在某些情況下，尚未通過認證的開發中裝置可以在 Google Home 生態系統中完成委派程序。詳情請參閱「配對限制」。

建立開發人員專案

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

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

4. 建立裝置

Matter 中的所有範例都位於 Github 存放區的 examples 資料夾中。我們提供多個範例，但本程式碼研究室的重點是 Chef。

Chef 兼具以下兩種身分：

  • 提供終端機介面的範例應用程式，並包裝 examples/shell 應用程式中的功能。
  • 這個指令碼採用「慣例優於設定」原則，封裝開發支援 Matter 裝置所需的幾項常見工作。

前往 Chef 範例資料夾，並建構第一個 Matter 版本：

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

執行 chef.py -h 即可查看 Chef 的幾個選項。我們在此使用的選項如下：

  • -d：定義要使用的裝置類型。在本例中，我們將建立燈光應用程式，並提供開/關和亮度控制選項。
  • -z：叫用 ZAP 工具，產生實作裝置類型的來源檔案。也就是說，根據您選擇的燈具，ZAP 會自動建立程式碼，並納入建構作業中，定義燈具 (資料模型) 和燈具與其他裝置的互動方式 (互動模型)。
  • -b：建構作業。
  • -r：[選用] 在虛擬 Matter 裝置上啟用 RPC 伺服器，讓其他元件 (例如 GUI) 與裝置通訊，以設定及擷取資料模型屬性。
  • -t linux：目標平台。支援的平台包括 linux、nrfconnect 和 esp32。您可以執行 ./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. 委任裝置

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

Nest Hub

你必須使用中樞裝置，才能在 Matter 網狀架構上佈建裝置。這是指支援 Matter 的 Google Nest 裝置，例如 Nest Hub (第 2 代)，可做為支援 Thread 裝置的邊界路由器，以及智慧住宅意圖的本機履行路徑。

請參閱這份清單，瞭解哪些中樞裝置支援 Matter。

開始委派程序前，請先確認下列事項：

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

取得 QR code

在委派程序中，您需要透過 QR code 提供 Matter 上線資訊。檢查 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 組合。

「掃描裝置」後長時間無法完成委派程序

6. 控制裝置

支援 Matter 的裝置完成委派程序並在 Google Home 應用程式中顯示為燈泡後，即可透過不同方式測試裝置控制功能：

  • 使用 Google 助理。
  • 使用 Google Home 應用程式。

Google 助理

在手機或中控螢幕上使用 Google 助理，透過語音指令切換裝置狀態，例如說出「Ok Google，切換燈光」。

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

Google Home 應用程式

輕觸 Google Home 應用程式中燈泡圖示旁的「開啟」和「關閉」標籤。

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

7. 恭喜！

你已成功建立第一個 Matter 裝置。太棒了！

在本程式碼研究室中，您學會如何：

  • 安裝 Matter 開發環境。
  • 建構並執行 Matter 虛擬裝置。
  • 透過 Google Home 委派及控制虛擬裝置。

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

  • Google Home Developer Center 的「Matter 基礎知識」一文，瞭解 Matter 概念的基本知識。
  • 連線標準聯盟 (Connectivity Standards Alliance) 發布的 Matter 規格、Matter 裝置程式庫和 Matter 應用程式叢集程式庫。
  • Matter GitHub 存放區。