建構 Matter 虛擬裝置

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

1. 簡介

Matter 是一種連線通訊協定，為智慧型裝置開發作業帶來驚人的機會。在本程式碼研究室中，您將使用預先設定 Docker 映像檔中提供的 SDK 和依附元件，來建構第一個 Matter 裝置。

如要瞭解 Matter 相關資訊，請造訪 Google Home 開發人員中心或 Connectivity Standards Alliance 網站。

課程內容

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

軟硬體需求

  • 集線器，支援任何 Matter 的 Google Nest 裝置，例如 Nest Hub (第 2 代)。您可以前往 Google 商店或偏好的零售商購買中樞。
  • 執行 X11 窗型系統的 Linux 機器。
  • Docker。
  • 對 Linux 有基本瞭解。

2. 設定環境

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

檢查硬體

這個 Docker 安裝目前不支援 Windows 和 MacOS 電腦。您可以在 MacOS 或 Windows 中手動安裝及建立 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 登錄檔提取該映像檔。
  • --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 設定

終端機開啟後會位於 ~/connectedhomeip 的 Matter 複製存放區。您不需要採取其他 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 的整合作業。

凡是通過 CSA Matter 認證的 Matter 裝置，都能在 Google Home 生態系統中運作。

建立開發人員專案

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

  1. 在「管理專案」畫面中，按一下 [建立專案]。
    Google Home 開發人員中心
  2. 在「開始使用」畫面中，按一下「建立專案」。

  1. 輸入不重複的專案名稱，然後按一下 [Create new project] (建立新專案)。 [建立新專案] 對話方塊
  2. 按一下「+ 新增 Matter 整合」，系統會帶您前往「Matter 資源」畫面，供您查看 Matter 開發說明文件並參閱部分工具。
  3. 準備就緒時，請點選 [下一步：開發]，這裡會顯示「案件檢查清單」畫面。
  4. 點選 [下一步：設定]
  5. 在「設定」畫面中輸入您的產品名稱。
  6. 點選 [選取裝置類型]，然後從下拉式選單中選取裝置類型 (在本例中為 Light)。
  7. 在供應商 ID (VID) 中，依序選取 [測試 VID] 和 [測試 VID] 下拉式選單的 0xFFF1。在產品 ID (PID) 中輸入 0x8000，然後點擊 [儲存並繼續]，接著點選下一頁的 [儲存]。
    設定專案
  8. 現在，你會在 Matter 整合底下看到一個 Matter 裝置。Matter 整合
  9. 重新啟動 Hub，確保接收 Matter 整合專案的最新設定。如果日後需要變更 VID 或 PID，您也必須在儲存專案後重新啟動，變更才會生效。

4. 建立裝置

您可以在 GitHub 存放區的 examples 資料夾中找到 Matter 的所有範例。目前有多種範例，但本程式碼研究室著重於主廚。

方塊：

  • 這個範例應用程式提供了終端機介面，以及 examples/shell 應用程式中的包裝功能。
  • 這個指令碼運用了慣例原則設定原則，說明開發支援 Matter 裝置的多項常見工作。

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

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

小廚可透過 chef.py -h 檢視選項。我們在這裡選擇的選項如下：

  • -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. 虛擬裝置控制器

虛擬裝置控制器是一種獨立應用程式，提供圖形使用者介面，可用來控制並顯示虛擬 Matter 裝置的狀態。這項工具使用 RPC 用戶端與連線至開發環境的 Matter 裝置進行通訊。

虛擬裝置控制器

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

您可以透過虛擬裝置控制器圖形使用者介面 (GUI) 與虛擬裝置互動。GUI 中的變更會影響基礎資料模型。虛擬裝置控制器目前支援調光燈光裝置類型。

安裝虛擬裝置控制器

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

如果在未提供任何引數的情況下啟動控制器，系統將使用 localhost 通訊埠 33000 進行網路通訊端選項。控制器成功連線到虛擬裝置後，畫面會顯示裝置狀態的畫面：

虛擬裝置圖形使用者介面

當您對虛擬控制器應用程式進行變更時，應用程式會將請求傳送至裝置的 RPC 伺服器，並每秒輪詢一次 RPC 伺服器以擷取狀態。

「虛擬裝置控制器」應用程式也可以用來擷取裝置委任流程中的 QR 圖碼。按一下裝置圖片旁的 QR 圖碼圖示，即可顯示這部裝置的 QR 圖碼：

QR code

你可以使用這個 QR 圖碼委任裝置。

6. 委任裝置

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

Nest Hub

必須為 Matter 布料提供裝置。這款 Google Nest 裝置 (如 Nest Hub (第 2 代) 不僅支援 Matter，還能做為支援 Thread 裝置的邊界路由器，也能做為轉送智慧型住宅意圖的本機執行路徑。

開始修訂佣金流程之前，請先檢查下列事項：

  • 你用於中心的 Google 帳戶是你在 Google Home 控制台登入時使用的 Google 帳戶。
  • 集線器和您用來執行虛擬 Matter 的電腦已連上相同的 Wi-Fi 網路。
  • 集線器採用與 Google Home 應用程式相同的結構 (Google Home 圖表中的「房屋」代表您的結構)。

取得 QR 圖碼

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

執行佣金作業

  1. 開啟 Google Home 應用程式。
  2. 輕觸左上角的「+」圖示。
  3. 輕觸「設定裝置」。
  4. 輕觸 [新裝置]。
  5. 選取住家，然後輕觸 [下一步]。
  6. Google Home 應用程式會掃描你的裝置。如果出現「找到 Matter 裝置...」訊息時，請輕觸 [是]。否則，請輕觸 [設定其他裝置]，然後從裝置清單中選取 [案件裝置]。
  7. 將相機鏡頭對準裝置的 QR 圖碼或網站產生的 QR 圖碼。
  8. 按照 Google Home 應用程式流程所述，繼續進行配對程序。

完成這些步驟後，Matter 虛擬裝置應該就會成功生效，並應以新圖示顯示在 Google Home 應用程式中。

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

疑難排解

發生「連線問題」或「無法聯絡 Google」的錯誤訊息時導致佣金失敗

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

長時間掃描「正在掃描您的裝置」後，即無法正常運作

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，請探索以下參考資料：