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

1. はじめに

Matter は、スマート デバイスの開発にすばらしい機会をもたらす接続プロトコルです。この Codelab では、事前構成済みの Docker イメージで提供される SDK と依存関係を使用して、最初の Matter デバイスをビルドします。

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

学習内容

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

必要なもの

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 イメージを pull します。ターミナル ウィンドウで、
    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 Window System はポート 1000 でローカルホストからの接続を受信できるため、グラフィック ユーザー インターフェースを使用できます。
  • docker run … image は指定されたイメージを実行し、必要に応じて Docker レジストリから pull します。
  • --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 の統合を管理するウェブ アプリケーションです。

接続規格 Alliance（Alliance）Matter 認定に合格した Matter デバイスは、Google Home エコシステムで動作します。認定を受けていない開発中のデバイスは、特定の条件下で Google Home エコシステム内で委託することができます。詳しくは、ペア設定の制限をご覧ください。

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

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

  1. [プロジェクトの管理] ページで、[プロジェクトを作成] をクリックします。
    Google Home デベロッパー センター
  2. [スタートガイド] ページで、[プロジェクトを作成] をクリックします。

  1. 一意のプロジェクト名を入力し、[Create new project（新しいプロジェクトを作成）] をクリックします。 [Create new project] ダイアログ
  2. [+ 統合を追加] をクリックすると [Matter リソース] 画面が表示され、そこで Matter 開発ドキュメントを表示し、いくつかのツールを読むことができます。
  3. 続行する準備ができたら、[次へ: 開発] をクリックして [Matter のチェックリスト] ページを表示します。
  4. [次へ: 設定] をクリックします。
  5. [設定] ページで、プロダクト名を入力します。
  6. [デバイスタイプを選択] をクリックし、プルダウン メニューからデバイスタイプを選択します（この場合は Light）。
  7. ベンダー ID（VID）で、[Test VID] を選択し、[Test VID] プルダウン メニューから [0xFFF1] を選択します。[プロダクト ID（PID）] に「0x8000」と入力し、[保存して次へ] をクリックしてから、次のページで [保存] をクリックします。
    プロジェクトの設定
  8. これで、Matter の統合の下に 1 つの Matter デバイスが表示されるようになります。Matter の統合
  9. ハブを再起動して、最新の 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. 仮想デバイス コントローラ

仮想デバイス コントローラは、仮想 Matter デバイスの状態を制御して表示するグラフィカル ユーザー インターフェースを提供するスタンドアロン アプリです。RPC クライアントを使用して、開発環境に接続されている Matter デバイスと通信します。

仮想デバイス コントローラ

仮想デバイス コントローラは、仮想デバイスを視覚的に表示します。

Virtual Device Controller のグラフィック ユーザー インターフェース（GUI）を使用して仮想デバイスを操作できます。GUI の変更は、基盤となるデータモデルに影響します。現在、仮想デバイス コントローラは調光モードのデバイスタイプをサポートしています。

仮想デバイス コントローラをインストールする

仮想デバイス コントローラは、Ubuntu LTS 20.04 Docker コンテナにプリインストールされています。

仮想デバイス コントローラを実行する

2 つ目のターミナル セッション インスタンスを作成します。

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 サーバーにリクエストを送信し、1 秒に 1 回 RPC サーバーにポーリングを行って状態を取得します。

仮想デバイス コントローラ アプリを使用して、デバイスのコミッショニング フローで QR コードを取得することもできます。デバイス画像の横にある QR コードアイコンをクリックして、このデバイスの QR コードを表示します。

QR コード

この QR コードを使用して、デバイスをコミッショニングできます。

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

注: このステップは、Google Home デベロッパー コンソールですでにプロジェクトをセットアップしている場合にのみ成功します。

Google Nest Hub

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

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

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

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

QR コードを取得する

コミッショニング プロセスを行うには、QR コードを使用して提供される 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 の組み合わせを使用する他のプロジェクトがないことを確認してください。

「デバイスのスキャン」を長時間実行した後にコミッショニングが失敗する

  • パソコンのファイアウォールがオフで、仮想デバイスを実行していることを確認します。
  • パソコンで 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 デバイスが正常に作成されました。でも使用できます。

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

  • 事前にパッケージ化された Docker イメージを使用して、Matter 開発環境をインストールする。
  • Matter 仮想デバイスをビルドして実行します。
  • Google Home から仮想デバイスをコミッションして操作します。

Matter について詳しくは、以下の参考資料をご覧ください。