Matter 仮想デバイスを作成する

1. はじめに

Matter は、スマート デバイスの開発に大きな可能性をもたらす接続プロトコルです。この Codelab では、Matter SDK のリソースを使用して、初めての Matter デバイスを構築します。

Matter について詳しくは、Google Home デベロッパー センターまたは Connectivity Standards Alliance のウェブサイトをご覧ください。

学習内容

  • Matter ビルド環境のセットアップ方法
  • パソコンで実行される仮想 Matter デバイスをビルドする方法
  • Google Home で仮想 Matter デバイスをコミッショニングして制御する方法

必要なもの

  • ハブ。これは、Google Nest Hub（第 2 世代）など、Matter に対応している Google Nest デバイスです。
  • X11 ウィンドウ システムを実行している Linux マシン。
  • Docker。
  • Git
  • Linux の基本的な知識。
    • この Codelab のすべてのコマンドは 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
    同じ commit を使用している場合は、ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications: と表示されます。
    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 レジストリからイメージを pull し、指定されたイメージを実行します。
  • --ipc=host を使用すると、Docker はプロセス間通信 Namespace をホストマシンと共有できます。
  • --net=host を使用すると、Docker はコンテナ内でホストのネットワーク スタックを使用できます。これは、ホストからコンテナに mDNS トラフィックを渡し、ホストの X11 ディスプレイを共有するために必要です。
  • -e DISPLAY は $DISPLAY をホストにエクスポートし、システム グラフィック インターフェースへのアクセスを提供します。これは、Matter クラスタの編集時に ZAP ツールを実行するために必要です。
  • -it は、バックグラウンド プロセスとしてではなく、インタラクティブ ターミナル（tty）で Docker を実行します。
  • --mount は、前にチェックアウトした SDK をコンテナにマウントします。
  • --workdir は、起動時に作業ディレクトリをマウントされた SDK ディレクトリに設定します。

必要に応じて、2 番目のターミナル セッション インスタンスを実行できます。

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 Developer Console は、Google Home との Matter 統合を管理するウェブ アプリケーションです。

Connectivity Standards Alliance（Alliance）の Matter 認証に合格した Matter デバイスは、Google Home エコシステムで動作します。認証されていない開発中のデバイスは、特定の条件下で Google Home エコシステムでコミッショニングできます。詳しくは、ペア設定の制限をご覧ください。

デベロッパー プロジェクトを作成する

まず、Google Home Developer Console にアクセスします。

  1. [プロジェクトの作成] をクリックします。
  2. 一意のプロジェクト名を入力し、[プロジェクトを作成] をクリックします。 [新しいプロジェクトを作成] ダイアログ
  3. [+ 統合を追加] をクリックすると、Matter リソース画面に移動します。この画面では、Matter 開発ドキュメントを表示したり、一部のツールについて確認したりできます。
  4. 続行する準備ができたら、[次へ: 開発] をクリックします。Matter チェックリスト ページが表示されます。
  5. [次へ: 設定] をクリックします。
  6. [設定] ページで、[プロダクト名] を入力します。
  7. [デバイスの種類を選択] をクリックし、プルダウン メニューからデバイスの種類（この場合は Light）を選択します。
  8. [Vendor ID (VID)] で [Test VID] を選択し、[Test VID] プルダウン メニューから 0xFFF1 を選択します。[Product ID (PID)] に 0x8000 と入力し、[Save & continue] をクリックします。次のページで [Save] をクリックします。これらの VID/PID 値を正確に使用してください。後の Codelab の手順で必要になります。
    プロジェクトの設定
  9. これで、[Matter 統合] に統合が表示されます。
  10. ハブを再起動して、最新の Matter 統合プロジェクト構成が確実に受信されるようにします。後で VID または PID を変更する必要がある場合は、変更を有効にするためにプロジェクトを保存した後で再起動する必要があります。再起動の手順については、Google Nest デバイスまたは Google Wifi デバイスを再起動するをご覧ください。

4. デバイスをビルドする

Matter のすべての例は、GitHub リポジトリの examples フォルダにあります。いくつかのサンプルが用意されていますが、この Codelab では Chef に焦点を当てます。

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: ターゲット プラットフォーム。サポートされているプラットフォームは、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 Developer Console でプロジェクトをすでに設定している場合にのみ成功します。

Google Nest Hub

Matter ファブリックでデバイスをコミッショニングするには、ハブが必要です。これは、Matter をサポートし、Thread 対応デバイスのボーダー ルーターとスマートホーム インテントのルーティングのローカル フルフィルメント パスの両方として機能する Google Nest デバイス（Google Nest Hub（第 2 世代）など）です。

Matter に対応しているハブについては、こちらのリストをご覧ください。

コミッショニング プロセスを開始する前に、次のことを確認してください。

  • ハブは、Google Home Console へのログインに使用したのと同じ Google アカウントとペア設定されています。
  • ハブが、Virtual Matter Device の実行に使用しているパソコンと同じ Wi-Fi ネットワークに接続されている。
  • ハブが Google Home アプリで使用している同じストラクチャにある（Google Home グラフの「家」はストラクチャを表します）。

QR コードを取得する

コミッショニング プロセスでは、QR コードで提供される Matter のオンボーディング情報が必要です。Matter アプリケーションのコンソール出力を調べます。ここには、コミッショニングに関連する QR コードのリンクが含まれています。

コミッション オペレーションを実行する

  1. Google Home アプリを開きます。
  2. 左上の + をタップします。
  3. [デバイスのセットアップ] をタップします。
  4. [新しいデバイス] をタップします。
  5. 家を選択して [次へ] をタップします。
  6. Google Home アプリがデバイスをスキャンします。「Matter デバイスが見つかりました」というメッセージが表示されたら、[はい] をタップします。それ以外の場合は、[別のデバイスをセットアップ] をタップし、デバイスのリストから [Matter デバイス] を選択します。
  7. デバイスの QR コードまたはウェブサイトで生成された QR コードにカメラを向けます。
  8. Google Home アプリのフローに沿ってペア設定プロセスを続行します。

これらの手順を完了すると、Matter 仮想デバイスが正常にコミッショニングされ、Google Home アプリに新しいアイコンとして表示されます。

Google Home アプリでペア設定された電球

トラブルシューティング

「接続の問題」または「Google に接続できませんでした」というエラー メッセージが表示されてコミッショニングが失敗する

  • Google Home Console で正しい 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 デバイスが作成されました。誠にありがとうございます。

この Codelab では、以下について学びました。

  • Matter 開発環境をインストールします。
  • Matter 仮想デバイスをビルドして実行する。
  • Google Home から仮想デバイスをコミッショニングして制御する。

Matter について詳しくは、以下のリファレンスをご覧ください。