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

1. はじめに

Matter は、スマート デバイスの開発に刺激的な機会をもたらす接続プロトコルです。この Codelab では、Matter SDK のリソースを使用して、初めての Matter デバイスを作成します。

Matter について詳しくは、Google Home Developer Center または Connectivity Standards Alliance のウェブサイトをご覧ください。

学習内容

  • Matter ビルド環境のセットアップ方法
  • パソコンで動作する仮想 Matter デバイスを作成する方法
  • Google Home で Matter 仮想デバイスをコミッショニングして操作する方法

必要なもの

  • ハブ: Matter に対応している Google Nest デバイス（Google Nest Hub（第 2 世代）など）。
  • X11 ウィンドウ システムを実行している Linux マシン。
  • Docker
  • Git
  • Linux の基本的な知識。
    • この Codelab のすべてのコマンドで想定するシェルは BASH です。

2.環境を設定する

ハードウェアを確認する

この Docker インストールでは、Windows パソコンと macOS パソコンはサポートされていません。macOS に Matter を手動でインストールしてビルドすることもできます。

また、以下の手順は Linux マシンで X11 ウィンドウ システムが実行されていることを前提としています。Linux マシンで Wayland を実行している場合は、X.Org もインストールされていることを確認します。

開発環境をセットアップする

  1. Docker Engine をインストールします（Docker デスクトップは使用しないでください）。
  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:66まず、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 レジストリから pull します。
  • --ipc=host により、Docker はプロセス間通信の名前空間をホストマシンと共有できます。
  • --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 は、Matter と Google Home の統合を管理するウェブ アプリケーションです。

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

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

まず、Google Home デベロッパー コンソールに移動します。

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

4. デバイスの構築

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

Chef には次のような特徴があります。

  • ターミナル インターフェースと examples/shell アプリにあるラッピング機能を提供するサンプルアプリです。
  • 「Convention-over-Configuration」の原則を採用し、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 に接続するため、Google Home アプリについて説明します。

デバイスを停止する

デバイスを停止する必要がある場合は、Ctrl+C キーを押してプログラムを終了できます。アプリが終了しない場合は、Ctrl+\ も使用する必要があります。

仮想デバイスの認証情報は、/tmp/ ディレクトリの chip 接頭辞で始まるファイルに保存されます。

設定プロセスを最初からやり直す場合は、次のコマンドを実行してこれらのファイルを削除する必要があります。

$ rm /tmp/chip*

5. デバイスをコミッショニングする

注: この手順は、Google Home Console ですでにプロジェクトをセットアップしている場合にのみ有効です。

Google Nest Hub

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

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

試運転プロセスを開始する前に、以下の点をご確認ください。

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

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 コンソールで正しい 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 について詳しくは、以下の参考資料をご覧ください。